REST API, WEB API(HTTP API)

<참고> https://www.redhat.com/ko/topics/api/what-is-a-rest-api

REST API, WEB API(HTTP API)

글. 수알치 오상문

 

RSET API를 지원하는 서비스 중에는 HTTP 기반의 WEB API(HTTP API)가 많다. 

 

1.  API : Application Programming Interface

- 애플리케이션 소프트웨어를 구축하고 통합하는 정의 및 프로토콜(규약) 집합이다.

- 정보 제공자와 정보 사용자 간의 호출 규칙이다.

- 사용자(클라이언트)와 사용자가 필요로 하는 자원(정보) 사이의 연결 역할을 한다.

 

예를 들어 날씨 서비스 API에서, 사용자가 지역 정보(우편번호나 지역명)를 제공하면, 생산자는 최고 기온, 최저 기온 등의 구성 정보를 응답하도록 규정할 수 있다.  

 

2. REST API

REST API는 REST(Representational State Transfer) 아키텍처 제약 조건을 준수하는 애플리케이션 프로그래밍 인터페이스이다.

- REST는 프로토콜이나 표준이 아닌 아키텍처 규칙 집합이다.

- API 개발자는 REST를 다양한 방식으로 구현할 수 있다. 

 

3. RESTful API 

HTTP 기반에서 사용자가 API를 통해 요청(request)하면 RESTful API는 자원 상태 표현(정보)을 요청자에게 돌려준다. 정보 표현은 JSON(Javascript Object Notation), HTML, XLT, 텍스트와 같은 미리 약속한 형식으로 전송된다. 이 중에서 JSON이 널리 사용된다. 

API를 RESTful 방식으로 서비스하려면 다음 기준을 따라야 한다.

• 클라이언트, 서버 및 자원으로 구성되었으며 요청/응답이 HTTP를 통해 관리되는 클라이언트-서버 구조이다.
• 스테이트리스(stateless) 클라이언트-서버 커뮤니케이션이다. 요청 간에 클라이언트 정보는 저장하지 않으며, 각 요청이 분리되어 독립적이다.
• 클라이언트-서버 상호 작용을 간소화하는 캐시 가능 데이터를 사용한다.
• 정보가 표준 형식으로 전송되기 위한 구성 요소 통합 인터페이스이다.
  • 요청된 자원은 식별 가능하며 클라이언트에 전송된 표현과 분리되어야 한다.
  • 수신한 표현을 통해 클라이언트가 자원을 조작할 수 있어야 한다(충분한 정보가 표현에 포함되어 있음).
  • 클라이언트에 반환되는 메시지(self-descriptive message)에 클라이언트가 정보를 처리해야 하는 방식에 대한 정보가 잘 나타나야 한다.
  • 클라이언트가 자원에 접근 후 하이퍼링크를 사용해 현재 수행 가능한 기타 작업을 찾을 수 있어야 한다.
• 요청된 정보를 검색하는 데 관련된 서버(보안, 로드 밸런싱 등 담당)의 각 유형을 클라이언트가 볼 수 없는 계층 구조로 만든 시스템이다.
• 코드 온디맨드 기능을 제공한다(선택 사항). 요청 받으면 서버에서 클라이언트로 실행 가능한 코드를 전송하여 클라이언트 기능을 확장할 수 있는 기능을 제공한다. 

 

4. WEB API (HTTP API) 구현 

1) WEB API

 

HTTP 기반으로 RESTful API를 구현할 수 있는 WEB API에 대해 알아보겠다.  

• URI는 정보의 자원을 표현한다.
• 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)를 이용한다.

 

[표] HTTP METHOD와 기능

METHOD	설명
GET	서버 자원을 조회하고 정보를 가져온다.
POST	서버에 (자원 정보를 제공하고) 자원을 생성한다.
PUT	서버 자원을 수정한다.
DELETE	서버 자원을 삭제한다.

* GET, POST만 이용하여 PUT, DELETE까지 구현하기도 한다.

 

2) Method와 URI

 

API에 사용하는 URI는 정보의 자원을 표현하고 행위는 Method로 표현한다.

 

• GET /members  :  모든 이용자 정보를 요청한다.
• GET /members/1 : 1번 이용자 정보를 요청한다.
• POST /members : 이용자 생성을 요청한다.
• PUT /members/1 : 1번 이용자 정보를 수정한다.
• DELETE /members/1 : 1번 이용자 정보를 삭제한다. 

 

[잘못 표현된 예]

• GET /members/delete/1  : GET은 정보 요청할 때 사용해야 하며, 동사로 삭제를 표현하지 말아야 한다.
• GET /members/get/1  : 특정 자원 정보는 id만 붙인다. GET /members/1
• GET /members/add   : 자원 생성은 POST를 이용한다. POST /members
• GET /members/update/1  : 자원 업데이트는 PUT을 이용한다. PUT /members/1 
• GET /members/del/1  : 자원 삭제는 DELETE를 이용한다. DELETE /members/1

 

3) 계층 구조 및 표기 

 

• URI 끝에 슬래시(/)를 포함하지 않는다.
• 대시(-)는 단어 사이에 가독성을 높일 때 사용한다.
• 언더스코어(_)는 사용하지 않는다.
• URI 경로는 소문자만 사용한다.
• 파일 확장자는 URI에 포함하지 않는다.
• Accept Header를 사용한다(클라이언트가 받고자 하는 응답 자료 형식 지정).

 

4) 상태 코드 (HTTP Status Code)

 

상태 코드는 3자리 숫자이다. 첫째 자리는 1에서 5까지 표현되며 첫째 자리가 4와 5인 경우는 비정상적인 상태이므로 별도 조치가 필요하다. 

 

[표] HTTP 주요 상태 코드 

상태 코드	설명
200	요청은 정상 수행됨
201	자원 생성 요청 시, 자원이 생성되었음.
301	요청 URI가 변경됨. (Locaton header에 변경된 URI를 돌려주자)
400	부적절한 요청임 (거절됨)
401	인증 필요한 자원을 요청 (예; 로그인 안한 사용자 요청)
403	차단된 자원을 요청했음 (인증과 무관) <--- 400 응답을 권장함
405	해당 자원에 사용할 수 없는 Method 요청 (거절됨)
500	서버에 문제가 있음 (서버 관리자에게도 보고되어야 함)