Chapter 2-3. API 명세서
REST(Representational State Transfer) API(Application Programming Interface)
API를 정의할 때 웹 애플리케이션은 보통 RESTful한 API를 정의하고 구현합니다. 그렇다면 RESTful한 것은 무엇일까요? 이것을 알아보기 위해서는 리소스(Resources)와 URI에 대해 간단하게 알고 넘어갈 필요가 있습니다. 리소스는 미디어, DB 데이터 등 모든 자원을 의미합니다. 즉 RESTful한 API로써 통신을 할 때 기대하는 결과값에 해당하는 자원들의 일체를 의미합니다. URI(Uniform Resource Identifier)란 특정 리소스를 식별하는 ‘통합 자원 식별자'를 의미합니다. 웹 기술에서 사용하는 논리적 또는 물리적 리소스를 식별하는 고유한 문자열 시퀀스입니다. 바로 감이 안잡히죠? 우리가 익히 잘 알고 있는 URL과 비교하여 이해하면 조금 더 명확하게 그 의미를 파악할 수 있습니다. URL은 흔히 웹 주소라고 많이 부르고 있습니다. 좌표의 개념으로 생각하면 쉽습니다. 리소스가 어디 있는지 알려주기 위한 주소값인 셈이죠. 이에 반해 URI는 URL보다 더 큰 범위의 개념을 갖습니다. 즉 URI는 식별하고 URL은 위치를 알려준다고 생각 할 수 있습니다. URI는 따라서 URL보다 더 많은 정보를 담고 있는데 그 구조를 살펴보면 다음과 같습니다.
scheme:[//[user[:password]@host[:port]][/path][?query][#fragment]
- scheme : http 또는 https를 사용합니다.
- user, password : 데이터가 있는 서버에 접근하기 위해 필요한 ID와 PASSWORD
- host, port : 서버의 호스트와 포트 번호
- path : 서버의 상세 경로
- query : path에 접근하기 위한 추가 정보 (파라미터)
- fragment : 메인 리소스 내에 존재하는 서브 리소스에 접근할 때 식별하기 위한 정보
RESTful한 API란 모든 리소스에 대해 고유한 URI를 부여하고 HTTP Method를 적절히 사용하여 리소스를 제어할 수 있는 수단입니다. 이때 요청에 대한 응답은 JSON이나 XML과 같은 사전 정의된 형식을 사용하여 일관된 방법으로 주고 받습니다. REST의 특징을 몇가지로 정리할 수 있는데 그 특징은 다음과 같습니다.
- 서버-클라이언트 구조 (Server-Client Architecture)
- 무상태성 (Stateless)
- 캐시 가능 (Cacheable)
- 일관된 인터페이스 (Uniform Interface)
- 자체적인 표현 구조 (Self-Descriptiveness)
- 계층 구조 (Layered System)
REST API 규칙
관계 나타내기
<http://test.com/groups/1/users>
- groups, users : 이와 같이 복수로 표현되는 것들은 보통 여러개의 리소스를 갖을 수 있으므로 복수형으로 표시하고 ‘Collection’ 이라고 부릅니다.
- 1 : Collection에 포함된 대상 리소스는 단수형으로 표시하고 ‘Document’라고 부릅니다.
- /groups/1/users : Collection과 Document의 관계를 /를 통해 나타낼 수 있습니다. 그룹이라는 Collection 안에 ‘1’ Document를 나타내고, 해당 Document가 갖고 있는 사용자들을 나타냅니다.
HTTP Method
- GET : Query의 ‘SELECT’에 해당한다.
- POST : Query의 ‘INSERT’에 해당한다.
- PUT : Query의 ‘UPDATE’에 해당한다.
- DELETE : Query의 ‘DELETE’에 해당한다.
