- RESTful API란?
- RESTful API 설계 규칙
- RESTful API의 장단점
- Path Parameter / Query Parameter
1. RESTful API란?
REST (REpresentational State Transfer)
어떠한 자원에 대한 CRUD요청을 HTTP Method로 표현하고 HTTP URI로 요청을 보내는 모든 것을 일컫는다.
한마디로 자원에 대해 URI를 지정하고 자원에 대한 행위를 Http Method로 표현하는 것을 말한다.
REST의 구성요소
- 자원: URI
- 행위: Http Method
- 표현: 클라이언트 - 서버 간 데이터를 주고받는 형태를 말하는 것으로 JSON, XML이 대표적이다.
RESTful API
API의 엔드포인트 구성방식을 구현하는 방식 중 하나로 REST를 기반으로 API를 구현한 것을 RESTful API라 부른다. REST의 설계규칙을 잘 따른 API를 RESTful 하다고 표현한다.
2. 설계 규칙
- 리소스는 명사를 사용한다. 명사는 복수형으로 사용한다.
GET /user/1 (x)
GET /users/1 (O)- resource 에 대한 행위는 HTTP Method로 표현된다. URI에 HTTP Method가 포함되면 안된다.
GET delete/users/1 (X)
DELETE /users/1 (O)- URI에 동사가 포함되어서는 안된다.
GET /users/show/1 (X)
GET /users/1 (O)- resource 사이에 연관관계가 있는 경우 상위 개념에서 하위개념으로 내림차순 식으로 작성한다.
/리소스/고유ID/관계 있는 리소스
GET /users/{user_id}/profile- 파일의 경우 payload의 파일 확장자를 URI에 포함시키지 않는다.
GET user/1/profile-photo.jpg (X)
GET user/1/profile-photo (O)- URI의 마지막 문자로 슬래시( / ) 를 포함하지 않는다.
- URI가 길어지는 경우 '-'를 사용한다. (하이퍼 링크 표현시 밑줄이 그어지기 때문에 '_'를 쓰면 가독성 떨어진다.)
- URI는 소문자로 작성한다.
3. RESTful API의 장단점
장점
self-descriptiveness. 자명하다. 즉, 요청을 보내는 URI만 보고도 API의 목적을 쉽게 이해할 수 있다.
예를 들어, GET /users/3/profile와 같은 URI가 있다고 하자. 사용자 정보가 모여있는 Users 중에 id가 3인 사용자의 프로필을 요청하는 것임을 바로 이해할 수 있다.
단점
표준 규약이 없어 안티패턴으로 작성되는 경우가 생길 수 있다.
표준이 없어 관리하기 힘들고, 안티패턴의 판단 기준이 모호할 수 있다. 따라서 REST API를 따르고 있는 기업(Google, Netflix, Amazon 등)을 표준으로 삼는 수 밖에 없다.
4. Path Parameter / Query Parameter
RESTful API는 Path Parameter 또는 Query Parameter로 통신할 수 있다.
Path Parameter
Product를 받아오는 Get요청이다.
위와 같이 특정한 하나의 데이터 또는 정제되지 않은 데이터가 필요한 경우에 사용될 수 있다.
새로운 데이터를 추가하는 POST요청과 데이터를 갱신하는 PATH요청이다.
POST
이름이 '무농약 깐 생강'이며 가격이 3000원인 데이터를 추가하고자 데이터를 request body에 담아 보내고 있다.
PATCH
id가 1번인 상품에 대해 가격을 수정하고자 수정하고픈 데이터 내용을 request body에 담아 요청하고 있다.
이처럼 클라이언트가 원하는 요청에 대한 데이터를 request body로 보내면 서버는 이를 받아 처리한다.
💡 PATCH는 데이터를 갱신하는 메서드인데, 전체 데이터를 수정하는 것이 PUT이라면 PATCH는 특정 하나의 내용을 수정할 때 사용된다.
특정 데이터에 대한 id값을 보내며 데이터 삭제를 요청하는 DELETE 메서드이다.
삭제할 데이터에 대한 여러 정보를 굳이 나열하여 보내는 것은 불필요하기 때문에 id값만 URI에 포함하여 요청을 보내고 있다.
Query String
Filtering
특정 조건에 맞는 데이터를 받아오는 GET요청이다.
이와 같이 조건에 맞게 데이터를 정제하여 불러올 때 사용할 수 있다.
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에 많이 사용한다.
오늘의 배운점은 다음과 같다.
첫번째. RESTful API 개념.
프로젝트를 하다가 urlpattern을 어떻게 지정해줘야할 지 고민인 부분이 있었다. 오늘 정리한 RESTful API의 개념을 적용하여 URI만 보고도 API 동작을 알 수 있게끔 적용해야 겠다.
두번째. PUT과 PATCH의 차이
데이터를 수정하는 동작을 PUT으로 구현했었다. 하지만 PUT은 리소스 전체를 수정할 때 쓰는 것이며 리소스 일부를 수정할 때는 PATCH가 더 적합함을 알았다.
예시)
# 기존 데이터
{
이름: '김영희',
나이: 23,
주소: '서울시'
}
PUT /users/1
{
이름: '김철수',
나이: 19
}
# response
{
이름: '김철수',
나이: 19,
주소: null
}
PATCH /users/1
{
이름: '김철수',
나이: 19
}
# response
{
이름: '김철수',
나이: 19,
주소: '서울시'
}