API에 대하여(+ REST API, REST 성숙도 모델)

API ( Application Programming Interface )

API는 한 프로그램에서 다른 프로그램으로 지정된 형식으로 요청, 명령을 받을 수 있는 (데이터를 주고 받기 위한)방법 (ex. 메뉴판)

public API: 누구나 사용 가능한 공개 API
private API : 비공개 API(사내에서만 쓰겠다!)
Partner API : 미리 정해준 파트너만 쓰는 API

REST(Representational State Transfer)

웹(http)의 장점을 최대한 활용할 수 있는 아키텍쳐이다.

- 구성요소
resource, method, message

- REST 의 4가지 속성

1. 서버에 있는 모든 resources는 각 resource당 클라이언트가 바로 접근할 수 있는 고유 URL이 존재합니다
2. 모든 요청은 클라이언트가 요청 할 때마다 필요한 정보를 주기 떄문에 서버에서는 세션 정보를 보관할 필요가 없습니다. 그렇기 때문에 서비스에 자유도가 높아지고 유연한 아키텍쳐 적용이 가능합니다
3. HTTP 메소드를 사용한다는 점입니다. 모든 resource는 일반적으로 HTTP 인터페이스인 GET, POST, PUT, DELETE 4개의 메서드로 접근되어야 한다는 것입니다.
4. 서비스 내의 하나의 resource가 주변에 연관된 리소스와 연결되어 표현 되어야 한다는 점

REST API

REST API 이해와 작성이 쉬운 api를 작성하는 방법론
웹에서 사용되는 데이터나 자원을 HTTP URI로 표현하고, HTTP 프로토콜을 통해 요청과 응답을 정의하는 방식

REST 원리를 따르는 시스템은 RESTful이란 용어로 지칭된다.

RESTful 하지 못한 경우
- CRUD 기능을 모두 POST로만 처리하는 API
- route에 resource, id외의 정보가 들어가는 경우

 

REST 성숙도 모델

4단계로 나뉘는데, 모든 단계를 충족해야 REST API라고 부를 수 있다로 주장했으나 실제로는 3단계 까지 지키기도 어렵기 떄문에 2단계까지만 적용해도 좋은 API디자인이라고 볼 수 있다. 이런 경우를 HTTP API라고도 부른다.

0단계 (HTTP 사용)

단순히 HTTP 프로토콜만 사용해도 된다
이 경우 REST API 라고 할 수는 없고, 0단계는 REST API를 작성하기 위한 기본 단계다.

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

모든 자원은 개별 리소스에 맞는 *엔드포인트를 사용해야 하며 요청하고 받는 자원에 대한 정보를 응답으로 전달해야 한다는 것
포인트는 단일 서비스 엔드포인트로 보내는 것이 아니라 개별 리소스와 통신하도록 설계하는 것이다
각 엔드포인트에 참조할 수 있는 일종의 주소값을 가진다. 각 리소스는 고유의 URI를 가질 수 있다

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

**CRUD에 맞게 적절한 HTTP 메서드를 사용하는 것에 중점을 둔다

HTTP 메서드를 사용할 때의 몇가지 규칙
- Get 메서드는 서버의 데이터를 변화시키지 않는 요청에 사용해야 한다
- POST 메서드는 요청마다 새로운 리소스를 생성하고 PUT 메서드는 요청마다 같은 리소스를 반환한다
***멱등성을 가지는 메서드 PUT과 그렇지 않은 메서드 POST는 구분해서 사용해야 한다 
- PUT 메서드와 PATCH 메서드도 구분하여 사용해야 한다. PUT은 교체 PATCH는 수정의 용도로 사용한다

3단계 (HATEOAS 원칙 준수)

HATEOAS(Hypertext As The Engine Of Application State)
하이퍼 미디어 컨트롤을 적용하는 단계이다.
요청은 2단계와 동일하지만, 응답에는 조금 더 쉽고 효율적으로 리소스와 기능에 접근할 수 있도록 리소스의 URI를 포함한 링크 요소를 삽입하여 작성해야 한다

---

* 엔드 포인트 (Endpoint) : API 호출을 수신하는 API연결의 끝. 어떤 자료를 요청할 건지에 대한 정보
라이온 킹이라는 영화에 대한 것을 작성한다면 /movie/Lion King이라는 엔드포인트를 사용할 것이다.

엔드포인트 작성 시에는 동사, HTTP 메서드, 혹은 어떤 행위에 대한 단어 사용은 지양하고 리소스에 집중해 명사 형태의 단어로 작성하는 것이 바람직한 방법이다.

**CRUD(Create : 생성, Read : 조회, Update : 수정, Delete : 삭제)

***멱등성 : 동일한 요청을 한 번 보내는 것과 여러 번 연속으로 보내는 것이 같은 효과를 지니고, 서버의 상태도 동일하게 남는 것
GET, HEAT, PUT, DELETE 메서드는 멱등성을 가지며 POST,PATCH는 그렇지 않다

 

---

참고

https://seokbeomkim.github.io/posts/rest-api-model/

https://aws.amazon.com/ko/what-is/restful-api/