Restful API

Restful API란 REST를 잘 준수하는 API로 HTTP 프로토콜을 사용하여 클라이언트와 서버 간의 통신을 통해 자원을 관리한다. 자원은 고유한 URI로 식별되며, HTTP 메서드를 통해 다양한 작업을 수행한다.

 

즉, REST 기반으로 서비스 API를 구현한 것으로 HTTP API를 잘 설계하는 규칙이라고 정리할 수 있다.

 

REST란?

REST는 Representational State Transfer의 약자로 자원을 이름으로 구분하여 해당 자원의 정보를 주고 받는 것을 의미한다.

 

URI를 통해 자원을 명시하고 HTTP Method를 통해 해당 자원에 대한 CRUD에 대한 정보를 표현하는 것이다.

 

REST API를 작성하는 방법

• 리소스는 명사를 사용해야 한다.
• 단수가 아닌 복수 형태를 사용해야 한다.
• 만약, REST 만으로 해결하기 어려운 경우라면 동사를 허용한다.
• 자원의 계층 관계를 슬래시(/)로 표현한다.
• 마지막 문자에는 슬래시(/)가 있으면 안된다.
• 언더바(_)가 아닌 하이픈(-)을 사용해야 한다.
• 소문자를 사용해야 한다.
• URI에 파일 확장자를 포함하면 안된다.
• CRUD 함수명은 사용하지 않고, HTTP Method를 활용해야 한다.
• 정렬, 페이징, 필터링은 신규 API를 만드는 것이 아닌 Query Parameter를 사용해야 한다.

 

Maturity Model (성숙도 모델)

성숙도 모델이란 REST의 제약 조건에 따라 API를 등급화 하는 방법이다.

 

Level 0

웹 서비스를 제공하기 위해 URL만 매핑해 놓은 상태

 

Level 1

외부로 공개하려는 리소스에 대해서 의미있는 URL로 표현하기 시작하는 단계

 

하지만 HTTP 메소드 별로 서비스를 구분하여 사용하고 있지 않은 상태

 

Level 2

제공하고자 하는 리소스를 적절하게 용도와 상태에 따라서 HTTP Methods에 맞게 설계하고 서비스하는 단계

 

Level 3

💡HATEOAS(Hypermedia As The Engine Of Application State)
클라이언트 요청에 대한 응답에 그 다음 단계로 진행할 수 있는 정보를 같이 알려주는 기능이다.

 

데이터를 가지고 그 다음 작업에서 어떠한 작업을 할 수 있는지 상태 정보를 함께 넘겨준다.

 

HATEOAS 응답 예시

{
  "id": 123,
  "name": "John Doe",
  "email": "john.doe@example.com",
  "links": [
    { "rel": "self", "href": "/users/123" },
    { "rel": "update", "href": "/users/123/update" },
    { "rel": "delete", "href": "/users/123/delete" },
    { "rel": "orders", "href": "/users/123/orders" }
  ]
}

 

 

RESTful API 설계 시 고려해야 할 사항들

• Cosumer first
  • API의 소비자 입장에서 간단하고 직관적인 API 설계를 해야한다.
• Make best user of HTTP
  • HTTP Method, Header 와 같은 HTTP의 장점을 살려서 개발해야 한다.
• Request method
  • 최소한 성숙도 모델 level 2로 사용해야 한다.
• Response Status
  • 각각의 API 요청에 따라 적절한 HTTP 상태코드가 전달되어야 한다.
  • 왜 실패하고 성공 하였는지 함께 반환 시켜주어야 한다.
• No secure info in URI
  • URI에는 사용자의 정보를 포함해서는 안된다.
• Use plurals
  • 제공하는 데이터에 대하여 단수가 아닌 복수형태를 쓰는 것이 일반적이다.
• Use nouns for resources
  • 모든 리소스는 가능하면 동사가 아닌 명사형태로 표시한다.

---

참고자료

• https://restfulapi.net/resource-naming/