[Network] REST API, RESTful 이해와 설계 방법

GOAL
REST의 개념을 이해한다.
REST의 특징도 이해한다.
REST의 설계 기본 규칙과 방법을 이해한다.
RESTful의 개념도 이해한다.

REST (Representational State Transfer)

• 자원을 이름(자원의 표현)으로 구분하여 해당 자원의 상태를 주고받는 모든 것을 의미한다.
• REST는 기본적으로 웹의 기존 기술과 HTTP 프로토콜을 그대로 활용하기 때문에 웹의 장점을 최대한 활용할 수 있는 아키텍처 스타일이다.
• REST는 네트워크상에서 Client와 Server 사이의 통신 방식 중 하나이다.

구체적인 개념

HTTP URI(Uniform Resource Identifier)를 통해 자원(Resource)을 명시하고, HTTP Method(GET, POST, PUT, DELETE)를 통해 자원에 대한 CRUD Operation을 적용하는 것을 의미한다.

REST 6가지 기본 원칙

• Client–server 구조
  • 클라이언트와 서버는 서로 독립적이어야 하며, 클라이언트는 오직 URIs 리소스만 알아야한다. 클라이언트와 서버의 인터페이스가 변경되지 않는 한, 이 둘은 독립적으로 개발되거나 대체될 수 있게 유지해야한다. (관심사의 명확한 분리)
• Stateless(무상태성)
  • 클라이언트의 모든 요청에는 해당 요청을 이해할 수 있는 모든 정보가 포함되어야한다. 서버는 HTTP 요청에 대한 어떤 것도 저장하지 않는다. 컨텍스트를 유지해야하는 세션, 인증과 인가에 대한 정보 또한 클라이언트에만 보관되며, 각 요청 시 해당 정보를 모두 포함하여 서버에 요청한다.
• Cacheable
  • 서버는 Response cache-control 헤더에 해당 요청이 캐싱이 가능한 지에 대한 여부를 제공해야 한다. 이를 제공한다면 클라이언트는 Response를 캐싱하여 서버와 클라이언트 간의 상호작용을 줄이고, 성능과 서버 가용성을 늘릴 수 있다.
• Uniform interface(일관된 인터페이스)
  • 보편적인 소프트웨어 엔지니어링 원칙을 component interface에 적용하면, 전체적인 시스템 아키텍처는 단순화되고 각 상호작용에 대한 가시성이 개선된다. 이름 그대로 일관된 인터페이스를 얻기 위해 REST에서는 4가지 인터페이스 규칙을 정의하였다.
    • identification of resources : 요청 시 개별 자원을 식별할 수 있어야함
    • manipulation of resources through representations : 어떤 자원에 대해 작업하기 위한 적절한 표현과 메타데이터를 충분히 갖추고 있다면, 서버는 해당 자원을 변경, 삭제할 수 있는 정보를 가지고 있단 의미
    • self-descriptive messages : 자신을 어떻게 처리해야하는지 정보를 포함해야함
    • hypermedia as the engine of application state : 단순히 결과 뿐만이 아니라 결과에 대한 정보를 포함해야 함
• Layered system(다중 계층)
  • REST는 다중 계층 구조를 가질 수 있도록 허용한다. (예를 들어 API 서버와 DB서버 그리고 인증 서버를 따로 둘 수 있다) 그리고 각 레이어는 자기와 통신하는 컴포넌트 외 레이어에 대해서는 정보를 얻을 수 없다. 클라이언트는 REST 서버와만 상호작용할 뿐, REST가 상호작용하는 레이어나 그 외 중간 레이어들, end server에 직접적으로 요청할 수 없으며 이들의 상호작용 또한 볼 수 없다.
• Code on demand (optional)
  • 서버가 클라이언트에서 실행시킬 수 있는 로직을 전송하여 클라이언트의 기능을 확장시킬 수 있다. 이를 통해 클라이언트가 사전에 구현해야하는 기능의 수를 줄여 간소화시킬 수 있다.

REST가 필요한 이유

• 애플리케이션 분리 및 통합
• 다양한 클라이언트의 등장
• 다양한 브라우저와 안드로이드, 아이폰과 같은 모바일 디바이스에서도 통신할 수 있어야 한다.
• 멀티 플랫폼에 대한 지원을 위해 서비스 지원에 대한 아키텍처를 세우고 이용하는 방법을 모색한 결과, REST에 관심을 가지게 되었다.

REST의 장단점

• 장점
  • HTTP 프로토콜의 인프라를 그대로 사용하므로 REST API 사용을 위한 별도의 인프라를 구축할 필요가 없다.
  • Hypermedia API의 기본을 충실히 지키면서 범용성을 보장한다.
  • REST API 메시지가 의도하는 바를 명확하게 나타내므로 의도하는 바를 쉽게 파악할 수 있다.
  • 서버와 클라이언트의 역할을 명확하게 분리한다.
• 단점
  • 사용할 수 있는 HTTP Method 형태가 제한적이다.
    • 구형 브라우저가 아직 제대로 지원해주지 못하는 부분이 있다.
      • PUT, DELETE를 사용하지 못하는 점
  • 개인적인 의견으로는 행위에 대한 URI 표현이 어렵다고 생각한다.
    • URI에 행위에 대한 동사 표현이 들어가면 안된다는게 설계 규칙인데, 동사로만 표현되는 행위들을 어떻게 명사로 표현해야할까
    • ex) 서버 자동 배포하는 역할을 하는 API - POST /server/deploy
    • ex) 들어온 값을 복사하는 API - POST /copy

REST 구성 요소

• 자원(Resource) : URI
  모든 자원에 고유한 ID가 존재하고, 이 자원은 Server에 존재한다.
  Client는 URI를 이용해서 자원을 지정하고 해당 자원의 상태(정보)에 대한 조작을 Server에 요청한다.
• 행위(Verb) : HTTP Method
  HTTP 프로토콜은 GET, POST, PUT, DELETE와 같은 메서드를 제공한다.
• 표현(Representation of Resource)
  Client가 자원의 상태(정보)에 대한 조작을 요청하면 Server는 이에 적절한 응답(Representation)을 보낸다.
  REST에서 하나의 자원은 JSON, XML, TEXT, RSS등 여러 형태의 Representation으로 나타내어 질 수 있다.
  그치만 JSON 또는 XML을 통해 데이터를 주고 받는 것이 일반적이다.

REST API 설계 기본 규칙

• URI는 정보의 자원을 표현해야 한다.
  • resource는 동사보다는 명사를, 대문자보다는 소문자를 사용한다.
  • resource의 도큐먼트 이름으로는 단수 명사를 사용해야 한다.
  • resource의 컬렉션 이름으로는 복수 명사를 사용해야 한다.
  • resource의 스토어 이름으로는 복수 명사를 사용해야 한다.
• 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현한다.
  • URI에 HTTP Method가 들어가면 안된다.
    • ex) GET /members/delete/2 -> DELETE /members/2
  • URI에 행위에 대한 동사 표현이 들어가면 안된다.
    • ex) GET /members/show/1 -> GET /members/1
  • 경로 부분 중 변하는 부분은 유일한 값으로 대체한다. (id는 하나의 특정 resource를 나타내는 고유값이다)
    • ex) id=1인 student를 삭제하는 route: DELETE /students/1

REST API 설계 규칙

• 슬래시 구분자(/)는 계층 관계를 나타내는데 사용한다.
  ex) /houses/rooms
• URI 마지막 문자로 슬래시(/)를 포함하지 않는다.
  ex) /houses/rooms
• 하이픈(-)은 URI 가독성을 높이는데 사용
  불가피하게 긴 URI 경로를 사용하게 된다면 하이픈을 사용해 가독성을 높인다.
• 언더스코어는(_ )은 URI에 사용하지 않는다.
  밑줄 때문에 문자가 가려지기도 하므로 가독성을 위해 사용하지 않는다.
• URI 경로에는 소문자가 적합하다.
  RFC 3986(URI 문법 형식)은 URI 스키마와 호스트를 제외하고는 대소문자를 구별하도록 규정하기 때문
• 파일확장자는 URI에 포함하지 않는다.
  • REST API에서는 메시지 바디 내용의 포맷을 나타내기 위한 파일 확장자를 URI안에 포함시키지 않는다.
  • Accept header를 사용한다.
  • ex) /members/face/1/photo.jpg (X)
  • ex) /members/face/1
• 필터를 위해 쿼리 파라미터를 사용한다.
  정렬, 필터링, 페이징은 신규 API를 생성하지 않고 쿼리파라미터를 활용한다.

REST API 설계 예시

CRUD	HTTP Method	Route
resource들의 목록을 표시	GET	/resource
resource들의 하나의 내용을 표시	GET	/resource/:id
resource를 생성	POST	/reource
resource를 수정	PUT	/resource/:id
resource를 삭제	DELETE	/resource/:id
resource를 부분 수정	PATCH	/resource/:id

상태 코드 요약

• 1XX: 전송 프로토콜 수준의 정보 교환
• 2XX: 클라이언트 요청이 성공적으로 수행됨
• 3XX: 클라이언트는 요청을 완료하기 위해 추가적인 행동을 취해야 함
• 4XX: 클라이언트의 잘못된 요청
• 5XX: 서버쪽 오류로 인한 상태코드

RESTful 개념

RESTful은 일반적으로 REST라는 아키텍쳐를 구현하는 웹 서비스를 나타내기 위해 사용되는 용어이다.

• REST API를 제공하는 웹 서비스를 RESTful하다고 할 수 있다.
• REST 원리를 따르는 시스템은 Restful이란 용어로 지칭된다.

RESTful의 목적

이해하기 쉽고 사용하기 쉬운 REST API를 만드는 것
RESTful API를 구현하는 근본 목적은 성능 향상이 아닌 일관적인 컨벤션을 통한 API의 이해도 및 호환성을 높이는 것이다. 그러니 성능이 중요한 상황에서는 굳이 RESTful한 API를 구현할 필요는 없다.

RESTful하지 못한 경우

• ex) CRUD 기능을 모두 POST로 처리한다.
• ex) route에 resource, id 외의 정보가 들어가는 경우(/students/updateName)

전체 응답코드

응답코드	설명
100	계속
101	스위칭 프로토콜
102	처리
200	확인
201	생성됨
202	수락됨
203	신뢰할 수 없는 정보
204	내용 없음
205	콘텐츠 재설정
206	부분 콘텐츠
207	다중 상태
208	이미보고 됨
226	IM 사용
300	다중 선택
301	영구 이동
302	발견
303	기타 확인
304	수정되지 않음
305	프록시 사용
306	스위치 프록시
307	임시 리디렉션
308	영구 리디렉션
400	잘못된 요청
401	승인되지 않음
402	결제 필요
403	금지
404	찾을 수 없음
405	허용되지 않는 방법
406	허용되지 않음
407	프록시 인증 필요
408	요청 시간 초과
409	충돌
410	사라짐
411	필요한 길이
412	전제 조건 실패
413	페이로드가 너무 큼
414	URI가 너무 김
415	지원되지 않는 미디어 유형
416	범위가 만족스럽지 않음
417	예상 실패
418	나는 찻주전자(RFC 2324)
421	잘못된 요청
422	처리 할 수 없는 엔티티
423	잠김
424	실패한 종속성
426	업그레이드 필요
428	전제 조건 필요
429	너무 많은 요청
431	요청 헤더 필드가 너무 큼
451	법적 이유로 사용할 수 없음
500	내부 서버 오류
501	구현되지 않음
502	잘못된 게이트웨이
503	서비스를 사용할 수 없음
504	게이트웨이 시간 초과
505	HTTP 버전이 지원되지 않음
506	변형도 협상
507	스토리지 부족
508	루프 감지 됨
510	확장되지 않음
511	네트워크 인증 필요

Reference

https://www.restapitutorial.com/httpstatuscodes
https://gmlwjd9405.github.io/2018/09/21/rest-and-restful.html