처음에는 RESTful API를 백엔드 입장에서의 사용자(프론트엔드 개발자)가 API를 사용할 때 엔드포인드 url과 용도를 명확하게 인지할 수 있도록 깔끔하게 만든 API라고만 생각했다. REST가 무엇인지에 대해 더 찾아보니 이게 많은 목적 중 일부라는 걸 알았다. 프립 사이트의 URI를 예시로 이해한 바를 정리했다.
REST
Representational State Transfer의 약자로, 아키텍쳐 디자인 가이드이다.
REST의 6가지 조건(constraints)
옆에 붙인 설명은 내가 이해한 대로 쓴 표현이라 추후 더 공부하다보면 틀린 점이 나올 수도 있겠다.
1. client-server: 서버, 클라이언트가 각자의 자세한 사항에 대해 신경쓸 필요가 없다.
2. steteless: 서버측에서 클라이언트의 맥락(context)을 저장하지 않는다. 세션 상태는 클라이언트측이 보관한다.
3. cacheable: cacheable한지 명시하여 가능하다면 서버측에서 응답 데이터를 재사용할 수 있다. HTTP가 가진 캐싱 기능을 활용할 수 있다.
4. layered: 계층간 상호작용을 제한하여 클라이언트가 접근할 수 있는 인터페이스를 일원화한다. 서버는 다중 계층으로 구성될 수 있다.
5. uniform interface: 약속된 interface를 사용하여 서버, 클라이언트 개발자가 바뀌더라도 유지보수가 용이하다.
6. code on demand(optional): 서버가 클라이언트에게 처리 코드를 제공할 수도 있다.
이런 조건을 잘 지키는 collections of resources를 RESTful API라고 부른다. 회사 내규에 따라 보편적인 규칙에서 약간 벗어나는 경우도 있다.
조건의 내용을 구글링해서 보니 서버와 클라이언트의 역할을 가능한 명확히 구분하고, 서로에 대한 의존도를 줄여 각각 별도로 구축하는 목적하에 있다는 걸 알 수 있었다. 이런 설계를 통해 application 사이의 결합도를 낮춘다 하는데, 개발자의 역할이 프론트-백으로 나뉜 Web 3.0 관점에 걸맞는 아키텍쳐 스타일이라는 생각이 들었다.
RESTful API가 포함하고 있는 요소
Resources: 수행 대상. json/xml, 파일, 이미지 등. 크게 collection(집합)과 element(개별)로 나누어 표현할 수 있다.
Representations of resources: 이에 대한 응답으로 resource의 표현(json, xml 등)을 전송한다. resource 그 자체를 직접 전송하지 않는다.
Request operations: resources에 대한 행위 표현. REST가 standard HTTP operations에 기반하고 있기 때문에, GET, DELETE 등의 method을 사용한다.
Resource identification in requests: resource를 식별하고 접근하기 위한 URI.
URI는 URL의 상위 개념으로, resource의 유일한 주소인 URL에 식별자를 더한 형태이다. 참고 링크
예시 1) www.frip.co.kr/category/daily/activity는 URI이면서 URL이다. collection URI이다.
예시 2) www.frip.co.kr/search?page=1&query=jeju는 URI이면서 URL이 아니다. search까지만 URL이고 그 뒤는 원하는 정보에 도달하기 위한 식별자이다.
예시 3) www.frip.co.kr/products/131246는 URI이면서 URL이 아니다. peoducts까지만 URL이고 131246이라는 식별자를 통해 resource에 접근하는 element URI이다.
규칙에 맞는 URI 만들기
uniform interface 조건에서 각각의 resource는 식별이 가능해야 된다. 메세지는 수신자가 이해하기 위한 모든 정보를 갖고 있어야 된다(self-descriptive message).
백엔드의 경우 페이지 위주의 생각에 휘둘리면 안 된다. HTTP status code를 응답에 포함해 클라이언트측이 결과에 대한 정보를 알 수 있게 해야 된다.
장고 urls.py에서 app들의 urls.py로 이어지도록, localhost/app 형태로 만들어두고 나면 이제 이 다음 어떤 걸 붙여야 할지 고민해야 된다. 아무것도 붙이지 않는다면 localhost/app 같은 형태가 될 것이다.
1. 마지막에 '/'를 포함하지 않는다. REST에서 '/'는 그 뒤가 있음을 의미한다.
2. '/' 뒤에 오는 url parameter는 '/' 앞에 있는 것의 식별자다. 예시 www.frip.co.kr/products/108923는 108923번 product.
3. 영소문자를 사용한다.
4. method로 사용되는 단어를 넣지 않는다.
5. 동사 사용을 가급적 피한다. signin(login)이나 signup 같이 이미 통용되고 있는 것들은 사용해도 된다.
6. 단어간 결합이 불가피한 경우 '_' 대신 '-'을 사용한다.
methods
Request operations로 사용되는 HTTP methods로는 POST(생성), GET(조회), PUT(추가/수정), DELETE(삭제), PATCH(수정) 등이 있다. 상품과 관련된 www.frip.co.kr/products를 예시로 삼자면(사용자 입장에서 접근할 수 있는 사이트에서는 이 URL이 존재하지 않는다. 하지만 프론트에서 요청을 보내는 백엔드 API의 URL로는 있을법하다), 아래 표와 같은 활용을 기대할 수 있다.
| POST | GET | PUT | DELETE | PATCH | |
| www.frip.co.kr/products | 상품 추가 | 상품 리스트 조회 | 상품 추가 또는 존재하는 상품에 대한 정보를 통째로 수정 | 상품 전체 삭제 | 상품 정보 일부를 수정 |
| www.frip.co.kr/products/123456 | 지원하지 않음(status=405) | 상품 123456 조회 | 상품 123456에 대한 정보를 통째로 수정 | 상품 123456 삭제 | 상품 123456에 대한 정보 일부를 수정 |
path variable
예시 www.frip.co.kr/products/123456에서 123456은 path variable이다.
method들과 조합해서 CRUD 기능을 구현하기에 적합하다.
query parameter
GET method를 사용하여 조회할 때 원하는 결과를 얻기 위해서 '?'로 시작하는 옵션을 덧붙일 수 있다.
sorting, filtering, searching, pagination에 사용한다.
상품 123456에 대한 정보를 얻기 위해 www.frip.co.kr/products?id=123456와 같은 URI를 작성할 수 있다.
REST는 추상적 개념이고 시대에 맞는 best practice를 추구한다는 점에서 데이터베이스 모델링과 같다. 다른 사람들의 best practice를 많이 보기도 하고 가이드라인 속에서 어떤 게 지금 서비스에 더 적합할지를 고민하는 시간이 필요하다고 생각한다.
더 공부할 것
1. API 문서 작성해보기. 참고 링크
2. www.frip.co.kr/search?page=1&query=jeju는 조건에 만족하는 결과를 찾는 URI다. 결과값이 없을 수도 있지만 collection URI라고 생각되는데 맞을까?
3. www.frip.co.kr/products/ 뒤에 숫자를 이것저것 붙여 보았는데 존재하지 않는 상품번호를 넣을 땐 아래와 같은 화면이 나오는 것 같다. 사용자가 잘못된 접근을 했을 때 어떻게 처리하는 게 좋을까?
참고 링크
RESTful API Designing guidelines — The best practices
'Web' 카테고리의 다른 글
| Docker 시작하기 (0) | 2021.03.23 |
|---|---|
| 소셜로그인 - kakao API (0) | 2021.03.14 |
| Style We 프로젝트 이미지 2 (0) | 2021.02.24 |
| Style We 프로젝트 이미지 1 (0) | 2021.02.24 |
| Auth (0) | 2021.02.08 |
