- RESTful API
- Path parameter와 Query parameter
RESTful API
REST(Representational State Transfer)
REST는 현재 가장 널리 사용되고 있는 API 설계 규칙이다. RESTful API는 REST 규칙을 지켜 설계된 API를 말한다. self-descriptiveness의 특징을 살려 직관적으로 개발자 사이의 의사소통을 수월하게 구성된 API는 통신 이해도를 높여준다.
즉, REST API란 REST하게 API를 서술하는 방법을 부르는 용어이다.
그렇다면 REST란 무엇인가?
- 자원을 설명으로 구분하여 해당 자원의 상태를 주고 받는 모든 것을 의미
- API 시스템을 구현하기 위한 다양한 아키텍처 중에 가장 널리 사용되는 형식 (REST, GraphQL, SOAP, ...)
- 즉, HTTP URI(Uniform Resource Identifier)를 통해 자원(Resource)을 명시하고, HTTP Method(POST, GET, PUT, DELETE, ...)를 통해 자원에 대한 요청을 처리하도록 설계된 아키텍처를 의미
REST API의 장단점
장점
- URI가 무엇을 의미하는지, request가 무엇을 요청하고 resopnse가 무엇을 응답받는지 자명하다. (Self-descriptiveness)
단점
- 표준 규약이 없어 안티 패턴(Ex. /products/all)으로 작성되는 경우가 흔함
RESTful API 설계 원칙
-
구성요소(클라이언트와 서버 등) 사이의 인터페이스는 일관돼야 한다는 원칙
=> 플랫폼에 무관하며, 특정 언어나 기술에 종속받지 않는 특징을 의미 -
URI는 동사를 제외한, 명사로 구성
=> [GET]/find/users/1 -> [GET]/users/1 -
Resource에 대한 행위를 HTTP method (GET, POST, PUT, DELETE)만으로 표현
=> [POST]post/reviews -> [POST]/reviews -
Resource 사이에 연관 관계 및 계층 관계가 있는 경우 '/'사용
=> [GET]/users/{user_id}/posts -
URI 마지막 문자로 '/'를 포함하지 않음
=> [GET]/users/portfolios/ -> [GET]/users/portfolios -
URI가 길어지는 경우 '-'을 사용하여 가독성을 높임
=> [GET]/users/1/ordered_items -> [GET]/users/1/ordered-items -
파일 확장자는 URI에 포함시키지 않고 파일의 확장자는 headers에 포함
=> [GET]/users/1/profile-photo.jpg -> [GET]/users/1/profile-photo -
응답 Response 의 Status code에 맞는 기본적인 규칙을 따름
Path parameter / Query parameter
Path parameter
위 그림처럼 GET 요청을 진행할 때
특정한 하나의 데이터 또는 정제되지 않은 데이터가 필요한 경우에 사용될 수 있다.
새로운 데이터를 추가하기 위해 POST 요청을 진행해보자
POST
name : '무농약 깐 생강', price : 3000원인 데이터를 추가해주었다.
PATCH
id가 1번인 상품에 대해 가격을 수정하기 위해 price : 1100원을 request body에 담아 요청하였다.
PUT
PATCH와 동일하게 수정을 요청하는 Method이다.
그러나 PATCH와 다른 점이 있다.
PUT은 특정 데이터를 저장하기 위해 모든 데이터를 전부 요청해야 한다.
//PUT
{
id : 1,
name : "무농약 깐 생강",
price : 1100
}그러나 PATCH는 수정하고 싶은 데이터만 전송한다.
//PATCH
{
price : 1100
}Query parameter
엔드포인트 뒤에 ? {조건}을 통해 조건에 맞는 데이터를 요청한다.
Ordering
역순으로 데이터를 ordering하여 보내줄 것을 요청하는 GET메서드이다. 서버는 Query String을 받아 클라이언트가 원하는 방식으로 데이터를 보내주고 있다.
Pagenation
주로 원하는 만큼 데이터를 불러오는 Pagenation이다. offset 0번부터 시작하여 100개의 데이터를 요청하고 있다.
이렇게 Query String은 원하는 조건을 주어 데이터를 정제하여 가져오는 경우에 사용할 수 있다.
Path Parameter vs Query Parameter
Path Parameter와 Query Parameter는 때에 따라 같은 결과를 가져오기도 한다. 그렇다면 각각의 방식은 어떨 때 가장 적합할까?
Path Parameter
전체 데이터 또는 특정 하나의 데이터를 다룰 때 사용한다.
Query Parameter
Query String은 filtering, ordering, searching에 많이 사용한다.
