REST API ?

---

• REST란 "Representational State Transfer"의 약자이다.
• REST API는 URI(Uniform Resource Identifier)를 사용해 자원(Resource)을 식별하고, HTTP를 통해 해당 자원에 대한 CRUD 요청을 수행한다.

REST API를 쓰는 이유

• 가장 큰 이유는 가독성 향상이라고 생각한다.
• Resource를 기반해 디자인하기때문에, 해당 URI와 HTTP 메서드만 보고도 API의 역할을 쉽게 알아볼 수 있다.
• RESTful하게 API 엔드포인트를 잘 작성하면, 인가 처리할 때도 유용하게 써먹을 수 있다.

그렇다면, 여기서 Restful하게 API를 작성하는 것 어떻게 하는 것일까?

REST API 작성하는 법

• REST API를 잘 작성하기 위한 방법을 찾아보니, 리차드슨의 REST 성숙도 모델이라는 것을 찾았다.
• 총 4단계로 나눠져 있고, 각 단계를 달성할 수록 성숙한(잘 만들어진) REST API라고 한다.

Level 0

• HTTP를 사용하고 있음을 의미
• 단일 URI와 단일 HTTP 메서드를 사용함
• 규칙
  1. URI 가독성을 높이기 위해 밑줄(_) 대신 하이픈(-)을 사용해야 한다
  • http://this-is-test -> O
  • http://this_is_test -> X
  • 밑줄을 사용하면 가려져서 안보이거나, 글꼴에 따라 읽기 힘들 수 있다. 하이픈을 쓰자!
  2. 대문자 대신 소문자를 쓰고, 파일 확장자는 URI에 포함시키면 안된다

Level 1

• 단일 URI 대신 리소스를 도입해, 리소스 별 고유한 URI를 사용해 식별한다.
• GET http://user/device/dev1
• GET http://user/device/dev2
• 요청하는 리소스에 따라 다른 URI로 표현해야 한다.
• 리소스는 동사가 아닌 명사로 표현해야 한다.
• /는 맨 끝에 위치하면 안된다.
• /로 계층 관계를 나타내야 한다.
• 단수나 복수형은 하나를 택일 하되 일관성있게 선택한 형태만 취해야 한다.

Level 2

• CRUD에 맞는 HTTP 메서드를 사용하는 것이 중요하다.
• 생성(Create, POST), 조회(Read, GET), 수정(Update, PUT, PATCH), 삭제(Delete, DELETE)
• 각 메서드 별 사용 시 신경써야할 규칙들이 있다.
  -GET 메서드는 데이터를 변화시키면 안된다.
  -POST 메서드는 요청마다 새로운 리소스를 생성해야한다.
  -PUT 메서드는 리소스를 대체한다. 요청 본문에 포함된 리소스가 서버의 리소스로 완전히 대체하기 때문에, 전체 리소스를 포함해 요청해야한다. 전체 업데이트에 사용된다.
• PATCH 메서드는 리소스의 일부를 수정한다. 요청 본문에 포함된 데이터만 서버의 리소스에서 수정된다. 부분 업데이트에 사용된다.
• DELETE 메서드는 리소스를 삭제한다.
• 이외, 적절한 상태 코드 사용, 쿼리 매개변수 사용 등이 있다.

Level 3

• HATEOAS(Hypermedia As The Engine Of Application State)가 적용되는 단계이다.
• 응답에 리소스의 URI를 포함한 링크 요소를 삽입해 작성해야 한다.
• API 서비스의 모든 End Point를 최초 진입점이 되는 URI를 통해 Hypertext Link 형태로 제공한다.
• 클라이언트에게 다음에 어떤 동작이 가능한지 정보를 제공해 줄 수 있다.

GET https://api/users/1

HTTP/1.1 200 OK
Content-Type: application/json
{
 "result" {
    "id": "1",
    "name": "jaejeong",
    "nextActions": {
       "/api/users/{userId}/roles",
     }
  }
}