REST API 와 Web API, 상태 코드

API

“API(Application Programming Interface, 응용 프로그램 프로그래밍 인터페이스)는 응용 프로그램에서 사용할 수 있도록, 운영 체제나 프로그래밍 언어가 제공하는 기능을 제어할 수 있게 만든 인터페이스를 뜻합니다.

주로 파일 제어, 창 제어, 화상 처리, 문자 제어 등을 위한 인터페이스를 제공합니다.

 

자바 프로그래밍을 위해서는 자바 언어가 제공하는 것들이 어떤 것이 있는지를 알아야 합니다.

그래야, 사용할 수 있겠죠?

절대값을 구하기 위해서는 어떻게 해야 할까요?

Java API문서를 읽어보면 답을 알 수 있습니다.

Math클래스의 abs()메소드를 사용하면 된다는 것을 알 수 있죠.

해당 메소드가 어떻게 내부적으로 구현되어 있는지는 문서를 봐도 알 수 없습니다.

하지만, 해당 라이브러리를 사용할 때 구현코드를 알지 못해도 인터페이스만 알면 사용할 수 있습니다.

이렇게 프로그래밍을 할 때 필요한 인터페이스를 API라고 합니다.

 

 

REST API

REST : REpresentational State Transfer

REST 형식의 API. 핵심 컨텐츠 및 기능을 외부 사이트에서 활용할 수 있도록 제공되는 인터페이스

예를 들어, 네이버에서 블로그에 글을 저장하거나, 글 목록을 읽어갈 수 있도록 외부에 기능을 제공하거나 우체국에서 우편번호를 조회할 수 있는 기능을 제거하거나, 구글에서 구글 지도를 사용할 수 있도록 제공하는 것들을 말합니다.

 

서비스 업체들이 다양한 REST API를 제공함으로써, 클라이언트는 이러한 REST API들을 조합한 어플리케이션을 만들 수 있게 되었습니다.

이를 매시업(Mashup)이라고 합니다.

 

 

REST 필수 조건

• client-server
• stateless
• cache
• uniform interface
• layered system
• code-on-demand (optional)

HTTP프로토콜을 사용한다면 client-server, stateless, cache, lared system, code-on-demand 등에 대해서는 모두 쉽게 구현 가능합니다.

 

하지만, 문제는 uniform interface

• 리소스가 URI로 식별되야 합니다.
• 리소스를 생성,수정,추가하고자 할 때 HTTP메시지에 표현을 해서 전송해야 합니다.
• 메시지는 스스로 설명할 수 있어야 합니다. (Self-descriptive message)
  • 응답 결과에 보통 JSON 메시지(다음 시간에 간단히 다루게 됩니다.)를 사용하게 되는데,
  • 이 JSON메시지가 어디에 전달되는지 그리고 JSON메시지를 구성하는 것이 어떤 의미를 표현해야만 메시지 스스로 설명할 수 있다고 말할 수 있는데, 그게 쉽지 않습니다.
• 애플리케이션의 상태는 Hyperlink를 이용해 전이되야 합니다.(HATEOAS)
  • 우리가 웹 게시판을 사용할 때, 리스트 보기를 보면, 상세보기나 글쓰기로 이동할 수 있는 링크가 있습니다.
  • 이렇게 웹 페이지를 보면, 웹 페이지 자체에 관련된 링크가 있는것을 알 수 있는데 이를 HATEOAS라고 말합니다. 이런 HATEOAS를 API에서 제공하는 것은 쉽지 않습니다.

첫 번째와 두 번째 항목은 지키기 어렵지 않은데,

메시지가 스스로 설명할 수 있어야 하는 부분과 HATEOAS를 지원하는 것은

웹과는 다르게 API로는 쉽지가 않습니다.

 

 

 

 

REST API는 쉽지 않기에 WEB API 또는 HTTP API 사용

REST의 uniform interface를 지원하는 것은 쉽지 않기 때문에, 많은 서비스가 REST에서 바라는 것을 모두 지원하지 않고 API를 만들게 됩니다.

• REST의 모든 것을 제공하지 않으면서 REST API라고 말하는 경우도 있습니다.
• REST의 모든 것을 제공하지 않고 Web API 혹은 HTTP API라고 부르는 경우가 있습니다.

우리는 2번째 방식을 따르려고 합니다.

 

 

 

Web API 디자인 가이드

1. 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현

GET: 읽기/조희 -> doGet()

POST: INSERT -> doPost()

PUT: UPDATE -> doPut()

DELETE: DELETE -> doDelete()

• GET /members/1       (o)
• GET /members/get/1   (x)
• GET /members/add      (x)
• POST /members          (o)
• GET /members/update/1  (x)
• PUT /members/1        (o)
• GET /members/del/1    (x)
• DELETE /members/1  (o)

 

2. URI는 정보의 자원을 표현해야 함

예시

• GET /members
  :  맴버의 모든 정보를 달라는 요청
• DELETE /members/1
  : HTTP Method 중의 하나인 DELETE를 이용하여 삭제를 표현해야 합니다.
  • GET /members/delete/1
    : GET은 정보 요청 시 사용. 위와 같이 동사로 삭제를 표현하면 안 됨

 

3. 슬래시 구분자(/)는 계층을 나타낼 때 사용

http://domain/houses/apartments

http://domain/departments/1/employees

• URI 마지막에 슬래시 구분자(/) 포함x
• 하이픈(-)은 URI가독성을 높일 때 사용
• 언더바(_)는 사용X
• URI경로는 소문자만 
• RFC 3986(URI 문법 형식)은 URI스키마와 호스트를 제외하고는, 대소문자를 구별
• 파일 확장자는 URI에 포함X
• Accept Header를 사용O

 

상태 코드

성공

201 상태코드는 POST 메소드보다는 PUT 메소드에 의해 원격지 서버에 파일이 생성된 경우에 쓰임...

 

클라이언트로 인한 오류

 

서버로 인한 오류