[스터디13] 01. RESTful 웹 서비스 기본사항

목차

 

이 책은 읽기가 어려운 것 같습니다. 하지만 POST가 리소스 생성뿐만 아니라 읽기 오퍼레이션에도 사용될 수 있다는 것과 같은 새로운 정보들을 얻을 수 있어 유익했습니다.

1장. RESTful 웹 서비스 기본사항

1.1 REST API 소개

• REST(Representational State Transfer)는 2000년 로이 필딩(Roy Fielding)의 박사학위 연구에서 제시한 아키텍처 스타일이다.
• 각 URL은 API 리소스로 작동하기 때문에 엔트포인트로 동사 대신 명사를 사용해야 한다.
• GET, DELETE, POST, PUT, PATCH와 같은 HTTP 메소드는 동작을 실행하기에 동사처럼 사용할 수 있다.

클라이언트-서버 작동 방식

1. 클라이언트는 REST API를 호출하고 서버는 응답을 보낸다.
2. REST를 이용해 클라이언트가 HTTP 요청과 응답을 사용하여 원격으로(또는 로컬로) 실행 중인 서버(또는 웹 서비스)와 통신한다. HTTP 요청에는 쿼리 매개변수, 헤더, 본문 형식의 페이로드 등이 포함된다.
3. 호출된 웹 서버는 성공/실패 표시와 HTTP 응답으로 감싸진 응답 데이터를 보낸다. HTTP 상태 코드는 일반적으로 응답 상태를 나타내며 응답 본문에는 응답 데이터가 포함된다.

• RESTful 웹 서비스는 완전한 클라이언트-서버 분리를 지원한다.
• 서버 애플리케이션의 플랫폼 또는 기술 변경이 클라이언트 애플리케이션에 영향을 주지 않는다.
• 각 부분이 독립적으로 발전할 수 있어 유연성이 향상된다.

REST의 특징

• REST 호출은 스테이트리스(stateless)다.
• REST는 캐시 제어를 사용하므로 REST API를 캐시할 수 있다.
• REST는 주요 컴포넌트(리소스와 URI, HTTP 메소드, HATEOAS)를 사용해서 동작한다.

1.2 리소스와 URI 다루기

• WWW(World Wide Web) 상의 모든 문서는 HTTP 관점에서 리소스로 여겨진다. 리소스는 URI로 표시되며, 서버 상의 고유 리소스를 나타내는 엔드포인트다.
• URI는 웹에서 리소스의 위치, 이름 또는 이 둘을 모두 사용해 리소스를 식별하는 문자열을 의미한다. URL과 URN 두 가지 타입이 있다.
• URL은 리소스의 네트워크 위치를 식별하는 역할을 한다. 식별자일 뿐만 아니라 리소스에 도달하는 방법도 알려준다.
• URN은 urn이라는 스킴으로 시작하는 URI 타입을 의미하며 잘 사용되지 않는다.

# URI 구문
scheme:[//authority]path[?query][#fragment]

# URN 구문
urn:oasis:names:specification:docbook:dtd:xml:4.1.2

URI 컴포넌트 목록 

• 스킴(Scheme): 공백 없는 글자 나열에 콜론(:)이 따라온다. 문자로 시작하고 숫자, 문자, 마침표(.), 하이픈(-) 또는 더하기 문자(+)의 조합이 이어서 쓰인다.
• 권한(Authority): 선택적 필드며 //가 앞에 온다. 선택적 하위필드(사용자 정보, 호스트, 포트)로 구성된다.
• 경로(Path): 경로에는 슬래시 문자(/)로 구분된 일련의 세그먼트가 포함된다.
• 쿼리(Query): 선택적 컴포넌트로 물음표(?)가 앞에 온다. 쿼리 컴포넌트는 비계층적 데이터인 쿼리 문자열이다. 쿼리 컴포넌트에서 각 매개변수는 앰퍼샌드(&)로 구분되며 매개변수 값은 등호(=) 연산자를 사용하여 할당한다.
• 프래그먼트(Fragment): 선택적 필드로 해시(#)가 앞에 온다. 프래그먼트 컴포넌트는 부속 리소스를 가리키는 프래그먼트 식별자를 가진다.

1.3 HTTP 메소드와 상태 코드 살펴보기

HTTP 메소드

• POST: 생성(Create) 또는 검색(Search)
• GET: 읽기(Read)
• PUT: 갱신(Update)
• DELETE: 삭제(Delete)
• PATCH: 부분 갱신(Partial update)

HTTP 상태 코드

• 정보성 응답(100~199)
• 성공적인 응답(200~299)
• 리다이렉트(300~399)
• 클라이언트 에러(400~499)
• 서버 에러(500~599)

상태 코드	설명
200 OK	이미 생성된 것 이외의 성공적인 요청
201 Created	성공적인 생성 요청
202 Accepted	요청을 받았지만 아직 액션을 취하지 않음. 서버가 요청을 수락했지만 일괄 처리와 같이 즉시 응답을 반환할 수 없는 경우에 사용
204 No Content	데이터가 없는 성공적인 오퍼레이션
304 Not Modified	캐싱(caching)을 사용. 서버가 클라이언트에 리소스가 수정되지 않았다고 응답하는 것으로 클라이언트는 동일한 캐시 리소스를 사용할 수 있음
400 Bad Request	입력 매개변수가 올바르지 않거나 누락되었거나 요청 자체가 불완전하여 실패한 오퍼레이션
401 Unauthorized	인증되지 않은 요청으로 실패한 오퍼레이션. 명시적으로 인증되지 않은 것(unauthenticated)의 의미
403 Forbidden	호출이 인가되지 않아서 실패한 오퍼레이션
404 Not Found	요청한 리소스가 존재하지 않아서 실패한 오퍼레이션
405 Method Not Allowed	요청한 리소스에 대해 메소드가 허락되지 않아서 실패한 오퍼레이션
409 Conflict	중복된 생성 오퍼레이션을 시도하는 경우 실패한 오퍼레이션
429 Too Many Requests	사용자가 정해진 시간에 너무 많은 요청(rate limiting)을 보내서 실패한 오퍼레이션
500 Internal Server Error	서버 오류로 인해 실패한 오퍼레이션. 일반적인 에러
502 Bad Gateway	업스트림 서버(upstream server) 호출이 실패하여 실패한 오퍼레이션. 예를 들어 앞단이 외부 결제 서비스를 호출했으나 그 호출이 실패한 경우
503 Service Unavailable	과부하 또는 서비스 실패 등 서버에서 예상하지 못한 일이 발생해 실패한 오퍼레이션

1.4 HATEOAS이란?

• RESTful 웹 서비스는 HATEOAS라는 하이퍼미디어를 통해 동적으로 정보를 제공한다.
• 하이퍼미디어는 REST 호출 응답으로 수신하는 콘텐츠의 일부이다. 하이퍼미디어 콘텐츠에는 텍스트, 이미지, 비디오와 같은 다양한 타입의 미디어에 대한 링크가 포함되어 있다.
• 하이퍼미디어 링크는 HTTP 헤더나 응답 본문에 포함될 수 있다.

1.5 REST API 설계 베스트 프랙터스

• 엔드포인트 경로에서 리소스의 이름을 지정할 때 동사형이 아닌 명사형 단어를 사용한다.
• 엔드포인트 경로에서 컬렉션 리소스의 이름을 지정할 때 복수형을 사용한다.
• 하이퍼미디어를 사용한다.
• API 버전 관리를 한다.
• 문서는 쉽게 접근할 수 있어야 하고 각 버전의 최신 내용을 담고 있어야 한다.
• 권장되는 상태 코드를 준수한다.

 

이 글은 『스프링 6와 스프링 부트 3로 배우는 모던 API 개발』 책의 내용을 바탕으로 작성되었습니다.