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): 리소스 조회
  • PATCH(Update): 리소스 일부 업데이트
    • RequestBody 존재 가능
  • PUT(Replace): 리소스 전체 업데이트
    • 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 등과 함께 본문에 커스텀 코드와 메시지로 다른 에러를 표현할 수 있습니다.

{
	"status": 400,
	"errors": [
		{
			"code": 1,
			"message": "validation error"
		}
	]
}
warning

클라이언트가 미들웨어를 사용하여 특정 상태 코드에 따라 일괄적인 에러처리를 할 수도 있습니다.

따라서 일반적인 에러코드 의미에서 조금 벗어나더라도 상황에 따라 로그인 관련은 401, 권한 관련은 403, 그 외 서버에서 인지한 에러는 400으로 통일해서 처리할 수도 있습니다.

  • 400 Bad Request
    • 잘못된 요청 형식 등 서버가 처리할 수 없음
    • 요청은 올바르지만, 유효성 검사 실패 등의 이유로 처리할 수 없음(422 Unprocessable Entity)
    • 서버의 현재 상태와 충돌(409 Conflict)
  • 401 Unauthorized: 인증(Authentication) 실패
    • 로그인 하지 않은 경우
    • 세션 또는 JWT 토큰 만료
  • 403 Forbidden: 인가(Authorization) 실패
    • 로그인은 했지만 권한이 없는 경우
    • 읽기 권한은 있지만 쓰기 권한이 없는 경우
  • 404 Not Found: 리소스를 찾을 수 없음
    • 리소스가 존재하지 않는 경우
    • 존재는 하지만 읽기, 쓰기 권한이 없는 경우
  • 429 Too Many Requests
info
  • 인증(Authentication): 사용자 신원 확인, AuthN
  • 인가(Authorization): 리소스에 대한 접근 권한 획득, AuthZ

5xx Server Error​

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

  • 500 Internal Server Error