[Spring] HTTP API 설계 (Restful API)

HTTP API 설계

• HTTP 설계는 항상 리소스(entity) 식별을 기준으로 삼아야한다.

Restful API

Rest (Representational State Transfer)를 잘 지킨 API를 의미하며, API로 HTTP 프로토콜을 사용하여 클라이언트와 서버 간의 통신을 통해 자원(리소스)를 관리한다.

💡Rest (Representational State Transfer) : 리소스를 이름으로 구분하여 해당 리소스의 상태를 주고 받는 것을 의미한다.

• 리소스는 고유한 URI로 식별된다.
• HTTP Method를 통해 해당 자원의 CRUD Operation을 적용한다.
  
  ➡︎ 이를 REST라고 칭한다.

📌 Restful API 설계 규칙 참고 자료

1. 리소스는 명사를 사용해야 한다.

URI에 들어갈 리소스는 단수가 아닌 복수 형태이다. [ ex > board ❌ boards ⭕]

URI에는 동사가 들어가면 안되고 HTTP Method의 역할을 포함하지 않는다.

🚨다만, REST만으로 해결하기 어려운 경우에는 동사를 허용한다. 🚨

2. 자원의 계층 관계를 슬래시(/)로 표현한다.

/device-management
/device-management/managed-devices
/device-management/managed-devices/{id}
/device-management/managed-devices/{id}/scripts
/device-management/managed-devices/{id}/scripts/{id}

3. 마지막 문자에는 슬래시(/)가 있으면 안된다.

🚨/device-management/🚨

4. 언더바(_)가 아닌 하이픈(-)을 사용해야 한다.

/device-management

5. 소문자를 사용해야 한다.

/device-management/managed-devices.xml

6. CRUD 함수명은 사용하지 않고, HTTP Method를 활용해야 한다.

어떤 CRUD 기능이 수행되는지 나타내기 위해서는 HTTP 요청 방법을 사용해야 한다.

HTTP GET /device-management/managed-devices  		
HTTP POST /device-management/managed-devices  	

6. 정렬, 필터링, 페이징은 신규 API를 만드는것이 아닌 Query Parameter를 사용해야 한다.

성숙도 모델 (Maturity Model)

성숙도 모델은 총 4단계로 나누어져 각 단계의 조건에 만족할 수록 REST API에 가까워 진다.

🔴 최소 Level2를 지켜야 한다.

---

Level.0

RPC(Remote Procedure Call)처럼 리소스 구분 없이 설계된 HTTP API이다.

➡︎ 별도의 원격 제어를 위한 코딩 없이 다른 주소 공간에서 리모트의 함수나 프로시저를 실행 할 수 있게 해주는 프로세스간 통신입니다. 즉, 위치에 상관없이 RPC를 통해 개발자는 위치에 상관없이 원하는 함수를 사용할 수 있습니다.

RPC(Remote Procedure call)에 대해 알아보자!

웹에서 제공하는 RESTful한 개념(리소스, 상태, 링크 등)은 활용하지 않고 단순히 정해진 주소에 요청을 보내고 응답받는 구조를 의미한다.

하나의 End-Point(주소)를 사용하기 때문에 HTTP Method는 반드시 POST가 되며, 상태코드는 프로세스 상태에 관계없이 항상 200을 응답한다.

Level.1

리소스 개념을 도입하여 의미있는 URL로 표현하기 시작하는 단계이다. 모든 요청을 하나의 End-Point로 보내는 것이 아니라 개별 리소스와 통신하게된다.

사용자의 요청을 GET, POST로 대부분 처리하고 에러를 반환한다. 또한, Header에 Content-Type이나 Cache 정보를 제공하지 않는다.

Level.2

4가지 HTTP Method를 사용하여 CRUD를 구현하고 StatusCode도 활용하여 반환한다.

💡 Header에 Content-Type이 제공되고 멱등성을 보장하는 GET의 경우 캐시가 적용된다.

Level.3

HATEOAS (Hypermedia As The Engine Of Application State)는 데이터를 가지고 그 다음 작업에서 어떠한 작업을 할 수 있는지 상태 정보를 함께 넘겨준다.

• 클라이언트 측에서는 서버가 제공하는 서비스를 일일이 찾는 수고를 겪지 않아도 된다.

• End-Point만 가지고 있으면 서버가 제공할 수 있는 다음, 그 다음 URI를 알 수 있다.

📌 REST API 성숙도 모델 (Maturity Model) [Richardson Maturity Model]

📌 REST API Maturity - Towards The Glory of REST