RESTful API by 알코

Seon Kim·2024년 6월 10일

API는 두 소프트웨어의 소통 : A가 이렇게 요청하면 B는 이렇게 응답한다는 약속

Rest API는 A가 어떤 방식으로 요청하고,B가 어떤 방식으로 응답할 지 지정해 놓은 다양한 형식들 중 하나.

요세 가장 많이 사용하는 방식이다. 왜 좋은 API형식인지 ??

CRUD 네 가지를 통해서

Create : 정보를 생성해서 넣는 역할

Read : 조회

Update : 정보 변경

Delete : 정보 삭제

→ 대부분의 서비스들이 API를 통해 하는 일들은 이 4가지로 구성되어있다.

RESTful한 요청으로 작성하기

POST https://api.yalcobooks.com/v1/books
	새 책의 정보를 추가하기
GET https://api.yalcobooks.com/v1/books
	책의 정보 조회
GET https://api.yalcobooks.com/v1/books/1
	색인번호가 1인 책의 정보 조회
PUT https://api.yalcobooks.com/v1/books/20
	색인번호가 20인 책의 정보 수정
PATCH https://api.yalcobooks.com/v1/books/7
	색인번호가 7인 책의 대여 상태 변경
DELETE https://api.yalcobooks.com/v1/books/123
	색인번호가 123책을 삭제하는 요청

각각이 CRUD 중 하나에 속해 있고, 이처럼 HTTP 프로토콜을 이용해서 URL 요청을 보낸다.

HTTP는 RESTful API의 필수요소는 아니지만, RESTful API의 조건을 구현하기 용이하기 때문에 현업에서 HTTP와 RESTful API를 같이 사용한다.

api : 무언가의 API로 사용되고 있다는 뜻
도메인은 서버의 주소
v1 : api의 변경사항이 생길 수 있기 때문에 버전 정보 제공
books : 어떤 데이터 정보인지를 확인할 수 있다.

RESTful API의 중요한 특징

URI는 이 요청이 “어떤 자원”에 관한 것인지 표현해야 하고, 그것만 표현해야한다.
- 주소에서는 요청이 어떤 요청인지 나타내면 안된다.
- add, modify, delete 처럼 그것으로 무엇을 하는가를 나타내는 동사는 URI에 가능한 한 포함하면 안된다.
- 어떤 종류의 작업을 할지는 HTTP 메소드를 통해서 표현한다.
RESTful API의 요청과 응답에는 구조화된 데이터 표현이 가능하면서 가벼운 JSON이 많이 사용된다.
응답에 상태코드(Status Codes)
- 서버의 응답에는 요청을 처리한 결과를 알려주는 상태 코드가 담겨서 온다.
상태가 없는 통신 (Stateless)
- 클라이언트의 상태 정보가 서버에 저장시키지 않는 것
  - 즉, 서버는 클라이언트에 대해 아무것도 기억하지 말아야 한다는 것
    - 때문에 클라이언트의 요청은 몇 번째 반복되든, 필요한 모든 내용을 포함하고 있어야한다.
멱등성 (Idempoter)
- stateless와 간접적으로 연결되는 개념
  - 클라이언트가 같은 요청을 몇 번을 보내든 언제나 같은 답으로 돌아와야 한다.
    - 실제 데이터값이 바뀌었을 때를 제외하고는 항상 같은 값
Cacheability
- 클라이언트와 서버는 서로에 대해서는 기억하지 않아야 하지만, 자기가 어떤 응답을 보냈는지, 자기가 어떤 응답을 받았는지는 기억해야한다.
- 이처럼 한 번 얻어낸 데이터를 또 쓸 수 있도록 저장하는 것을 캐싱이라고 한다.

HTTP 메서드

GET, DELETE : 편지봉투

POST, PUT, PATCH : 소포 상자

RESTful API의 요청과 응답에는 구조화된 데이터 표현이 가능하면서 가벼운 JSON이 많이 사용된다.

[
    {
        "id": 1,
        "title": "Clean Code",
        "author": "Robert C. Martin",
        "published_date": "2008-08-01",
        "isbn": "9780132350884",
        "status": "available"
    },
    {
        "id": 2,
        "title": "The Pragmatic Programmer",
        "author": "Andy Hunt and Dave Thomas",
        "published_date": "1999-10-30",
        "isbn": "9780201616224",
        "status": "rented"
    },
    {
        "id": 3,
        "title": "Design Patterns: Elements of Reusable Object-Oriented Software",
        "author": "Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides",
        "published_date": "1994-10-31",
        "isbn": "9780201633610",
        "status": "available"
    }
]

query parameter : 특정 조건으로 조회

status가 available한 것만 조회가 된다. https://api.yalcobooks.com/v1/books?status=available

[
    {
        "id": 1,
        "title": "Clean Code",
        "author": "Robert C. Martin",
        "published_date": "2008-08-01",
        "isbn": "9780132350884",
        "status": "available"
    },
    {
        "id": 3,
        "title": "Design Patterns: Elements of Reusable Object-Oriented Software",
        "author": "Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides",
        "published_date": "1994-10-31",
        "isbn": "9780201633610",
        "status": "available"
    }
]

고유 식별자 : 특정 책의 정보 요청

고유 식별자를 사용하기 위해서는 데이터베이스를 구축할 때 반드시 각 항목마다의 고유값이 만들어지도록 설계해야한다.

HATEOAS

각 요청의 응답에, 가용한 다른 요청들의 정보를 포함시키는 것

리소스에 관해서 다른 리소스(링크)를 같이 요청하여 첨부 할 수 있는 기능

이 링크 정보들을 통해서, 개발자는 API 문서들을 다 뒤져보지 않아도 다음에 어떤 요청을 보낼 수 있는지 살펴볼 수 있다.

이 부분의 API의 세부사항이 변경되더라도, 클라이언트에서 이 정보를 참조하게 만들면 클라이언트의 코드를 고칠 필요도 없어진다.

각 리소스는 그것의 상위 또는 하위 리소스를 가질 수 있다.

예시로 책의 경우, 각각에 대한 리뷰들이 달릴 수 있으니 리뷰를 하위 리소스로 갖는다고 할 수 있다. GET https://api.yalcobooks.com/v1/books/reviews → 색인번호가 1인 책에 해당하는 리뷰들을 조회하려면 위와 같이 URI를 작성하고, 이를 통해 각 요청이 응답으로 받고자 하는 정보들 뿐 아니라, 리소스들이 서로 어떤 관계를 갖는지 이 URI를 통해 쉽게 파악할 수 있다.

{
    "bookId": 1,
    "reviews": [
        {
            "reviewId": 101,
            "userId": "user123",
            "rating": 5,
            "comment": "This book is a must-read for software engineers!",
            "date": "2023-01-15"
        },
        {
            "reviewId": 102,
            "userId": "user456",
            "rating": 4,
            "comment": "Very insightful, though some examples are outdated.",
            "date": "2023-01-20"
        }
    ]
}

POST

Create에 해당하는 http 메소드로 정보를 입력하는데 사용되고, 정보를 입력하기 때문에 용량이 클 수도 있기 때문에 GET과는 다르게 소포상자 느낌이 된다.
- https://api.yalcobooks.com/v1/books로 작성했을 때 새 책의 등록은 해당 요청이 어느 리소스에 데이터를 추가하는 것인지 명시하면된다.
- POST, PUT, PATCH와 같은 소포 상자에는 body라는 공간이 존재하여 이곳에 용량이 큰 데이터를 실어보낼 수 있다.

PUT vs PATCH : Update

put과 patch의 차이는 전부 갈아엎느냐, 부분적으로 수정하느냐의 차이가 있다.
수정은 특정 항목에 관한 것이기 때문에 어떤 책인지를 명시하는 식별자를 붙여주어야한다.
- https://api.yalcobooks.com/v1/books/1 1이 식별자
PUT : 특정 항목의 정보를 전체적으로 대체할 때 사용
- 전체적으로 대체하기 때문에 모든 정보를 body에 실어서 보내야한다.
- 결과로는 해당 요청의 실행 성공 여부를 보내줄 수도 있다.
```
{
	"message" : "Book updated successfully."
}
```
PATCH : 부분적인 부분에 대해서만 대체할 때 사용
- status를 rented로 변경해주고 싶으면
```
{
 "status" : "rented"
}
```
- 만약에 PUT으로 처리하게 되면 다른 값들은 null로 되어서 status 정보만 body에 남는다.

Delete

URI에는 삭제할 책의 식별자를 작성해 주면 그 식별자를 삭제시켜준다.
- https://api.yalcobooks.com/v1/books/1
결과로는 실행 결과의 성공 여부를 보내주면 된다.

{
	"message" : "Book deleted successfully."
}

Seon Kim

개발 어린이

이전 포스트

논리적 vs 물리적

다음 포스트