REST API: “Representational State Transfer”의 약자, REST API는 웹에서 사용되는 모든 자원을 HTTP URI로 표현하고, HTTP Method를 통해 요청과 응답을 정의하는 방식, REST API를 사용한다는 것은 REST 아키텍처의 제약 조건을 준수한다는 말
코드스테이츠에서 운영 중인 Message States Server의 API 문서
Endpoint
- root-endpoint(or root-URL): API로 요청을 서버와 통신할 때, 서버가 요청을 수락하는 시작점을 의미함. 일반적으로 root-endpoint는 도메인 주소의 루트(/)를 가리킨다.
Github API의 root-endpoint는 https://api.github.com - path: path(또는 url-path)는 API를 통해 서버와 통신할 때, 서버와 통신할 수 있는 key 역할을 합니다. 서버에 정의된 문자열에 따라 path가 달라집니다. 예를 들어, https://api.github.com/user 에서는 'user'가 path
메시지 조회
request
- GET /{githubID}/messages //ID가 작성한 모든 메시지를 조회
- 이 요청에는 추가적인 파라미터(query parameter)를 사용할 수 있다(roomname)
(/kimcoding/messages?roomname=로비)
response
- 응답은 JSON 형식
- id 숫자 고유한 아이디
- username 문자열 사용자 이름
- text 문자열 본문 내용
- roomname 문자열 방 이름
- date 문자열 작성한 시간
메시지 추가
request
- POST /{githubID}/messages //ID가 작성한 메시지를 생성
- 파라매터를 필수로 포함시켜야함, 요청 형식: JSON, MIME 타입: application/json
- username 문자열 사용자 이름
- text 문자열 본문 내용
- roomname 문자열 방 이름
response
- 응답은 JSON 형식, {"id": 5}, 생성된 메시지의 고유한 ID값
메시지 초기화
request
- POST /{githubID}/clear //ID가 작성한 메시지를 초기화한다, 본문 불필요
response - 응답은 JSON 형식, {"message": "message initialized!"}
REST API 디자인 가이드
REST는 새로운 것이 아닙니다. REST는 초기 인터넷 표준, URI 및 HTTP에 중점을 두어 대규모 애플리케이션 서버 시대 이전의 방식으로 웹으로 복귀한 것
URI는 정보의 자원을 표현합니다.
자원에 대한 상태 정의는 HTTP method(GET, POST, PUT, DELETE...)로 표현합니다.
5가지 설계 지침
Resources(URIs), HTTP method, HTTP headers, Query parameters, Status Codes
1. 리소스(URI)
RESTful 접근 방식은 다음을 사용하는 것입니다.
GET /users/1234 POST /users (with JSON describing a user in the body)
DELETE /addresses/1234
(동의어 반복 금지 => getUser(1234) createUser(user) deleteID(1234))
URI Case: spine-case(URI 작성), camelCase(JS), snake_case(Database), PacelCase(Class)
-
HTTP methods
GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS -
HTTP headers
General Header: 이러한 헤더 필드는 요청 및 응답 메시지 모두에 일반적으로 적용
Client Request Header: 요청 메시지에만 적용
Server Response Header: 응답 메시지에만 적용
Entity Header: 엔티티 본문에 대한 메타 정보를 정의하거나 BODY가 없는 경우 요청에 의해 식별된 리소스에 대한 메타 정보를 정의 -
Query parameters
Paging: API의 초기 설계 단계에서 리소스의 페이징을 예상해야 합니다. 반환될 데이터 양의 진행 상황을 정확히 예측하는 것은 실제로 어렵습니다. 따라서 호출 클라이언트에서 제공하지 않는 경우(예: 값 범위 [0-25]) 리소스를 기본값으로 페이지를 매기는 것이 좋습니다.
Filtering: 필터링은 일부 속성과 예상 값을 지정하여 쿼리된 리소스의 수를 제한하는 것으로 구성됩니다. 여러 속성에 대한 컬렉션을 동시에 필터링하고 하나의 필터링된 속성에 대해 여러 값을 허용할 수 있습니다.
Sorting: 리소스 컬렉션에 대한 쿼리 결과 정렬. 정렬 매개변수는 정렬이 수행되는 속성의 이름을 쉼표로 구분하여 포함해야 합니다.
Searching: 검색은 컬렉션의 하위 리소스입니다. 따라서 결과는 리소스 및 컬렉션 자체와 다른 형식을 갖습니다. 이를 통해 검색과 관련된 제안, 수정 및 정보를 추가할 수 있습니다.
매개변수는 쿼리 문자열을 통해 필터와 동일한 방식으로 제공되지만 반드시 정확한 값은 아니며 해당 구문은 대략적인 일치를 허용합니다. -
Status Code
1xx: hold on
2xx: success, 200:OK, 201:Created. 204:No Content
3xx: redirect, 301:Moved permanently, 302:Found, 304:Not Modified
4xx: Client errors, 404:Not Found, 403:Forbidden, 400:Bad Request,
401:Unathorized
5xx: Server errors, 500:Internal Server Error, 502:Bad Gateway
https://developer.mozilla.org/ko/docs/Web/HTTP/Status
구글 API 디자인 가이드
https://cloud.google.com/apis/design?hl=ko
Open API
누구에게나 열려있는 API, 무제한으로 이용할 수 있다는 의미는 아니다. 기관이나 API마다 정해진 이용 수칙이 있고, 그 이용 수칙에 따라 제한사항(가격, 정보의 제한 등)이 있을 수 있다.
API Key
API를 이용하기 위해서는 API Key가 필요
로그인된 이용자에게만 자원에 접근할 수 있는 권한을 API Key의 형태로 제공
