API 명세서

API 명세

인가를 위한 Authorization 헤더

Autorization: Bearer {access_token}

• 인가가 필요한 API에 요청 시 Authorization request header 필수
• access token(JWT)를 통해 인가 수행, Bearer 토큰 형식

공통 예외 응답 포맷

{
    "message": "사용자가 존재하지 않음"
}

• 비즈니스 로직상 예외 - 예외 상황 메시지 제공

{
    "message": {
        "birth": "생년월일은 필수값",
	"gender": "성별은 필수값"
    }
}

• 요청값 예외 : 문제의 요청 필드명 : 예외 메시지와 같은 Map 형태로 제공

명세서

• Swagger
• Postman

RETS API Design Rule

URL은 /로 끝나지 않게 한다.

마지막 슬래시는 불필요하며 일관성을 해친다.

적합 예시

http://api.example.com/users

부적합 예시

http://api.example.com/users/

단어 구분은 -를 사용한다.

하이픈이 URL에서 가장 가독성이 좋다.

적합 예시

http://api.example.com/talk-topics

부적합 예시

http://api.example.com/talk_topics

소문자를 사용한다.

대소문자 구분으로 인한 혼란을 방지한다.

적합 예시

http://api.example.com/user-profiles

부적합 예시

http://api.example.com/User-Profiles

동사 사용을 피한다.

HTTP 메서드가 동작을 나타내므로 URL에는 리소스만 표현한다. (예외 존재)

적합 예시

http://api.example.com/user-profiles

부적합 예시

http://api.example.com/User-Profiles

파일 확장자를 URL에 포함하지 않는다.

확장자 대신 Accept 헤더를 사용한다.

적합 예시

GET /users/123/profile  
Accept: image/png

부적합 예시

GET /users/123/profile.png

복수형 명사를 사용한다.

일관성을 위해 리소스 컬렉션은 복수형을 사용한다.

적합 예시

GET /articles

부적합 예시

GET /article

검색, 정렬, 필터링은 쿼리 파라미터로 구현한다.

URL 구조를 단순하게 유지하고 유연성을 제공한다.

적합 예시

GET /articles?sort=date&filter=published

부적합 예시

GET /articles/sort/date/filter/published

CRUD 함수명을 사용하지 않는다.

HTTP 메서드가 동작을 나타내므로 중복을 피한다.

적합 예시

POST /articles

부적합 예시

POST /articles/create

관계를 나타낼 때는 네스팅을 사용한다.

리소스 간의 관계를 명확히 표현한다.

적합 예시

GET /users/123/articles

부적합 예시

GET /articles?userId=123

상태 코드를 적절히 사용한다.

HTTP 상태 코드로 요청 결과를 명확히 전달한다.

적합 예시

• 요청이 정상 수행되었으며 응답 데이터가 존재 : 200 OK
• 잘못된 요청 값이 요청에 포함됨 : 400 Bad Request

부적합 예시

항상 200 OK 사용

응답에 적절한 헤더를 포함한다.

클라이언트에게 응답 형식 정보를 제공한다.

적합 예시

Content-Type : application/json

부적합 예시

헤더 없이 응답

에러 응답의 일관된 구조를 유지한다.

클라이언트가 에러를 쉽게 처리할 수 있게 한다.

적합 예시

{"error": "Invalid token", "code": "AUTH001"}

부적합 예시

비일관적인 에러 응답 형식

페이지네이션 정보를 제공한다.

대량의 데이터를 효율적으로 처리할 수 있게 한다.

적합 예시

GET /articles?page=2&per_page=100

부적합 예시

페이지 정보 없는 대량 데이터 응답