RESTful API

RESTful API

웹상에서 아용되는 여러 리소스를 HTTP URI로 표현하고, 그 리소스를 어떻게 할 것인지(불러올 것인지, 받아올 것인지 등) HTTP Method로 정의하는 방식이다.
HTTP Method + Payload 형식으로 깔끔하게 표현 가능하다.

Payload
HTTP request에서 server로 보내는 데이터로, body에 담아 보내는 데이터

RESTful API를 사용하는 이유?

self-descriptiveness라는 특징 때문이다.
URI에 GET/users, POST/beverages/1 과 같은 형식으로 표현하기 때문에,
URI만 보고도 어떤 API인지 쉽게 이해할 수 있다.

하지만, RESTful API는 정해진 표준 규약이 존재하진 않기 때문에, 개발자들 사이에서 암묵적으로 정해진 약속을 따르게 된다. 따라서 형식이 변경될 수 있다.

API 설계 규칙

• URI 정보를 명확하게 표현한다.주로 resource는 명사형을 사용한다.
  GET/users/show/1 -> GET users/1
• resource에 대한 행위: HTTP Method(GET/POST/DELETE)로 표현한다.
  GET delete/user/1 -> DELETE /users/1
• resource끼리 연관이 되어있는 경우: /리소스/고유ID/관계 리소스
  GET /users/{user_id}/profile
• 파일의 경우 파일 확장자를 URI에 포함하지 않는다.
  GET users/1/profile-photo.jpg ❌
• URI 마지막 문자로 /를 포함하지 않는다.
  뒤에 리소스를 추가적으로 넣어야 하는 경우, ?를 붙이게 되는데
  /를 마지막에 붙이면 리소르를 넣을수가 없다.
• 대문자와 언더바(_)는 사용하지 않는다.

Path Parameter

URI 끝에 /id를 붙이면, 해당 id를 가지고 있는 값의 데이터를 받을 수 있다.
GET http://10.58.4.1:8000/products

{
  "results": [
    {
      "id": 1,
      "name": "사리곰탕"
      "price: "1000원"
    }, 
    {
      "id": 2,
      "name": "신라면"
      "price: "800원"
    }, 
  ]
}

GET http://10.58.4.1:8000/products/2

{
  "results": [
    {
      "id": 2,
      "name": "신라면"
      "price: "800원"
    }, 
  ]
}

Query Parameter

• Searching
  GET /users?search=신라면
• Pagination
  GET /products?offset=0&limit=100
• Ordering
  GET /products?ordering=-id
• Filtering
  GET /products?price=3000&name=신라면

Path Parameter vs Query Parameter

GET /products/3과 GET /products?id=3은 동일한 결과를 가지고있다.
그럼 둘 중 어떤 방법을 사용하는게 좋을까?

상황에 따라 다르다.
여러 조건을 걸어서 데이터를 필터링하거나 검색 기능을 구현해야 할 때는 query parameter를 사용하는 것이 좋고, URI가 너무 길어지거나 필터링, 써칭 등의 기능이 필요 없는 경우는 그냥 path parameter를 사용하면 된다