REST API는 HTTP API를 좀 더 잘 써보자고 튀어나온 일종의 약속이다.

Representational State Transfer의 약자임

뭔 개발기술이 아니라 일종의 약속이고 지향해야할 구조라고 볼 수도 있겠다.

컴퓨터 과학자인 Roy Fielding 박사가 2000년에 자신의 박사학위 논문에서 처음으로 정의했다.

API가 일종의 메뉴판이라면 그 메뉴판을 어떻게 잘 배치하고 이름짓고 할 것인가?

Rest API의 원칙

1. 균일한 인터페이스

Restful한 Api 설계, 디자인의 기본이다. 이는 서버가 표준 형식으로 정보를 전송함을 나타낸다. 형식이 지정된 리소스를 Rest에서는 표현이라고 부르는데, 이 형식은 서버 애플리케이션에 있는 리소스의 내부 표현과 다를 수 있다. 예를 들어, 서버는 데이터를 텍스트로 저장하되, HTML 표현 방식으로 전송할 수도 있다.

균일한 인터페이스에는 4가지 아키텍처 제약 조건이 있다.

• 요청은 리소스를 식별해야 한다. 이를 위해 균일한 리소스 식별자를 사용한다.
• 클라이언트는 원하는 경우 리소스를 수정하거나 삭제하기에 충분한 정보를 리소스 표현에서 가지고 있어야 한다. 서버는 리소스를 자세히 설명하는 메타데이터가 포함된 메시지를 전송한다.
• 클라이언트는 표현을 추가로 처리하는 방법에 대한 정보를 수신한다. 이를 위해 서버는 클라이언트가 리소스를 적절하게 사용할 수 있는 방법에 대한 메타데이터가 포함된 명확한 메시지를 전송해야 한다.
• 클라이언트는 작업을 완료하는 데 필요한 다른 모든 관련 리소스에 대한 정보를 수신합니다. 이를 위해 서버는 클라이언트가 더 많은 리소스를 동적으로 검색할 수 있도록 표현에 하이퍼링크를 넣어 전송한다.

2. 무상태

Rest 아키텍처에서 무상태는 서버가 이전의 모든 요청과 독립적으로 모든 클라이언트 요청을 완료하는 통신 방법을 말한다. 이게 말이 드럽게 보이는데, Stateless는 이전 벨로그 글에서도 간략하게 설명해놨다. 솔직히 이건 웹 통신 자체가 무상태성을 띈다.

3. 계층화 시스템

클라이언트는 클라이언트와 서버 사이의 다른 승인된 중개자에게 연결할 수 있다. 동시에 여전히 서버로부터도 응답을 받는다. 서버는 요청을 다른 서버로 전달할 수도 있다. 클라이언트 요청을 이행하기 위해 함게 작동하는 보안, 앱 및 비즈니스 로직과 같은 여러 계층으로 여러 서버에서 실행되도록 RESTful 웹 서비스를 설계할 수 있다. 이런 계층은 클라이언트에 보이지 않는 상태로 유지된다.

4. 캐시 가능성

서버의 응답 시간을 개선하기 위해 클라이언트 또는 중개자에 일부 응답을 저장하는 프로세스인 캐싱을 지원한다. 예를 들어 모든 페이지에 공통 머리글, 바닥글이 있는 웹사이트를 방문한다면, 머릿글과 바닥글은 캐싱하여 한 번 저장된 상태로 직접 캐시 이미지를 사용해야 한다. Restful 웹 서비스는 캐시 가능 또는 캐시 불가능으로 정의되는 API 응답을 사용하여 캐싱을 제어해야 한다.

5. 온디맨드 코드

REST 아키텍처 스타일에서 서버는 소프트웨어 프로그래밍 코드를 클라이언트에 전송하여 클라이언트 기능을 일시적으로 확장하거나 사용자 지정을 할 수 있다. 이를테면 웹 사이트에서 등록 양식을 작성하면 브라우저는 잘못된 전화번호와 같은 실수를 즉시 강조 표시한다.
음.. 일종의 Validation?

RESTful API의 장점

1. 확장성

REST API를 구현하는 시스템은 RESTful한 아키텍처가 클라이언트 - 서버 상호 작용을 최적화하기 때문에 효율적인 디자인이 가능하다.

2. 유연성

RESTful 웹 서비스는 완전한 클라이언트-서버 분리를 지원한다. 각 부분이 독립적으로 발전할 수 있도록 다양한 서버 구성 요소를 단순화하고 분리한다. 서버 애플리케이션의 플랫폼 또는 기술 변경은 클라이언트 애플리케이션에 영향을 주지 않는다. 애플리케이션 함수를 계층화하는 기능은 유연성을 더욱 향상시킨다. 이를테면, 개발자는 애플리케이션 로직을 다시 작성하지 않고도 데이터베이스 계층을 변경할 수 있다.

3. 독립성

REST API는 사용되는 기술과 독립적이다. Java에서든 JavaScript에서든 어떤 프로그래밍 언어로도 클라이언트 및 서버 애플리케이션을 모두 작성할 수 있다. 당연하게도 Rest API는 기술이 아닌 일종의 철학, 아키텍처와도 같기 때문이다. HTTP API를 그대로 사용하기 때문에 별도의 환경을 구축할 필요가 없다.

REST API의 구성요소

• 자원 (리소스) : URI
• 메서드
  - GET : 클라이언트는 GET을 사용하여 서버에 지정된 URI에 있는 리소스에 접근할 수 있다.
  • POST : 클라이언트는 POST를 사용하여 서버에 데이터를 전송한다. 여기에는 데이터와 그 데이터 포현을 포함한다.
    만약 POST 요청 이후에 클라이언트가 새로고침을 계속 눌러서 전송을 반복한다면, 동일한 리소스를 계속 생산한다.
    이에 개발자는 POST 요청이 단 1번 이루어질 수 있도록 설계해야 하는데, 일반적으론 리다이첵트를 자주 사용하는 듯.
    
  • PUT : Patch라고도 한다. 기존 리소스를 업데이트 하는 메서드다. POST와 다르게 동일한 요청을 여러번 하더라도 결과는
    동일하다. 어차피 수정요청 하는거니까 수정해도 또 그 값일거잖아?
    
  • DELETE : 클라이언트는 DELETE를 사용하여 리소스를 제거한다. DELETE 요청은 서버 상태를 변경할 수 있으며, 리소스를
    삭제하는 행위이므로, 클라이언트에게 적절한 인증이 있는지 확인해야 한다. 일반적으로 위험한 부분은 애초에 접근 자체 를 막아놔야 한다.
    
• 표현 (Representation)
  Json 등을 통해 서버와 클라이언트가 주고받는 응답을 의미한다.

• 참고사항
  REST API 아마존 웹 서비스의 설명
  

REST API 설계 예시

1. 동사보다는 명사를, 대문자보다는 소문자를

Get /members/delete/1

상기 URI는 언듯보기에 문제가 없어 보인다. 하지만 delete라는 단어는 행위를 나타내는 동사다. 리소스를 나타내는 것이 아닌 행위를 나타내므로 이는 method로 전달함이 옳다.

Delete /members/1

메서드를 delete로 바꾸면, memberId가 1인 녀석을 삭제하겠다! 라는 의도는 확실히 전달된다.
이런 모든 사항이 균일하게 적용되어야 한다. 만약 어쩔 수 없이 동사를 사용하더라도 최대한 지양해야 함.

2. _ 대신 - 을

http://velog.io/kwj1830/code-states

DB Row를 만들던 버릇대로 _를 넣기보다 - 을 넣어야 한다.

3. 파일 확장자는 URI에 포함하지 않는다.

jpg나 zip같은 파일 확장자를 URI에 포함할 이유가 없다. 필요할 경우 Accept header에 명시하는 것이 옳다.

4. 행위를 포함하지 않는다.

상기 1번 예시를 보면 된다.
만약 Item을 조회, 생산, 수정, 삭제하는 페이지가 있다고 한다면

//조회
Get /Item

// 생산
Post /Item

//수정
Put /Item/{itemId}

//삭제
Delete /Item/{itemId}

이런 방식으로 처리해야 적절할 것이다.

5. / 는 계층 관계를 나타내는데 사용하고 마지막 문자로 사용하지 않는다.

URI는 리소스의 유일한 식별자로 사용되어야 한다. 그렇기에 안붙인 것과 붙인 것의 차이를 명확하게 해야한다. 혼동을 일으키지 않기 위해 안붙이는 거로 통일해라