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.

정보

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

URI(Uniform Resource Identifiers)

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

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

URI path

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

URI query

HTTP Verb

https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods

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

정보

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

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

경고

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

따라서 일반적인 에러코드 의미에서 조금 벗어나더라도 상황에 따라 로그인 관련은 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

정보

인증(Authentication): 사용자 신원 확인, AuthN
인가(Authorization): 리소스에 대한 접근 권한 획득, AuthZ

5xx Server Error

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

500 Internal Server Error

REST(REpresentational State Transfer)​

URI(Uniform Resource Identifiers)​

URI path​

URI query​

HTTP Verb​

HTTP status codes​

2xx Success​

4xx Client Error​

5xx Server Error​