TIL43 | REST API

REST API

REST(Representational State Transfer)

• 로이필딩이 논문에서 처음 소개. 웹이 HTTP를 제대로 사용하지 못하는 상황을 보고 HTTP의 장점을 최대한 활용할 수 있는 아키텍처로 소개했다

• HTTP를 기반으로 클라이언트가 서버의 리소스에 접근하는 방식을 규정한 아키텍처

• REST API는 REST를 기반으로 서비스 API를 구현한 것을 의미한다

 

REST API 구성

• REST API는 자원, 행위, 표현의 3가지 요소로 구성된다
  • 자원 : URI
  • 행위 : HTTP 요청 메소드
  • 표현 : 페이로드 (자원에 대한 행위의 구체적 내용)
• REST는 자체 표현 구조로 구성되어 REST API만으로 HTTP 요청의 내용을 이해할 수 있다
• 즉, URI로 자원을 식별하고 자원에 대한 행위를 HTTP method로 표현하는 형태

 

장점

• REST API는 그 자체만으로도 API의 목적이 쉽게 이해된다.
• URI만으로도 어떤 자원을 요청하는 지 식별할 수 있고, 계층적으로 표현할 수 있다

단점

• 표준 규약이 없다
• 하나의 엔드포인트에서 돌려줄 수 있는 응답이 구조가 정해져 있는 경우가 많다
• 엔드 포인트에서 그 리소스에 대한 거의 모든 것을 담당한다. 그래서 어떤 정보를 얻으려면 각 리소스 종류별로 요청을 해야하고, 요청 횟수가 필요한 리소스의 종류에 비례한다

 

REST API 설계 원칙

• URI는 리소스를 명확하게 표현해야 한다

  • 자원을 식별할 수 있는 이름은 명사를 사용

  • 예) GET /todos/show/1 ⇒ GET /todos/1

• 리소스에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현한다

  • URI에 HTTP Method가 포함되서는 안된다.
  • 예) GET delete/user/1 ⇒ DELETE /users/1

• resource 사이에 연관 관계가 있는 리소스

  • 예) GET /users/{user_id}/profile

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

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

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

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

  • 예) GET users/portfolios/ (❌)

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

  • _ under bar를 쓰면 가독성 떨어짐

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

 

RESTful 하지 못한 API설계 예시