소라브 샤르마, 『스프링 6와 스프링 부트 3로 배우는 모던 API 개발』 1장

1장 RESTful 웹 서비스 기본사항

REST API

• REST는 REpresentational State Transfer의 줄임말
• RESTful 웹서비스란 REST 스타일을 따르는 웹서비스

REST의 역사

• REST가 사용되기 전에는 웹 애플리케이션들을 서로 연결하기 위해 SOAP(Simple Object Access Protocol)을 사용
  SOAP는 그 뜻과 달리 서비스 간 통신 방법이 단순하지 않음
• 2000년에 로이 필딩이 REST 제시
• SOAP에 비해 REST는 커뮤니케이션은 단순화하고 통합은 더 쉬워짐
  HTTP 위에서 작동하기 때문에 웹 전반과 내부 네트워크에서 사용할 수 있음 
• REST API를 최초로 활용한 회사는 이베이

REST 기본원리

• HTTP 프로토콜 위에서 작동
• 각 URI는 API 리소스로 동작하기 때문에 엔드포인트로 동사 대신 명사 사용
  HTTP 메서드로 역할 구분
• REST 호출은 stateless. 특정 상태를 유지하지 않음. 
• REST 관점에서 HTTP의 모든 표현(representation)은 자체 설명적(self-descriptive)이기 때문에 클라이언트는 표현(HTTP 응답)을 캐시한다. 
• REST는 다음 3개의 중 컴포넌트를 사용해서 동작한다. 
  리소스와 URI, HTTP 메서드, HATEOAS

---

URI

• 웹상의 모든 문서는 HTTP 관점에서 리소스로 여겨진다. 
  이 리소스는 URI로 표시되며, 서버 상의 고유 리소스를 나타내는 엔드포인트다. 
• URI란 웹에서 리소스의 위치, 이름, 또는 이 둘을 모두 사용해 리소스를 식별하는 문자열을 의미한다. 
• URI의 종류에는 URI와 URN이 있다. 

URI 구문

scheme:[//authority]path[?query][#fragment]

스킴(scheme)	공백없는 글자 나열에 콜론이 따라온다 문자로 시작하고 숫자, 문자, 마침표, 하이픈 또는 더하기 문자의 조합이 이어서 쓰인다 HTTP, HTTPS, MAILTO, FILE, FTP 등이 스킴의 대표적 예시다.  URI 스킴은 반드시 IANA(Internet Assigned Numbers Authority)에 등록되어 있어야 한다.
권한(Authority)	선택적 필드이며 //가 앞에 온다  다음과 같은 선택적 하위 필드로 구성된다   - 사용자 정보 : 선택사항이며 사용자 이름과 암호를 포함할 수 있는 하위 컴포넌트를 의미한다.   - 호스트 : IP 주소 또는 등록된 호스트 또는 도메인 이름을 포함하는 하위 컴포넌트다.   - 포트 : 콜론 뒤에 오는 선택적 하위 컴포넌트다.
경로(Path)	경로에는 슬래시 문자로 구분된 일련의 세그먼트가 포함된다.
쿼리(Query)	선택적 컴포넌트로 물음표가 앞에 온다.  쿼리 컴포넌트에서 각 매개변수는 앰퍼샌드로 구분되며 매개변수 값은 등호 연산자를 사용하여 할당한다.
프래그먼트(Fragment)	선택적 필드로 해시(#)이 앞에 온다.  프래그먼트 컴포넌트는 부속 리소스를 가리키는 프래그먼트 식별자를 가진다

URL

• URL은 URI의 부분집합이며 리소스를 식별하는 기능뿐만 아니라 기본 액세스 매커니즘을 설명하여 리소스를 찾는 방법을 제공한다. 
• URL은 리소스의 전체 웹 주소를 나타내며, 프로토콜 이름(스킴), 권한 컴포넌트의 일부인 호스트 이름과 포트, 경로 등을 포함한다. 

URN

• 스킴으로 시작하는 URI타입이며, 잘 사용되지 않는다. 

---

HTTP 메서드

다양한 HTTP 메서드가 존재하지만 주로 5개가 사용된다. 

POST	일반적으로 리소스 생성 오퍼레이션이지만 예외적으로 읽기 오퍼레이션에 사용하는 경우도 있다 GET 호출 길이 제한을 초과하거나 보안이 필요한 매개변수가 존재하는 경우이다.
GET	일반적으로 리소스 읽기 오퍼레이션과 연결된다.
PUT	일반적으로 리소스 갱신 오퍼레이션과 연결된다.
DELETE	리소스 삭제 오퍼레이션과 연결된다.
PATCH	리소스 부분 갱신 오퍼레이션과 연결된다.

HTTP 상태코드

• 100번대 : 정보성 응답
• 200번대 :  성공적인 응답
• 300번대 :  리다이렉트
• 400번대 :  클라이언트 에러
• 500번대 :  서버 에러

코드별 자세한 설명은 아래 링크 참조

https://developer.mozilla.org/en-US/docs/Web/HTTP/Status

HTTP response status codes - HTTP | MDN

HATEOAS

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

---

REST API 설계 베스트 프랙티스

명사형 단어 사용

• REST는 명령이 아닌 상태를 전송하기 떄문에 엔드포인트 경로에는 항상 리소스 이름 사용
• HTTP 메서드와 함께 사용하기 때문에 리소스명만 명시하면 됨

컬렉션 리소스의 이름을 지정할 때 복수형 사용

• 리소스가 리스트인 경우 리소스 이름을 복수형으로 사용

하이퍼미디어 사용

• 응답에 명시적으로 URL 링크를 제공하면 REST 클라이언트 작업을 더 쉽게 만든다

API 버전 관리

• Accept 헤더에 버전을 명시하거나 엔드포인트 경로에 버전을 추가한다

중첩된 리소스

• 중첩되거나 특정 관계가 있는 리소스에 대한 엔드포인트는 어떻게 구성해야 할까? 
• 중첩된 엔드포인트 접근 방식을 사용하거나 하이퍼미디어와 결합한다. 

API 보안

• 암호화된 통신을 위해 HTTPS를 사용한다
• 항상 OWASP의 주요 API 보안 위협 및 취약점을 살핀다. 
• 보안 REST API에는 인증이 있어야 한다. 쿠키나 세션을 사용하면 안된다. JWT또는 OAuth 2.0 기반 토큰을 사용하여 보안을 유지해야 한다. 

문서 유지 관리

• 문서는 접근이 쉬워야하고 각 버전의 최신 내용을 담고 있어야 한다. 
• 샘플 코드와 예제를 제공하는 것이 좋다

권장되는 상태 코드 준수

캐싱 보장

• REST API 응답에 캐싱 관련 헤더를 추가하면 캐싱을 보장할 수 있다. 
• REST API 응답에 추가할 수 있는 헤더는ETag, Last-Modified가 있다

단위시간당 요청량 제한 유지 관리

• 단위시간당 요청량을 초과한 경우 429(Too Many Requests)를 반환한다. 
• 단위시간당 요청량 제한이 초과되기 전에 X-Ratelimit-Limit(현재 기간에 허용된 요청수), X-Ratelimit-Remaining(현재 기간에 남은 요청 수), X-Ratelimit-Reset(현재 기간의 남은 시간초), X-Ratelimit-Used(현재 기간에 사용된 요청수) 헤더를 사용하여 경고를 전달할 수 있다. 

---

전자 상거래 앱 소개

책에서는 이커머스 앱을 예시로 사용한다. 

하위 도메인

• 사용자
• 카트
• 제품
• 주문
• 결제
• 배송

앱 아키텍쳐

---