웹에서 사용되는 데이터나 자원(Resource)을 HTTP URI로 표현하고, HTTP 프로토콜을 통해 요청과 응답을 정의하는 방식
- REST는 개방형 표준을 사용하므로 API 또는 클라이언트 응용 프로그램의 구현이 특정 구현에 바인딩되지 않는다
- REST API는 리소스를 중심으로 디자인되며 클라이언트에서 액세스할 수 있는 모든 종류의 개체, 데이터 또는 서비스가 리소스에 포함된다.
- 리소스마다 해당 리소스를 고유하게 식별하는 URI인 식별자가 있다
- REST API는 균일한 인터페이스를 사용하므로 클라이언트와 서비스 구현을 분리하는데 도움이 된다. (가장 일반적인 작업 GET, POST, PUT, PATCH, DELETE)
- HTTP 프로토콜을 기반으로 요청과 응답에 따라 리소스를 주고받기 위해서는 알아보기 쉽고 잘 작성된 메뉴판이 필요하다.
- 2단계까지만 적용해도 좋은 API 디자인이라고 볼 수 있고, 이런 경우를 HTTP API라고 부른다.
REST 성숙도 모델
📌 0단계
- 웹 매커니즘 사용하지 않고 단순히 HTTP 프로토콜을 사용하기만 해도 됨
- REST API를 작성하기 위한 기본 단계
- 요청에서의 엔드포인트로 모두
/appointment
를 사용
📌 1단계 : 리소스 사용
리소스를 도입하는 단계
- 모든 요청을 단일 서비스 엔드포인트로 보내는 게 아닌, 개별 리소스와 통신하도록 설계하는 단계
- 요청하는 리소스에 따라 각기 다른 엔드포인트로 구분하여 사용
- 엔드포인트 작성 시에는 동사, HTTP 메서드, 혹은 어떤 행위에 대한 단어 사용은 지양하고, 리소스에 집중해 명사 형태의 단어로 작성할 것.
- 엔드포인트 디자인은 "어떤 응답이 제공되는지" "어떤 리소스의 상태를 변화시키는가"가 중요하다.
- 동사 사용보단 리소스를 지칭하는 명사 사용이 권장됨.
ex) GET /doctors/kim
- 요청에 따른 응답으로 사용한 리소스의 정보와 함께 성공/실패 여부를 반환. 실패시 실패한 이유도 제공하자.
CRUD(Create, Read, Update, Delete)에 맞게 적절한 HTTP 메서드와 HTTP 응답 코드의 사용을 도입하는 단계
- 0단계와 1단계에선 CRUD와 상관없이 POST 메서드를 사용했으나, 이는 2단계에 따르면 적합한 메서드 사용한 것이 아님.
- 조회(READ)하기 위해
GET
메서드를 사용해 요청을 보내고, GET
은 body
를 가지지 않으므로 query parameter를 사용하여 필요한 리소스를 전달한다.
- 또한 생성(CREATE)하기 위해선
POST
메서드를 사용해 요청을 보내고, POST
요청에 따른 응답 반환여부가 중요하다.
- 이 경우 응답은 새롭게 생성된 리소스를 보내주므로, 응답코드는
201 Created
로 명확히 작성해야 하며, 관련 리소스를 클라이언트가 Location
헤더에 작성된 URI를 통해 확인할 수 있도록 하면 2단계 충족.
- 중요한 건 무엇인가 잘못되었음을 알리기 위해 명시적으로 에러 응답을 사용한다.(HTTP 메서드와 HTTP 응답코드 사용 도입)
📌 3단계 : 하이퍼미디어 컨트롤 도입
클라이언트의 상태(State)를 링크를 이용하여 컨트롤 한다
서비스를 HATEOAS(Hypertext As The Engine Of Application state, App 상태 엔진으로서의 하이퍼미디어) 원칙에 기반하여 하이퍼미디어 컨트롤을 적용하는 단계
- 예약을 하기 위해 필요한 요청을, 가능한 시간대 목록을 가져오면서 알 수 있는 디자인 방법이다.
- 요청은 2단계와 동일하지만, 응답에는 리소스의 URI를 포함한 링크 요소를 삽입하여 작성해야 한다.
- ex) 응답 내에 새로운 링크를 넣어 새로운 기능에 접근할 수 있도록 하는 것이 3단계의 핵심 포인트
- 장점
- 서버가 클라이언트에 문제를 일으키지 않고 URI scheme을 변경할 수 있다.
- 클라이언트 개발자가 프로토콜을 탐색할 수 있도록 돕는다. 링크는 클라이언트 개발자에게 다음에 무엇을 할 수 있는지 힌트를 제공한다.
- 서버가 응답 내에 링크를 넣음으로써 새로운 기능을 알릴 수 있도록 한다.
💡 정리
1단계 : 큰 서비스 엔드포인트를 여러개의 리소스로 나누는 분할 & 정복을 사용해서 복잡성을 다루는 문제 처리
2단계 : 불필요한 다양성을 제거, 동일한 방식으로 유사한 환경을 처리할 수 있도록 메소드의 표준 집합을 도입, id 값을 반환받음
3단계 : 프로토콜을 더 스스로 문서화할 수 있는 방법을 제공함으로써 발견가능성을 도입, 링크를 반환받음
HTTP Method
- GET : 정보를 요청하기 위해 사용
- POST : 정보를 입력하기 위해 사용
- PUT : 정보를 업데이트하기 위해 사용
- DELETE : 정보를 삭제하기 위해 사용
- OPTION, HEAD, PATCH 등등
HTTP Status Code
- 200 : OK
- 201 : Created, 리소스가 정상적으로 생성
- 301 : Moved Permanently, 리소스의 URI가 변경 됨
- 400 : Invalid Request, 잘못 된 요청
- 401 : UnAuthorized, 인가되지 않은 요청
- 404 : Not Found, 리소스를 찾을 수 없음
- 500 : Internal Server Error, 서버의 내부 에러
Open API와 API Key
- API : 어플리케이션을 프로그래밍하기 위한 인터페이스
- 어떤 방식으로 정보를 요청하고 받을 수 있는지에 대한 규격을 뜻함
📌 Open API(Open Application Programming Interface, 공개 API)
누구나 사용할 수 있도록 공개된 API
- 개발시 들어가는 시간을 줄이고 비용을 절감한다.
- 대부분 무료 제공이지만 호출수에 따라 비용이 발생할 수 있다.
카카오 API
네이버 API
구글 API
📌 API Key
특정 사용자만 알 수 있는 일종의 문자열, 서버의 문을 여는 열쇠
- API Key가 있어야 API를 사용할 수 있고, API를 제공하는 측에서는 이 Key를 통해서 누가 어떤 API를 얼마만큼 사용하고 있는지 추적할 수 있다.
- 모든 클라이언트가 같은 API 키를 공유하기 때문에, 한번 API 키가 노출되면 전체 API가 뚫려버리는 문제가 있으므로 높은 보안 인증이 필요할 때에는 권장하지 않는다.