RESTful API

RESTful API

RESTful API는 현재 사용되고 있는 API 설계 규칙 중 가장 널리 사용되고 있는 규칙이다.

API 아키텍쳐에는 :
GraphQL, SOAP, GRPC, REST 등이 있다.

REST??

: Representational State Transfer 의 약어로
웹상의 여러 리소스를 HTTP URI로 표현하고 그 리소스에 대한 행위를 HTTP Method로 정의하는 방식이다.
- 리소스(HTTP URI로 정의된) 를 어떻게 한다(Method + Payload)에 대한 것을 구조적으로 깔끔하게 표현한다.

왜 REST를 쓰는가

1. 비싼 툴이 필요없다.
   (지금 쓰는 수준의 파이썬, 장고 수준에서 처리가 가능하다.)
2. 진입 장벽이 낮다. 학습 용이성.
3. 프로세싱이 적고 빠른편이다.

GraphQL 참고
: 페이스북에서 만든 아키텍쳐로, 엄격하게 정의된 endpoint에 요청하는 대신 한번의 요청으로 정확히 가져오고 싶은 데이터를 가져올 수 있게하는 쿼리를 보낼 수 있다.

SOAP 참고
: REST와 다르게 프로토콜이다!
레거시 시스템에서 주로 준수하고 있으며, REST에 비해 진입장벽이 높고 복잡하다.

REST가 일반적으로 가장 기초이며, 널리 통용되지만, 기업의 시스템이나 개발 환경에 따라 사용하는 아키텍쳐는 얼마든지 바뀔 수 있음을 생각하다.

REST의 특징

http 통신 구성

• URI(Uniform Resource Identifier)
  - 해당 사이트의 특정 자원의 위치를 나타내는 유일한 주소
• HTTP Method
  - HTTP request가 의도하는 action을 정의한 것
• Payload
  - HTTP request에서 server로 보내는 데이터 (body)

RESTful API 규칙

• URI 정보를 명확하게 표현한다.
  - resource는 명사를 사용한다. (대상의 집합체는 복수형태로)
  Ex) GET /user/1 -> GET /users/1

• resource에 대한 행위를 HTTP Method(GET, POST, PUT, DELETE)로서 표현한다.
  - URI에 HTTP Method가 표함되서는 안된다.
  Ex) GET delete/user/1 -> DELETE /users/1
  - URI에 동사가 포함되서는 안된다.
  Ex) GET /users/show/1 -> GET /users/1
  Ex) POST insert/user/2 -> POST /users/2

• resource 사이에 연관 관계가 있는 경우
  - /리소스/고유ID/관계 있는 리소스
  Ex) GET /users/{user_id}/profile

• 파일의 경우 payload의 포맷을 나타내기 위한 파일 확장자를 URI에 포함시키지 않는다.
  Ex) GET user/1/profile-photo.jpg (x)
  Ex) GET user/1/profile-photo
  (이때, payload의 포맷은 headers에 accept를 사용)

아래의 예제에서 첫번째 예제는 prroduct보다는 전체를 다 가져온다는 의미로 products를 쓰는 것이 더 적절하다.

Path/ Query parameter

Path parameter

end point에 길을 찾아가듯이 단계별로 타고 넘어간다.

상황에 따라 내가 필요한 정보를 Method로 요청한다.

path parameter로 원하는 resource만 제거할 수도 있다.
204 No content는 요청 정보가 없는 것이 아니라, 데이터가 지워져서 더 이상 없다는 의미이다.

Query parameter

Query parameter는 URI에 붙어 원하는 정보를 (Filtering, Sorting, Searching)할 수 있는 방법이다.

Path vs Query

이때는 Path parameter로 접근하는 방법이 더 적합하다.

Status Code

이런 end point로 Request를 받을 때 그 결과에 따라 적절한 code를 반환하는데, 이는 다음과 같다

참고 블로그