API 디자인
리소스를 중심으로 디자인 됩니다. 리소스는 클라이언트에서 액세스할 수 있는 모든 종류의 개체, 데이터 또는 서비스이빈다.
리소스마다 고유하게 식별하는 URI인 식별자가 있습니다. 예를 들어 특정 고객 주문의 URI는 다음과 같습니다.
https://adventure-works.com/orders/1
DB에서의 하나의 레코드, Spring에서의 하나의 객체와 유사한 단일 자원의 개념입니다. 단수를 사용하여 문서 자원을 표시합니다.
http://api.example.com/**device-management**/managed-devices/{device-id}
http://api.example.com/**user-management**/users/{id}
http://api.example.com/**user-management**/users/admin
서버가 관리하는 리소스 디렉터리입니다. 복수형으로 작성합니다.
http://api.example.com/device-management/**managed-devices**
http://api.example.com/user-management/**users**
http://api.example.com/user-management/**users**/{id}/**accounts**
스토어는 클라이언트가 관리 하는 자원 저장소이다. 클라이언트는 API를 이용하여 자원을 넣거나 가져올 수 있고 삭제 할 수 있다. 복수를 사용하여 스토어를 표현한다.
http://api.example.com/song-management/users/{id}/**playlists**
컨트롤러 자원은 인자와 반환 값, 입력 및 출력이 있는 실행 가능한 함수와 같다. 문서, 컬렉션, 스토어로 해결이 어려운 절차적 실행을 수행하기 위한 모델이다. 특정 자원을 가리키는 것이 아니라 실행 인 만큼 예외적으로 동사를 사용한다.
http://api.example.com/cart-management/users/{id}/cart/**checkout**
http://api.example.com/song-management/users/{id}/playlist/**play**
자원을 정렬, 필터링 하거나 제한된 수량을 요청 해야 할 필요가 있다. 이때 신규 API를 생성 하려 하지 말고 쿼리 파라미터를 활용 한다.
http://api.example.com/device-management/managed-devices
http://api.example.com/device-management/managed-devices?**region=USA**
http://api.example.com/device-management/managed-devices?**region=USA&brand=XYZ**
http://api.example.com/device-management/managed-devices?**region=USA&brand=XYZ&sort=installation-date**
http://api.example.com/devicemanagement/manageddevices/ http://api.example.com/device-management/managed-devices
REST API에서는 일관된 소문자를 권장합니다. 복합어 형태로 이뤄진 경우 -로 가독성을 챙깁니다. 단, 언더바(_)는 사용하지 않습니다. 애플리케이션의 글꼴에 따라 일부 브라우저나 화면에서 정상적으로 표시되지 않을 수 있습니다.
https://adventure-works.com/orders // Good
https://adventure-works.com/create-order // Avoid
컬렉션을 참조하는 URI에 대해서는 일관적인 명명 규칙을 적용해야 한다.
GET : 리소스 접근
POST : 리소스 생성
PUT: 리소스에 대한 전체 속성 업데이트
PATCH: 리소스 일부 속성 업데이트
DELETE: 지정된 URI 리소스 제거
| 리소스 | POST | GET | PUT | DELETE |
|---|---|---|---|---|
| /customers | 새 고객 만들기 | 모든 고객 검색 | 고객 전체 업데이트 | 고객 전체 제거 |
| /customers/1 | - | id=1인 고객 검색 | 고객1의 세부 정보 업데이트 | 고객 1 제거 |
| /customers/1/orders | 고객 1의 주문 생성 | id=1인 고객의 주문 내역 검색 | 고객 1의 주문 전체 업데이트 | 고객 1의 모든 주문 내역 제거 |
POST
PUT
HTTP 표준:
호환성 문제:
안정성과 멱등성:
캐싱:
오랜 시간이 지나더라도 일반적인 개발자 환경을 제공하려면 다음과 같아야합니다.
1: 단순해야합니다.
2: 직관적이어야 합니다.
3: 일관적이어야 합니다.