API 디자인 지침

window azure사이트에 API 디자인지침이 잘정리되어있다.. API 디자인 지침

잘 디자인된 API 특성

플랫폼 독립성

모든 클라이언트는 내부에서 API가 구현된 방법에 상관업싱 API를 호출할 수 있어야 한다. 따라서 표준 프로토콜을 사용해야하고 클라이언트 및 웹서비스가 교환할 데이터형식에 동의할 수 있는 메커니즘이 있어야한다.

서비스진화

API는 클라이언트 어플리케이션과 독립적으로 기능을 진화시키고 추가할 수 있어야 한다. API가 진화해도 기존 클라이언트가 수정없이 계속 작동할수 있어야한다. 모든 기능은 클라이언트 어플리케이션이 해당 기능을 완전히 이용할 수 있도록 검색이 가능해야한다.

REST 소개

REST란 Hyper media기반 분산시스템구축을 위한 아키텍처 스타일 이다. 기본 프로토콜들과도 독립적이고 http에 연결될 필요가 없음. 하지만 대부분의 일반적인 REST 구현에서 HTTP를 사용하고있기때문에 이 디자인 지침에서도 HTTP를 위한 REST API 디자인에 중점을 둘것임.

다음은 HTTP를 사용하는 Restful API의 몇가지 디자인 기본 원칙임.

REST API는 리소스를 중심으로 디자인되며 클라이언트에서 액세스할 수 있는 모든 종류의 개체, 데이터 또는 서비스가 리소스에 포함됨.
리소스마다 해당 리소스를 고유하게 식별하는 URI인 식별자가 존재함.
클라이언트가 리소스의 표현을 교환하여 서비스와 상호작용. 대부분 JSON을 사용함.
HTTP 프로토콜의경우 HTTP method를 사용하여 균일한 인터페이스를 만듬.
상태 비저장 요청 모델을 사용. (요청은 독립적이고 임의 순서로 발생할수있음. 정보는 리소스에만 저장됨.)

리소스를 중심으로 API 구성

가능하다면 URI는 동사(리소스에 대한 작업)이 아닌 명사(리소스)를 기반으로해야함.
```
https://adventure-works.com/orders // Good
https://adventure-works.com/create-order // Avoid
```
리소스 URI를 컬렉션/항목/컬렉션보다 더 복잡하게 요구하지 않는 것이 좋음.
웹 요청은 웹서버 부하를 높이므로 다수의 작은 리소스를 표시하는 “번잡한” Web API를 피하도록 노력해야함
API와 기본 데이터 원본 사이에 종속성이 발생하면 안됨.

HTTP method를 중심으로 작업

GET

지정된 URI에서 리소스의 표현을 검색. 응답은 리소스의 세부정보를 포함

POST

지정된 URI에 새 리소스를 만듬. 요청 본문은 새 리소스의 세부정보를 포함.

PUT

지정된 URI에 리소스를 만들거나 대체. 요청 본문은 만들/업데이트할 리소스를 지정.

PATCH

리소스의 부분업데이트를 수행. 요청 본문은 리소스에 적용할 변경 내용을 지정.

DELETE

지정된 URI의 리소스를 제거.