✨ RESTful API란?
✨ RESTful API 설계 규칙
✨ Path parameter, Query parameter
✨ RESTful API?
API 시스템을 구현하기 위한 아키텍쳐(Graphql, SOAP, GRPC, REST, ... etc) 중에 가장 널리 사용되는 형식
REpresentational State Transfer
웹상에서 사용되는 여러 리소스를 HTTP URI로 표현하고 그 리소스에 대한 행위를 HTTP Method로 정의하는 방식
HTTP Method로 정의하는 방식
즉, (HTTP URI로 정의된)리소스를 어떻게 한다(Method + Payload)를 구조적으로 깔끔하게 표현하는것
→ 서로 사전에 정한 규칙에 의거하여 요청하는 바가 무엇인지 응답으로 전송되는 것이 어떤 것인지 명확하고 간략하게 드러낼 수 있다.
→ 진입장벽이 다른 시스템에 비해 낮고 학습커브가 짧다
→ 프로세싱이 덜 필요하므로 빠른 송신이 가능하다
장점 : self-descriptiveness, RESTful API로 그 자체만으로도 API의 목적이 쉽게 이해 된다.
단점 : 표준규약이 없어, 안티패턴으로 작성되는 경우가 흔하다.
기본 배경 지식
URI / HTTP Method / Payload
URI (Uniform Resource Identifier)
해당 사이트의 특정 자원의 위치를 나타내는 유일한 주소
HTTP Method
HTTP request가 의도하는 action을 정의한 것
ex) GET, POST, PUT, DELETE
payload
HTTP request에서 server로 보내는 데이터 (body)
✨RESTful API 설계 규칙
-
URI 정보를 명확하게 표현해야 한다.
→ resource는 명사를 사용한다.
ex)GET/user/1 → GET/users/1
-
resource에 대한 행위를 HTTP Method
(GET, POST, PUT, DELETE)로 표현한다.
→ URI에 불필요하게 동사가 포함되서는 안된다.
ex) GET/user/show/1 -> GET/users/1
POST insert/user/2 -> POST users/2
-
resource 사이에 연관 관계가 있는 경우
→ resource/users/{user_id}/profile -
파일의 경우 payload의 포맷을 나타내기 위한 파일 확장자를 URI에 포함시키지 않는다.
-
GET user/1/profile-photo.jpg (X)
ex) GET user/1/profile-photo
ex) payload의 포맷은 headers에 accept를 사용한다. -
URI는 / 구분자를 사용하여 자원의 계층 관계를 나타내는데 사용한다.
-
URI 마지막 문자로 / 를 포함하지 않는다.
ex) GET users/portfolios/ (X) -
불가피하게 URI가 길어지는 경우 - 을 사용하여 가독성을 높인다. ( _는 사용하지 않는다 )
-
URI 경로에는 대문자 사용을 피하도록 규정하고 있다.
✨ Path parameter vs Query parameter
Path parameter
경로를 변수로 사용해 URI에 접근하는 방식
GET https://10.58.4.1:8000/products/1
PATCH https://10.58.4.1:8000/products/1
Query Parameter
경로 뒤에 입력 데이터를 함께 제공하는 방식
? 이후 부분을 query string이라고 한다.
key, value쌍으로 이루어진다.
Query parameter - Filtering
GET / products?price=3000원
GET / products?price=3000원&name=사과
Query parameter - Ordering
GET / products?ordering=-id
Query parameter - Pagination
GET / products?offset=0&limit=100
GET /products/3 vs GET /products?id=3
똑같은 결과가 나오는데 언제 어떤 방법을 사용해야 할까?
Path parameter
→ resource가 있는지 없는지 식별해야하는 상황에서 적합
Query parameters
→ Filtering, Sorting, Searching에 적합
