HTTP
- GET, POST, PUT, PATCH, DELETE 메서드를 일반적으로 사용한다.
- GET : Read
- POST : Create
- PUT, PATCH : Update
- DELETE : Delete
- 리소스와 행위는 URI와 HTTP 메서드를 통해 표현한다.
- GET /books/1 : 1번 책을 조회
- POST /books : 책을 생성
- PUT /books/1 : 1번 책을 수정
- DELETE /books/1 : 1번 책을 삭제
- HTTP 응답의 상태 코드
- 1xx~ : 정보
- 2xx~ : 성공
- 3xx~ : 리다이렉션
- 4xx~ : 클라이언트 오류
- 5xx~ : 서버 오류
ContentType : application/json
대부분의 REST API는 JSON 형식을 사용하고 있다.
Response를 JSON으로 받기 위해 HTTP 헤더에 ContentType : applicaiton/json를 삽입한다.
아래와 같이 가독성이 높아지며 만약 데이터가 많다면 왜 헤더에 JSON 형식을 지정해줘야하는지 알 수 있다.
not using applicaiton/json
Resposne > {"userId" : a, "userName" : "Jack", "userAge" : 11}
using applicaiton/json
Resposne >
{
"userId" : a,
"userName" : "Jack",
"userAge" : 11
}URI에 동사를 사용하지 말 것
작업에 대한 정보를 URI가 아닌 HTTP 메서드를 사용하여 표현하라.
HTTP 메서드는 현재 리소스의 작업 상태에 대해 명확하게 설명하기에 부족하지 않다.
책 표지 생성 Case
**BAD**
GET: /books/createBook
**GOOD**
POST: /books/book
책 표지 수정 Case
**BAD**
GET: /books/updateBook/1
**GOOD**
PUT: /books/book/1자원에 대해 복수 사용
1. book/2
2. books/2단수형보다 복수형의 경우가 모든 유형의 API 엔드포인트를 표현하기에 적합하다.
위 상황을 예로 1번의 경우 2번의 책 한권을 받고자 하는 것을 예상할 수 있지만
만약 book/2가 아닌 book/라면 애매하다. 한 권인지 여러 권인지..
이러한 모호함을 방지하고 일관성을 유지하기 위해 대부분의 경우에 복수형을 사용한다.
Response에 세부 오류 정보를 반환
API 서버에서 오류를 처리할 때, 클라이언트가 명확하게 파악하고 디버깅을 손쉽게 하기 위해 JSON 본문에 오류 세부 정보와 문제가 되는 필드를 포함해주면 좋다.
{
"error": "잘못된 요청입니다.",
"detail": {
"bookId": "책 ID 필드는 필수입니다."
}
}HTTP 상태 코드 사용에 주의
먼저, 최악의 경우 HTTP 상태 코드 200과 함께 오류 응답을 반환하는 것이다.
**BAD**
HTTP/1.1 200 OK
{
"error": "잘못된 요청입니다.",
"detail": {
"bookId": "책 ID 필드는 필수입니다."
}
}
**BAD**
HTTP/1.1 401 BAD REQUEST
{
"error": "잘못된 요청입니다.",
"detail": {
"bookId": "책 ID 필드는 필수입니다."
}
}HTTP Status Code 200은 성공을 의미하는데, 서버에선 오류 정보를 반환하고 있다.
이는 잘못된 경우이고 클라이언트는 API에 대해 확신할 수 없게 된다.
적절한 HTTP 상태 코드를 활용하여 응답을 내려줘야 클라이언트가 헷갈리지 않는다.
HTTP 상태 코드를 일관되게 사용하자
클라이언트가 상태 코드로 요청에 상태를 먼저 파악할 수 있어야한다.
만약 이 관습에 벗어난다면 따로 문서화해두어야 서로 헷갈리지 않는다.
일반적으로 다음 패턴을 고수한다.
GET : 200 OK
PUT : 200 OK
POST : 201 CREATED
PATCH : 200 OK
DELETE : 204 No Content리소스를 중첩하지 말자
책의 저자가 Morgan인 책 정보를 조회한다고 가정해보자.
1. GET : /authors/Morgan/books
2. GET : /books?authors=Morgan두 API는 서로 같은 행위를 하고 동일한 응답을 받는다.
일대다 관계를 나타내기 때문에 1번을 지향하는 개발자도 있지만
쿼리 스트링을 통해 리소스를 필터링해주는 방법을 권장한다.
https://abdulrwahab.medium.com/api-architecture-best-practices-for-designing-rest-apis-bf907025f5f
