728x90
REST API
학습 목표
- REST API에 대해 이해할 수 있다.
- REST 성숙도 모델에 대해 이해할 수 있다.
- REST API 문서를 읽을 수 있다.
- REST API에 맞춰 디자인할 수 있다.
- Open API와 API Key에 대해 이해할 수 있다.
Chapter1-1. REST API 디자인
- REST API란?
- 웹에서 사용되는 데이터나 자원을 HTTP URI로 표현하고 HTTP 프로토콜을 통해 “요청”과 “응답”을 정의하는 방식을 말한다.
- 클라이언트가 서버에게 원활하게 HTTP 프로토콜을 통해 “요청”하고 “응답”을 받기 위해 사용자가 알아보기 쉽도록 REST API를 디자인해야 한다.
- 쉽게 설명해서 이용자가 편리하게 주문할 수 있도록 메뉴판을 알아보기 쉽게 짜야 한다.
- Richardson 성숙도 모델: 로이 필딩의 REST 방법론을 더 실용적으로 적용하기 위한 4단계 모델.
- 0단계: HTTP 사용
- 1단계: 개별 리소스와의 통신 준수
- 2단계: HTTP 메소드 원칙 준수
- 3단계: HATEOAS 원칙 준수
구글 REST API 작성 가이드라인
원문: https://cloud.google.com/apis/design/resources?hl=ko
Gmail API
Gmail API 서비스는 Gmail API를 구현하며 Gmail 기능 대부분을 제공합니다. 리소스 모델은 다음과 같습니다.
- API 서비스: gmail.googleapis.com
- 사용자 컬렉션: users/* 각 사용자는 다음과 같은 리소스를 갖습니다.
- 메시지 컬렉션: users/*/messages/*
- 스레드 컬렉션: users/*/threads/*
- 라벨 컬렉션: users/*/labels/*
- 변경 내역 컬렉션: users/*/history/*
- 사용자 프로필을 나타내는 리소스: users/*/profile
- 사용자 설정을 나타내는 리소스: users/*/settings
- 사용자 컬렉션: users/* 각 사용자는 다음과 같은 리소스를 갖습니다.
Chapter1-2. REST 성숙도 모델 - 0단계
0단계: 단순히 HTTP 프로토콜을 사용하는 수준
- REST API를 작성하기 위한 기본 단계이다.
- 0단계만 적용된 경우 해당 API를 REST API라고 할 수는 없음.
- 예제에서는 요청 시 리소스들의 Endpoint가 전부 /appintment 로 동일하였음.
// Request 1. 예약 가능한 시간 확인
POST /appointnent HTTP/1.1
[헤더 생략]
{
"date": "2022-06-10",
"doctor": "현호"
}
// Request 2. 특정 시간에 예약
POST /appointnent HTTP/1.1
[헤더 생략]
{
"doctor": "현호",
"start": "14:00",
"end": "15:00",
"patient": "홍길동"
}
Chapter1-3. REST 성숙도 모델 - 1단계
1단계: 개별 리소스와의 통신 준수
- REST API는 웹에서 사용되는 모든 데이터나 자원(Resource)을 HTTP URI로 표현한다.
- 따라서 사용되는 데이터나 자원, 즉 개별 리소스에 맞는 Endpoint를 사용해야 한다.
- 예제의 0단계에서는 요청 시 Endpoint가 전부 /appintment 로 동일하였으나 1단계에서는 Endpoint가 예약 시간과 예약한 의사명에 맞게 변경되는 리소스를 Endpoint로 사용.
- 올바른 엔드포인트 작성 방식:
- 동사 사용을 지양할 것.
- HTTP 메서드 명시를 지양할 것. (”요청” 메세지 start line에 이미 나와있다.)
- 특정 행위에 대한 단어 사용을 지양할 것.
- 리소스에 집중하여 명사 형태의 단어로 작성이 바람직함.
- 요청의 응답으로 리소스를 전달 시 사용한 리소스의 정보와 성공/실패 여부를 반환해야 한다.
// Request
// 개별 리소스에 맞는 엔드포인트를 사용해야 한다.
// 예약 시간 확인 요청, 응답 예시는 생략했음.
POST /slots/123 HTTP/1.1
[헤더 생략]
{
"patient": "홍길동"
}
// Response
// 성공/ 실패 여부를 포함한 응답을 반환해야 한다.
HTTP/1.1 409 Conflict
[헤더 생략]
{
"appointmentFailure": {
"slots": { "id": 123, "doctor": "현호", ...},
"patient": "홍길동",
"reason": "해당 시간은 이미 예약되어 있습니다"
}
}
Chapter1-4. REST 성숙도 모델 - 2단계
2단계: CRUD에 맞는 적절한 HTTP 메서드 사용
- 0단계와 1단계에서는 모든 요청을 CRUD와 상관없이 POST 메서드를 사용했었다.
- 2단계에서는?
- C: POST 메서드 사용 → 매 요청마다 같은 리소스 반환(멱등). PUT과 병용하지 말아야 한다.
- R: GET 메서드 사용 → 서버의 데이터를 변화시키지 않는 요청에만 사용해야 한다.
- U: PUT: 교체 / PATCH: 수정 → 교체와 수정을 구분하여 사용해야 한다.
- D: DELETE 메서드 사용
- 요청 메세지에서 적절한 HTTP 메서드를 사용해야 한다.
- 응답 메세지에서 새롭게 생성된 리소스를 보내주는 것에 맞게 명확한 응답 코드(HTTP 상태 코드)를 작성해야 하며 클라이언트가 Location 헤더에 작성된 uri를 통해 관련 리소스를 확인할 수 있어야 함.
- 대체로 2단계까지 적용하면 잘 작성된 API라고 본다. 베스트 케이스들도 3단계까지 적용한 사례는 드물다. 즉 3단계까지 무조건적으로 모두 적용할 필요는 없다.
// Request
// 개별 리소스에 맞는 엔드포인트를 사용해야 한다.
// CRUD에 맞게 적절한 HTTP 메서드를 사용해야 한다.
// 예약 가능한 시간 확인
GET /doctors/허준/slots?date=2022-06-10 HTTP/1.1 // 올바른 메서드 사용
[헤더 생략]
// 특정 시간에 예약
POST /slots/123 HTTP/1.1
[헤더 생략]
{
"patient": "홍길동"
}
// Response
// Location 헤더에 작성된 uri를 통해 클라이언트가 리소스를 확인할 수 있어야 한다.
// 명확한 응답 코드를 작성해야 한다.
// 예약 가능한 시간 확인 요청의 응답 메세지는 생략하였음.
HTTP/1.1 201 Created // 명확한 응답 코드 작성
Location: slots/123/appointment // Location 명시
[헤더 생략]
{
"appointment": {
"slots": { "id": 123, "doctor": "현호", ...},
"patient": "홍길동"
}
}
Chapter1-5. REST 성숙도 모델 - 3단계 + a
3단계: HATEOAS(Hypertext As The Engine Of Application State)
- 하이퍼미디어 컨트롤 적용.
- 요청은 2단계와 동일하나, 응답에는 리소스의 URI를 포함한 링크 요소를 삽입하여 작성해야 한다.
- 응답의 링크 요소는 응답 후에 가능한 여러 액션들을 위한 많은 하이퍼미디어 컨트롤을 포함.
- 예제: 예약시간 확인 → 해당 시간대 예약 가능한 링크 삽입
- 예제: 특정 시간대 예약 완료 → 예약내역 재확인 링크 삽입
// Response
// 응답에 리소스의 uri를 포함한 링크 요소를 삽입한다.
HTTP/1.1 201 Created // 명확한 응답 코드 작성
Location: slots/123/appointment // Location 명시
[헤더 생략]
{
"appointment": {
"slots": { "id": 123, "doctor": "현호", ...},
"patient": "홍길동"
},
"links": {
"self": {
"href": "<http://localhost:8080/slots/123>",
"method": "GET"
},
"cancel": {
"href": "<http://localhost:8080/slots/123/cancel>",
"method": "DELETE"
}
}
}
Chapter1-6. Open API와 API Key
Open API
- Open API란?
- Web 2.0 API, 통신망 서비스 API 등 주로 인터넷이나 통신망과 관련된 자원의 API들.
- 여러 사람들이 공동으로 사용할 필요가 있는 자원에 대하여 이 자원의 사용을 개방하여 사용토록 함.
- 사용자들이 자원에 대한 전문적인 지식이 없어도 쉽게 사용할 수 있도록 기능을 추상화하여 표준화한 인터페이스 이다.
- 무제한으로 이용할 수 있는 것은 아니다. API 마다 정해진 이용 수칙과 제한사항이 존재한다.
API Key
- API를 이용하기 위해서는 API 서버의 문을 여는 API Key가 필요하다. 서버를 운용하는데에는 비용이 발생하기 때문에 아무런 조건 없이 익명의 클라이언트에게 데이터를 제공함을 막기 위함.
- API Key가 필요하지 않은 경우도 있음.
- API Key가 필요한 경우, 로그인한 이용자에게 자원의 접근 권한을 API Key의 형태로 제공하며 데이터를 요청할 때 API Key를 같이 전달해야 응답을 받을 수 있다.
참고 자료
- 코드스테이츠 유어클래스 컨텐츠
- 경기데이터드림 - Open API란?
- 구글 REST API 작성 가이드라인
- 마이크로소프트 REST API 작성 가이드라인
728x90