[API] RESTful API

What is REST?

우선 RESTful API를 알아보기 전에, REST의 정의에 대해 짚고 넘어가보도록 하자. REST(REpresentational State Transfer)란 웹에 존재하는 모든 자원(resource, ex. 이미지, 동영상, 데이터)에 고유한 URI를 부여하여 자원에 대한 주소를 지정하는 방법론, 또는 규칙으로, 현재 가장 널리 사용되고 있다.

즉, RESTful API는 REST 규칙을 지키면서 API를 제공한다는 의미로, 프론트엔드에서 백엔드API를 호출할 url을 정의하는 방법이라고 생각할 수 있다.

RESTful API의 장점으로는 self-descriptiveness, 즉 RESTful API 그 자체로도 목적을 쉽게 이해할 수 있다는 점이 있다. 하지만 표준 규약이 존재하지 않아, 안티패턴으로 작성되는 경우가 많다.

Anti Pattern

실제 많이 사용되는 패턴이지만 비효율적이거나 비생산적인 패턴

REST 규칙

• url 은 page 기준이 아닌 resource 기준으로 작성한다.

[GET] http://127.0.0.1:8000/product/main_page_product

• 메인 페이지에 표출되어야할 정보가 무엇인지 판별하여 url을 정한다.

[GET] http://127.0.0.1:8000/store/find_store

• 동사(find)를 사용하지 않는다.

[POST] [http://127.0.0.1:8000/product/add_first_item_information]

• 자원을 추가(add)할 때는 ~/post 만으로 충분하다.

[GET] [http://127.0.0.1:8000/store](http://127.0.0.1:8000/store/search_store)?name='강남'

• 검색 기능은 자원의 정보를 호출하는 기능이므로 [GET] method를 사용한다.

• 검색 키워드는 body를 통해 전달하지 않고, query string을 활용한다.

Query Parameter vs Path Parameter

만약 어떤 resource를 식별하고 싶으면 Path Variable을 사용하고,
정렬이나 필터링을 한다면 Query Parameter를 사용하는 것이 좋다.

/users  # 사용자 목록을 가져온다.
/users?occupation=programer  # 프로그래머인 사용자 목록을 가져온다.
/users/123  # 아이디가 123인 사용자를 가져온다.

또한, 기본적인 CRUD 기능을 위해서 또 다른 URL이나 query parameter를 정의할 필요는 없다.
대신 원하는 기능에 맞게 HTTP 메소드를 바꾸어야 한다.

/users [GET] # 사용자 목록을 가져온다.
/users [POST] # 새로운 사용자를 생성한다.
/users/123 [PUT] # 사용자를 갱신한다.
/users/123 [DELETE] # 사용자를 삭제한다.