API, 요즘들어서 더 많이 들어본 단어다.
직접 API 키를 받아본 적도 있어서 그런지, 친숙하게 느껴진다.
오늘은 이 API에 대해 정리해보는 시간을 가지려고한다👀
API 란 무엇인가
서로 다른 프로그램 간 소통하게 도와줄 수 있는 통신규약
이 전전글에서도 소개했지만, 클라이언트와 서버의 소통약속이라고 할 수 있다.
클라이언트가 서버에 대해 잘 모를 때, 서버는 API를 주면서 이렇게 해! 라고
주문서를 놔주는것이다.
=> 서버에 요청해서 데이터를 가져오는 방법 이라고 생각하자
ex) /user : 사용자 정보에 관한 요청
그렇다면 REST API란?
REST를 풀어 쓰면, Representational State Transfer.
해석해보면.. 대표 상태 전송이 되겠다.
기본적으로 REST의 개념으로는, 웹 애플리케이션 상에 존재하는 모든 리소스에 대해 고유의 URI를 부여하고 HTTP Method(get, post, put, delete)를 이용해서 리소스에 대해 CURD 명령을 적용하는것이다.
따라서, 대표 상태 전송이란
URI(가 부여된 리소스)의 상태를 응답으로 전송한다는 의미로 해석할 수 있다.
*그렇다면 REST의 구성요소에는 뭐가 있을까?!
- 자원 : 자원은 서버에 존재하는 데이터의 총칭 / 각각의 자원은 고유의 URI/URL을 가진다.
- 행위 : 클라이언트가 HTTP Method를 이용하여 자원을 조작하는 것.
- 표현 : 클라이언트가 HTTP Method로 자원을 조작하면 서버가 그에 대한 응답을 보내는 것.
📌REST에 대한 특징에는 6가지가 있다.
이 6가지는 웹 API를 디자인 할 때 사용되는 원칙이다.
1. Server-Client Architecture(서버클라이언트 구조) : 서버와 클라이언트의 역할을 분명하게 구분
2. Stateless(무상태성) : HTTP처럼 stateless의 특성, 각 요청에 대한 정보를 저장하지 않고 별개로 처리
3. Cacheable(캐시가능) : HTTP를 사용하기 때문에 웹의 기본 인프라를 사용할 수 없고, 캐시 기능을 이용해서 URI에 대한 반복요청을 효율적으로 처리 할 수 있다.
4. Uniform Interface(일관된 인터페이스) : HTTP를 사용하는 환경이라면 플랫폼에 상관없이 사용할 수 있다.
하나를 가져오기 위한 URL을 짜야한다. (한 개의 정보를 가져오기 위한 두 개의 URL은 X)
5. Self-Descriptiveness(자체적 표현 구조) : JSON, XML을 이용하는 메세지 구조로, 메세지가 무엇을 의미하는지 직관적으로 이해 할 수 있다.
6. Layered System(계층 구조) : 클라이언트와 서버 통신사이에 보안 등을 위한 중간 계층을 추가할 수 있다.
(클라이언트가 대상 서버와 직접 통신하는지 중간서버와 통신하는지 알 수 없음)
REST API를 작성할 때의 규칙
리차드슨의 4단계 모델을 그림으로 표현한 것이다.
모든 단계를 충족해야 REST API라고 부를 수 있다고 주장했지만,
엄밀히 3단계까지 지키기 어렵기 때문에 2단계까지만 적용해도 HTTP API 라고 부른다.
밑으로는 성숙도 모델의 0~3단계까지의 모습이다.
0단계
- 단순히 HTTP프로토콜을 사용하고 있다.
1단계
-
REST API는 웹에서 사용되는 모든 데이터나 자원을 HTTP URI로 표현해야하기 때문에, 모든 자원은 리소스에 맞는 endpoint를 사용해야하고, 요청 후 받는 자원에 대한 정보를 응답으로 전달해야한다는것이 1단계의 요점이다.
-
0단계에서의 요청 endpoint는 모두 /appoint였지만, 1단계에서는 요청하는리소스가 무엇인지에 따라 다른 endpoint로 구분한다.
-
1단계에서의 endpoint는 /doctors/허준, 그리고 /slots/123이다.
slots 뒤의 123은 slots라는 리소스의 123이라는 id를 가진 리소스이다.
++) endpoint작성 시에는 동사,HTTP메서드, 혹은 어떤 행위에 대한 단어 사용은 지양하고, 리소스에 집중해 명사 형태로 작성하는 것이 좋다. -
응답 부분에 appointFailure라는 리소스 사용에 대한 실패 여부를 반환하고 있다.
2단계
-
2단계에서는 CURD에 맞는 적절한 HTTP메서드 사용을 중점으로 둔다.
앞서 0,1단계에서는 모두 요청을 POST메서드로 사용하고 있지만, 성숙도모델 2단계에 따르면, 적합한 메서드를 사용한 것이 아니다. -
예약가능한 시간을
조회한다는것은 READ하는 행위기에,GET메서드를 사용하고,
이 때의 GET은 body를 가지지 않기 때문에 queryparameter를 사용하여 필요한 리소스를 전달한다. => slots?date=2022-08-10 -
예약을 생성하기 위해서는
POST메서드를 사용하여 요청을 보내야한다. 이 경우 응답은 새롭게 생성된 리소스를 보내주기 때문에, 응답 코드를201 Created로 명확하게 작성해야하며, 관련 리소스를 클라이언트가 Location 헤더에 작성된 URI를 통해 확인할 수 있도록 한다.
++) HTTP 메서드를 사용할 때 유의할 규칙
GET메서드는 서버의 데이터를변화시키지 않는 요청에 사용 => ex)READPOST메서드는 요청마다 새로운 리소스를 생성하고PUT메서드는 요청마다 같은 리소스를 반환한다.PUT처럼 같은 리소스를 반환하는 특징을멱등하다고 한다. 이 둘의 차이를 이해하고 구분하여 사용해야한다.PUT은 교체,PATCH는 수정의 용도로 사용한다.
3단계
- HATEOAS(Hypermedia As The Engine Of Application State)라는 하이퍼미디어 컨트롤을 적용한다. 요청은 2단계와 동일하지만, 응답에 리소스의 URI를 포함한 링크요소를 삽입하여 작성해야한다.
- 링크를 넣어 새로운 기능에 접근할 수 있도록 하는것이 3단계의 중요핵심이다.
이러한 링크들은 효율적으로 리소스와 기능에 접근할 수 있게 하는 요소가 될 수 있다.
