[HTTP] REST API

키워드 : REST API, REST 성숙도 모델, Open API, API key

---

REST API

 

• API(Application Programming Interface)란? : 클라이언트가 리소스를 활용할 수 있도록 서버가 제공하는 인터페이스
• REST(Representational State Transfer) API란 ?
• API의 대표적인 아키텍처.
• 웹에서 사용되는 데이터나 리소스를 HTTP URI로 표현하고 HTTP 프로토콜을 통해 요청과 응답을 정의하는 방식.
• 즉, 쉽게 이야기하자면 ‘최적의 URI 표현 방식 및 요청&응답 설계 방식’이라고 보면 된다.

 

REST API 기본 원칙

1. URI는 리소스를 표현해야 한다.
   • 행위에 대한 표현은 지양하고, 리소스를 표현할 수 있는 명사형을 지향한다.
2. 리소스에 대한 행위는 HTTP 요청 메소드로 표현한다.

 

REST API 디자인 가이드

리차드슨의 4단계 REST 성숙도 모델 이론을 따른다 :

• 0단계 : HTTP 사용
• 1단계 : 개별 리소스와의 통신 준수
• 2단계 : HTTP 메소드 원칙 준수
• 3단계 : HATEOAS 원칙 준수

3단계까지 모두 적용하면 좋지만, 2단계까지만 적용해도 좋은 API 디자인이라 여겨진다.

 

 

0단계 (HTTP 사용)

• HTTP 프로토콜을 사용한다. 하지만 HTTP 프로토콜만 사용했다고 해서 REST API로 간주하지는 않는다.
• 가장 바탕이 되는 기본 단계이다.

 

1단계 (개별 리소스와의 통신 준수)

• 각각의 리소스를 식별할 수 있는 적절한 이름을 써야하며, 요청하고 받는 리소스에 대한 정보를 응답으로 전달한다.
• 이름은 행위나 HTTP 메서드가 들어간 표현은 지양하고, 리소스의 특징을 표현할 수 있는 명사형이 권장된다.
• 요청에 따른 응답에는 사용한 리소스에 대한 정보와 리소스 사용의 성패 여부를 반환한다.

 

2단계 (HTTP 메소드 원칙 준수)

• CRUD에 기반한 HTTP 메서드를 사용한다.

 

종류	HTTP 요청 메서드	비고
조회 (READ)	GET	서버의 데이터를 변화시키지 않는 요청에 사용.
추가 (CREATE)	POST	요청마다 새로운 리소스 생성.
갱신 (UPDATE)	PUT	요청마다 같은 리소스 반환(멱응성). 교체 시 사용
갱신 (UPDATE)	PATCH	수정 시 사용.
삭제 (DELETE)	DELETE	삭제 시 사용.

 

3단계 (HATEOAS 원칙 준수)

• HATEOAS(Hypertext As The Engine Of Application State) 하이퍼미디어 컨트롤 적용.
• 요청 : 2단계와 동일.
• 응답 : 리소스의 URI를 포함한 링크 요소를 삽입. 새로운 링크를 넣어 새로운 기능에 접근을 가능케 함.

 

---

 

Open API

• 누구에게나 개방된 API, 대개 공공데이터가 이에 해당.
• 무제한으로 이용할 수 있는 것은 아니다.
• API마다 정해진 이용 규칙과 제한사항이 존재할 수 있다.

 

API Key

• API 를 이용하기 위해 필요한 key.
• API key가 필요한 경우, 접근 권한을 API key 형태로 제공하며 데이터 요청 시 key를 전달해야 한다.