API Design Process
API Design 을 하기 위해서는 보통 다음의 단계를 따른다.
- Review API requirements
- Identify main resource / entity
- 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 하였다.