[API] RESTful API

📌 RESTful API란?

• 리소스(HTTP URI로 정의된)를 어떻게 한다를 구조적(HTTP Method + Payload)으로 깔끔하게 표현

• Representational State Transfer : 무언가 상태를 나타내는 것을 보내준다. 누가봐도 자명하게 명확하게 나타낸다.

• API 시스템을 구현하기 위한 아케틱쳐 중(ex. Graphql ,SOAP, GRPC, REST)에 가장 널리 사용되는 형식

• "프론트엔드에서 백엔드 API를 호출할 url을 어떻게 만들것인가?"

  장점

  • 자명하다(self-descriptiveness). 그 자체만으로도 API의 목적이 쉽게 이해된다

  단점

  • 표준규약이 없어, 여러 안티패턴으로 작성되는 경우가 흔하다. (안티패턴이란 실제 많이 사용되는 패턴이지만 비효율적이거나 비생산적인 패턴)
    -회사마다 다를 수 있기에 올바른 패턴이 무엇인지는 항상 인식해야한다.

📌 RESTful API의 구성 요소

URI/HTTP Method/Payload

• URI : 해당 사이트의 특정 자원의 위치를 나타내는 유일한 주소
• HTTP Method : HTTP request가 의도하는 action을 정의한 것
• Payload : HTTP request에서 server로 보내는 데이터(body)
  
  

📌 RESTful API 설계 규칙

1. URI 정보를 명확하게 표현해야 한다.
: resource는 명사를 사용한다.
: 무조건 복수로 사용하자!!!

❌ GET/user/1
⭕️ GET/users/1

2. resource에 대한 행위를 HTTP Method로 표현한다.
: URI에 HTTP 메서드가 포함되어서는 안된다.

❌ GET delete/user/1
⭕️ DELETE/users/1

3. URI에 동사가 포함되어서는 안된다.
: URI는 명사여야 한다.

❌ GET/user/show/1
⭕️ GET/users/1

❌ POST insert/user/2
⭕️ POST/users/2

• resource 사이에 연관 관계가 있는 경우
• /리소스/고유ID/관계있는 리소스
  ex. GET/users/{user_id}/profile
  
  

4. 파일의 경우 payload의 포맷을 나타내기 위한 파일 확장자를 URI에 포함시키지 않는다.
❌ GET user/1/profile-photo.jpg
⭕️ GET user/1/profile-photo
(이때 payload의 포맷은 헤더스에 어셉트를 사용한다.)

5. URI는 / 구분자를 사용하여 자원의 계층 관계를 나타내는데 사용한다.

6. URI 마지막 문자로 /를 포함하지 않는다.
❌ GET users/portfolios/
7. 불가피하게 URI가 길어지는 경우 -을 사용하여 가독성을 높인다.
8. _는 사용하지 않는다.
9. URI 경로에는 대문자 사용을 피하도록 규정하고 있다.

update를 위해 PUT || PATCH를 사용 / GET || POST의 차이 블로그 쓰기

---

📌 Path parameter

• URI로 경로의 형태로 나타낸다.
• GET : server에서 원하는 데이터를 받아올 떄
• POST : DB에 내가 원하는 정보를 넣고 싶다
• PATCH : DB 업데이트, 내가 원하는 정보만 업데이트
• PUT : DB 업데이트
• GET, POST / PATCH, PUT의 차이를 잘 알고있자!
  
  

📌 Query parameter

• 주로 GET 요청을 사용함
• 내가 원하는 정보를 DB에 포함시킬 수 있음
• Filtering, Ordering, Pagination, Searching에 사용

Filtering

• ? 뒤에 있는 key=value 형태로 요청을 보낼 수 있다.
• &를 사용하여 key=valule 여러 개를 보낼 수 있다.
  

Ordering

• -를 사용하여 순서를 뒤집을 수 있다.
  

Pagination

• 1,020개의 데이터를 전부 가져오는 것은 비효율적이기 때문에 offset(시작점)과 limit(끝점)으로 필요한 데이터의 범위를 지정해줄 수 있다.
• 이때 프-백 간 offset-limit에 대한 상호 교류가 필요하다
  
  
  

📌 Path parameter vs Query parameter

모범 답안은 있으나 정답은 없으니 개발 맥락에 따라 유연하게 사용하자!

Path parameter : 단 하나의 상품만 가져오는 경우 사용한디.(정수값을 받아올 수 있기 때문)
Query parameter : Filtrering, Sorting, Searching일 때 사용한다.

📌 참고(status code)

개발자는 각자 1인분을 만드는 것이 아니라 서로가 모여 1인분을 만드는 직업이다.

참고자료 : https://library.gabia.com/contents/8339/