0x49. REST API Design

API Design Process

API Design 을 하기 위해서는 보통 다음의 단계를 따른다.

1. Review API requirements
2. Identify main resource / entity
3. Use HTTP methods to assigin action on resource

Step 1: Review API Requirements

boss 로부터 다음 API requirements 를 요구받았다고 가정해보자.

Create a RET API for the Employee Directory

REST clients should be able to

• get a list of employees
• get a single employee by id
• add a new employee
• update an employee
• delete an employee

Step 2: Identify main resource / entity

그리고 Service 전반에 걸쳐서 사용되는 main resource / entity 의 name 을 정해야 한다. 위의 requirements 의 경우 employee 라는 noun 이 가장 중요한 keyword 가 된다.

convention 은 보통 resource / entity 의 plural, 즉 복수형 형태를 사용한다. 여기서는 employees 가 될 것이다. 실제로는 /api/employees 와 같이 endpoint 로 사용한다.

Step 3: Use HTTP methods to assigin action on resource

POST, GET, PUT, DELETE method 를 사용하여 resource 에 어떠한 동작을 수행하도록 만든다.

HTTP Method	Endpoint	CRUD Action
POST	/api/employees	Create a new employee
GET	/api/employees	Read a list of employees
GET	/api/employees/{employeeId}	Read a single employee
PUT	/api/employees	Update an existing employee
DELETE	/api/employees/{employeeId}	Delete an existing employee
위와 같이 동일한 endpoint 를 사용하고 HTTP method 를 이용하여 다른 동작을 수행하도록 하는 것이 좋다.

/api/employeesList, /api/addEmployee 와 같이 어떠한 action 을 수행하는지를 endpoint name 으로 정하는 것은 anti-pattern 으로 분류되어 지양해야 한다.

Paypal, GitHub 등 실제 Real-Time Service 에서 사용되는 REST API 도 모두 동일한 endpoint 에 대하여 다른 HTTP method 를 사용함으로써 다른 동작을 수행하도록 design 하였다.