REST API

---

Representational State Transfer

• Web의 장점을 최대한 활용할 수 있는 것으로써 제시된 architecture.
• 뚜렷하게 정해진 표준이 있는 것은 아니다. (가이드라인 정도)
• 클라이언트 - 서버 구조
  • 서버는 API를 제공하고 클라이언트가 사용자 인증 등을 관리하도록 하여,
    역할을 확실히 구분하여 서로 간의 의존성을 줄인다.
  • 중간에 프록시 서버를 둘 수 있다.
• stateless
  • 서버는 state를 따로 관리하지 않고, request에 대한 처리만 하도록 하는 구조이다.
    
    

URI 규칙

---

• resource에 대한 CRUD는 HTTP method (GET, POST, PUT/PATCH, DELETE)로 표현하고,
  URI에 resource를 표현하는 것을 중심으로 한다.
  • control resource를 의미하지 않는 한, 동사는 지양하고 명사를 사용한다.
• 슬래시(/)
  • 계층 관계를 나타내는 데에 사용한다.
  • 맨 마지막에는 쓰지 않는다.
• 하이픈(-)
  • 필요에 따라 가독성을 높이기 위한 목적으로 사용한다.
  • 밑줄(_)은 쓰지 않는다.
• 소문자
  • 대소문자에 따라 다른 resource로 인식하기 때문에, 대문자 사용을 지양한다.
• 확장자
  • 확장자는 URI에 포함시키지 않는다.
• collection, document
  • document는 객체 하나로써 단수, collection은 객체들의 집합으로써 복수로 표현.
    • ex. GET: sports/soccer/players/13
• 리소스 간에 관계가 있는 경우의 표현
  • /리소스 명/리소스 id/관계가 있는 다른 리소스 명 을 나타내고자 할 때는
    필요에 따라서는 다음 예시의 likes와 같이 서브 리소스를 두어 표현하기도 한다.
    • 소유 관계 ex. GET: /users/{userid}/devices
    • 기타 관계 ex. GET: /users/{userid}/likes/devices
      
      

HTTP response status code

---

• 200번 대
  • 200: 클라이언트의 요청을 정상적으로 수행함.
  • 201: 클라이언트가 POST를 통한 resource 생성 요청 시, 성공적으로 생성됨.
  • 202: 클라이언트가 비동기 작업에 대한 요청을 받아들임.
    응답으로, 진행 상황을 조회할 수 있는 URL을 넘겨준다.
    혹은 작업이 완료됨에 따라 server push를 할 수 있도록 한다.
  • 204: 클라이언트의 DELETE 등의 요청을 수행하여 응답 body에 아무 것도 없는 경우.
• 300번 대
  • 301: 클라이언트가 요청한 resource에 대한 URI가 변경 되었을 때 사용한다.
    응답으로, location header에 변경된 URL를 명시해야 한다.
• 400번 대
  • 400: 클라이언트의 요청이 부적절할 시.
    응답으로, 관련한 사유를 명시해준다.
  • 401: 클라이언트가 인증되지 않은 상태에서 보호된 resource를 요청 시.
  • 403: 클라이언트가 인증은 되었으나 권한이 없는 resource에 대한 요청 시.
  • 404: 클라이언트가 존재하지 않는 resource에 대한 요청 시.
  • 405: 클라이언트가 사용 불가능한 method로 resource를 요청 시.
    응답으로, header에 허용 가능한 method를 표시한다.
  • 409: 클라이언트가 비즈니스 로직 상 불가능한 요청 시.
  • 429: Dos, brute-force attack 같은 비정상적인 접근을 막기 위해 요청 수를 제한 시.
    응답으로, header에 retry-after: 3600 등을 넘겨준다.
• 500번 대
  • 500: 서버에 문제가 있을 경우로, 사용자에게 나타내지 않도록 한다.
    단, 웹 서버의 오류일 때는 가능하다.
    
    

기타

---

• content-type은 application/json을 쓰는 것을 지향한다.
  • 이미지 등에는 formdata를 사용한다.
• GET method
  • query parameter: 검색, 정렬, 필터링에 대한 resource 표현 시 사용한다.
  • path variable: 특정할 수 있는, 식별된 resource에 대해 사용한다.
    • resource 식별을 위해 POST, PUT/PATCH, DELETE 에서도 사용한다.
      - POST, PUT/PATCH는 생성 혹은 변경할 데이터를 body(payload)에 담는다.
      - DELETE는 path variable로 resource를 식별하면 되므로, body는 쓰지 않는다.