REST API

API

: Application Programming Interface

Interface: 어떤 장치 간 정보를 교환하기 위한 수단이나 방법

개발에서의 API는 요청과 응답을 구성하는 방법에 대한 정보들이 들어있음

 

REST

: Representational State Transfer

서버와 클라이언트 통신 방법 중 하나

http URI를 통해 resource를 명시하고, http method를 이용해 resource를 교환하는 통신 방법

 

REST의 특징(아키텍처)

참고) https://restfulapi.net/

1. Server-Client 구조

Server와 Client를 분리하여 최대한 독립적으로 개발 가능

2. Stateless(무상태)

작업을 위한 상태 정보를 따로 저장하고 관리하지 않음.

= 들어오는 요청 단순 처리

3. Cacheable(캐시처리가능)

http를 그대로 사용하기 때문에 캐싱 기능 적용 가능

4. Layerd System(계층화)

5. Uniform Interface(인터페이스 일관성)

http프로토콜을 따르는 플랫폼에서 REST API 사용 가능

 

REST의 장단점

장점: REST API 사용을 위한 별도의 인프라 구축이 필요하지 않음(http 프로토콜 인프라를 그대로 사용하기 때문)

단점: http method 형태가 제한적이며 구형 브라우저에서는 호환되지 않아 지원해주지 못하는 동작 존재

 

REST API

REST 아키텍처 조건을 준수하는 API

RESTful: REST 원리를 따르면서 REST API 설계 규칙을 올바르게 지킨 API

 

REST API 설계 규칙 5가지

참고) https://restfulapi.net/resource-naming/

1. 명사를 사용하여 Resource를 표현해라

명사: 속성 존재

동사: 속성이 존재하지 않음

Resource: 속성 존재

따라서, RESTful URI는 Resource의 속성을 표현할 수 있는 명사를 참조

 

resource 타입 4가지

1.1. document: 단일 개념(=파일 하나, 객체 인스턴스, 데이터베이스 한 행)

• 단수 사용

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

 

1.2. collection: 서버에서 관리하는 리소스 디렉터리

• 복수 사용

http://api.example.com/device-management/managed-devices
http://api.example.com/user-management/users
http://api.example.com/user-management/users/{id}/accounts

 

1.3. store: 클라이언트가 관리하는 리소스 저장소

• 복수 사용

http://api.example.com/song-management/users/{id}/playlists

 

1.4. controller: 문서, 컬렉션, 스토어가 해결하기 어려운 추가 프로세스 실행

• 동사 사용

http://api.example.com/cart-management/users/{id}/cart/checkout
http://api.example.com/song-management/users/{id}/playlist/play

 

2. 일관성이 핵심이다.

모호성을 최소화하고 가독성과 유지보수성을 극대화하기 위해 일관된 resource 명명 규칙(=resource naming conventions)과 URI 형식을 사용해야 함

 

2.1. 슬래시(/)를 사용하여 계층 관계 표시

http://api.example.com/device-management
http://api.example.com/device-management/managed-devices
http://api.example.com/device-management/managed-devices/{id}
http://api.example.com/device-management/managed-devices/{id}/scripts
http://api.example.com/device-management/managed-devices/{id}/scripts/{id}

 

2.2. URI에 후행 슬래시(/) 사용 금지

http://api.example.com/device-management/managed-devices/ ---X
http://api.example.com/device-management/managed-devices ---O

 

2.3. 하이픈(-)을 사용하여 URI의 가독성을 개선

http://api.example.com/devicemanagement/manageddevices/ ---X
http://api.example.com/device-management/managed-devices ---O

 

2.4. 언더바(_) 사용 금지

• 언더바 대신 하이픈 사용 권장

http://api.example.com/inventory-management/managed-entities/{id}/install-script-location ---O http://api.example.com/inventory-management/managedEntities/{id}/installScriptLocation ---X

 

2.5. uri-path 소문자 사용

• scheme, host는 대문자 사용 가능

http://api.example.org/my-folder/my-doc //1
HTTP://API.EXAMPLE.ORG/my-folder/my-doc //2
http://api.example.org/My-Folder/my-doc //3 --X

 

3. 파일 확장자 사용 금지

파일 확장자는 보기에도 좋지 않으며 아무런 이점이 없음

http://api.example.com/device-management/managed-devices.xml ---X
http://api.example.com/device-management/managed-devices ---O

 

4. CRUD 함수 사용 금지

URI는 resource를 고유하게 식별하는 용도로만 사용해야 함

http method를 사용하여 어떤 CRUD 함수가 수행되는지 표시

HTTP GET http://api.example.com/device-management/managed-devices //Get all devices HTTP POST http://api.example.com/device-management/managed-devices //Create new Device HTTP GET http://api.example.com/device-management/managed-devices/{id} //Get device for given Id HTTP PUT http://api.example.com/device-management/managed-devices/{id} //Update device for given Id HTTP DELETE http://api.example.com/device-management/managed-devices/{id} //Delete device for given Id

 

5. 쿼리 파라미터를 사용하여 URI 컬렉션 필터링

resource에 대한 정렬, 필터링, 제한 등의 요구사항은 쿼리 파라미터 사용(새 API 생성X)

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