Skip to main content

RESTful API


REST(REpresentational state transfer)

The REST architectural style emphasises the scalability of interactions between components, uniform interfaces, independent deployment of components, and the creation of a layered architecture to facilitate caching components to reduce user-perceived latency, enforce security, and encapsulate legacy systems.

info

모든 API를 RESTful하게 정의하고 개발할 수 있는 부분은 그렇게 하면 좋겠지만, 잘 모르겠거나 애매한 부분이 있어서 어려운 것 같습니다.

URI(Uniform Resource Identifiers)

<schema>://<authority>/<path>[?<query>][#<fragment>]

  • /는 리소스 사이의 계층적 관계를 나타낼 때 사용
  • URI의 마지막에는 /를 붙이지 않음
  • -를 사용할 수 있음
  • _를 사용하지 않음
  • 대소문자를 구분, 일반적으로 소문자를 사용

URI path

  • Collection
    • 여러 리소스가 들어있는 하나의 디렉터리를 가리키는 리소스, 서버에서 관리
    • 복수 명사를 사용
    • Ex) /products
  • Document
    • 하나의 객체를 가리키는 리소스
    • 하위 리소스를 가질 수 있음
    • 단수 명사를 사용
    • Ex) /products/candy
  • Controller
    • 특정 동작을 실행하는 리소스
    • CRUD(Create, Read, Update, Delete)(HTTP Verb) 기능에 매핑 할 수 없는 경우에만 구현
    • 하위 리소스를 가질 수 없음
    • 동사를 사용
  • Store
    • Collection과 유사하지만 클라이언트가 관리
    • 복수 명사를 사용

URI query

HTTP Verb

  • POST(Create): 새로운 리소스 생성 또는 Controller 실행
    • RequestBody 존재 가능
    • 비멱등성
  • GET(Read): 리소스 조회
  • PUT(Update): 리소스 전체 업데이트
    • RequestBody 존재 가능
    • 멱등성
  • DELETE(Delete): 리소스 삭제

HTTP status codes

2xx Success

  • 200 OK
  • 201 Created: 리소스 생성
  • 202 Accepted: 요청은 성공했지만 지금 당장 결과를 알려줄 수 없음(Async)
  • 204 No Content: 본문 없음, 클라이언트가 다른 페이지로 이동할 필요 없음

4xx Client Error

info

상태 코드로 표현하기 어려운 경우가 있습니다. 그런 경우 400, 401, 403 등과 함께 본문에 커스텀 코드와 메시지로 다른 에러를 표현할 수 있습니다.

{
"code": 1,
"message": "Invalid Arguments"
}
  • 400 Bad Request: API 스펙에 맞지 않는 요청
  • 401 Unauthorized: 인증(Authentication) 실패
  • 403 Forbidden: 인가(Authorization)되지 않은 요청
  • 409 Conflict: 서버의 현재 상태와 충돌한 경우
info
  • 인증(Authentication): 사용자 신원 확인
  • 인가(Authorization): 리소스에 대한 접근 권한 획득

5xx Server Error

서버가 요청을 처리하지 못한 경우이며 해당 에러는 모두 로그로 남겨서 트래킹 할 수 있어야 합니다.

  • 500 Internal Server Error

Example

  • POST /auth/create
  • POST /auth/create-with-oauth
  • POST /auth/reset-password
  • POST /auth/delete
  • POST /auth/delete-with-oauth
  • POST /auth/signin
  • POST /auth/signin-with-oauth
  • POST /auth/refresh
  • POST /auth/signout
  • GET /auth/account
  • PUT /auth/account
  • POST /auth/mfa/send
  • POST /auth/mfa/verify