좋은 REST API를 디자인 하는 방법
REST API를 작성할 때할 규칙들은 리차드슨의 REST 성숙도 모델로 총 4단계(0~3단계)로 나누어진다. 그러나 2단계까지만 적용해도 좋은 API 디자인이라고 말하며, 2단계 부터 HTTP API 라고도 부릅니다.
REST - 0단계
HTTP 프로토콜을 사용하기만 해도 된다. → REST API의 출발 (기본단계)
- 해당 API를 REST API라고 할 수는 없다.
- 모든 요청에서 엔드포인트로
/appointment를 사용한다.
REST - 1단계
개별 리소스와의 통신을 준수한다.
개별 리소스에 맞는 엔드포인트(Endpoint)를 사용해야 한다는 것과 요청하고 받은 자원에 대한 정보를 응답으로 전달해야 한다.이때 응답으로 리소스를 전달할 때도 사용한 리소스에 대한 정보와 함께 리소스 사용에 대한 성공/실패 여부를 반환해야 합니다.
엔드포인트 (Endpoint) 작성밥법
- 엔드포인트 작성방법 : 리소스에 집중해 명사 형태의 단어로 작성하는 것이 바람직하다.
- 지양해야하는 방법: 동사, HTTP 메소드, 혹은 어떤 행위에 대한 단어 사용은 지양한다.
ex 1) 예약 가능한 시간 확인 요청 -> "엔드포인트" : /doctors/허준
→ 응답: 데이터(리소스) -> 의사 허준의 예약 가능한 시간대
ex 2) 특정 시간에 예약 요청 -> "엔드포인트" : /slots/123 실제 변경되는 리소스 요청
-> 예약이 불가능할 경우 ? 응답 : 리소스 사용에 대한 실패 여부를 포함한 응답을 받는다.
REST - 2단계(HTTP API)
CRUD에 맞게 적절한 HTTP 메소드를 사용하는 것에 중점을 둔다.
→ HTTP 메소드를 사용할 때 규칙을 확인하고 사용해야한다.
관련 리소스를 클라이언트가 Location 헤더에 작성된 URI를 통해 확인 할 수 있도록 해야, 완벽하게 REST 성숙도 모델의 2단계를 충족한 것이라고 본다.
ex 1) 예약 가능한 시간을 조회(READ)하기 위해 GET 로 요청
→ GET 메소드는 body를 가지지 않기 때문에 query parameter를 사용하여 리소스 전달
-> 응답: 데이터(리소스) -> 의사 허준의 예약 가능한 시간대
ex 2) 특정 시간에 예약을 생성(CREATE)하기 위해 POST 로 요청
→ 응답 : 새롭게 생성된 리소스 → 상태코드 201 Created 로 명확하게!
REST - 3단계(HTTP API)
HATEOAS, 하이퍼미디어 컨트롤(Hypertext As The Engine Of Application State)을 적용한다.
2단계와 거의 동일하지만, 응답에는 리소스의 URI를 포함한 링크를 넣어 새로운 기능에 접근할 수 있도록 하는 것이 3단계의 중요 포인트이다.
- 응답에 들어가게 되는 링크 요소 : 응답을 받은 다음에 할 수 있는 다양한 행동 을 위해 많은 하이퍼미디어 컨트롤을 포함한다.
ex) 예약 가능 시간을 확인 요청-> 응답 : 예약을 할 수 있는 링크를 삽입하여 응답
