RESTful API

• API 시스템을 구현하기 위한 아키텍처 중에 가장 널리 사용되는 형식

  Graphql, SOAP, GRPC, REST, ... etc

• Representational State Transfer
  웹 상에서 사용되는 여러 리소스를 HTTP URI로 표현하고 그 리소스에 대한 행위를 HTTP Method로 정의하는 방식. 즉, HTTP URI로 정의된 리소스를 HTTP Method + Payload를 이용하여 구조적으로 깔끔하게 표현한다.

• REST 구조의 제약 조건을 준수하는 API, CRUD 연산에 대한 요청을 할 때, 요청을 위한 Resource(자원, URI)와 이에 대한 Method(행위, POST) 그리고 Representation of Resource(자원의 형태, JSON)을 사용하면 표현이 명확해지므로 이를 REST라 하며, 이러한 규칙을 지켜서 설계된 API를 Rest API 또는 Restful한 API라고 한다.

• URI를 통해 자원을 식별하고 어떤 행위를 할 것인지 http method로 정의하는 형식을 REST라고 하는데 이러한 REST한 형식에 따라서 API를 설계하고 구현한 형식을 RESTful API라고 한다.

• 장점
  self-descriptiveness, RESTful API는 그 자체만으로도 API의 목적이 쉽게 이해된다.

• 단점
  표준 규약이 없어 안티패턴으로 작성되는 경우가 흔하다.

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

기본 배경 지식

URI/HTTP Method/Payload

• URI(Uniform Resource Identifier)

  • 해당 사이트들의 특정 자원의 위치를 나타내는 유일한 주소

    ex)

    https://finance.naver.com/login
    https://finance.naver.com/news

• HTTP Method

  • HTTP request가 의도하는 action을 정의한 것

• Payload

  • HTTP request에서 server로 보내는 데이터 (body)

RESTful API 설계 규칙

• URI 정보를 명확하게 표현해야 한다.

  • resource는 명사를 사용

    ex) GET/user/1 -> GET/users/1 (복수형 사용)

• resource에 대한 행위를 HTTP Method(GET, POST, PUT, DELETE)로 표현한다.

  • URI에 HTTP Method가 포함되서는 안된다.

    ex) GET delete/user/1 -> DELETE /users/1

  • URI에 동사가 포함되서는 안된다.

    ex) GET /user/show/1 -> GET users/1
    ex) POST insert/user/2 -> POST users/2

• resource 사이에 연관 관계가 있는 경우

  • /리소스/고유ID/관계 있는 리소스

    ex) GET users/{user_id}/profile

  • 파일의 경우 payload의 포맷을 나타내기 위한 파일 확장자를 URI에 포함시키지 않는다.

    ex)
    GET user/1/profile-photo.jpg (X)
    GET user/1/profile-photo
    (이때, payload의 포맷은 headers에 accept를 사용한다)

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

• URI 마지막 문자로 /를 포함하지 않는다.

  ex) GET users/portfolios/ (X

• 불가피하게 URI가 길어지는 경우 -를 사용하여 가독성을 높인다.

• _는 사용하지 않는다.

• URI 경로에는 대문자 사용을 피하도록 규정하고 있다.

정리

1. URI는 명사를 사용한다.
2. 슬래시로 계층 관계를 표현한다.
3. URI의 마지막에는 슬래시를 붙이지 않는다.
4. URI는 소문자로만 구성한다.
5. 가독성이 떨어지는 경우 하이픈을 사용한다.

Path parameter, Query parameter

Path parameter

• DELETE는 Path 파라미터 이용해서 하는 것이 안전하다.
  

Query parameter

• Filtering
  

• Ordering
  

• Pagination
  

• Searching
  

Status Code

HTTP status code	성공/실패	의미
200 OK	Success	GET - 리소스 반환 PUT / PATCH -상태 메세지 또는 리소스 반환
201 Created	Success	POST - 상태 메세지 또는 새로 생성된 리소스 반환
204 No Content	Success	DELETE - 성공적으로 삭제된 요청의 응답
400 Bad Request	Failure	ALL - 요청에 잘못된 값들이 포함됨 (예: 전화번호에 글자가 포함된 경우)
401 Unauthorized	Failure	ALL - 인증을 요청했으나 사용자가 인증 요건을 충족하지 못함 (예: 로그인이 필요한 경우)
403 Forbidden	Failure	ALL - 사용자가 허용되지 않은 콘텐츠로 접근을 시도함 (예: 비용을 지불한 사용자가 아닌 경우)
404 Not Found	Failure	ALL - 리소스 없음
405 Method Not Allowed	Failure	ALL - 허가되지 않은 HTTP Method로 시도됨
500	Server Error