이번주에는 스프링부트 2주차 스터디를 진행했다.
REST API를 기반으로 하는 API 명세 작성에 대한 내용이었다.
파트장으로서 챌린저들의 활동 내용에 대해서 피드백을 주기 위해 추가적인 공부의 필요성을 느꼈고 질문한 내용들로부터 햇갈리는 개념이나, 잘못 알고 있는 부분이 존재한다는 것을 확인했다.
웹 검색, AI, CS책 등 다양한 자원들을 활용해 학습을 진행했고 이 내용들을 기록해놓고 두고두고 보려고 한다.
📖 API란 무엇일까?
REST API를 설명하기 전 API에 대해 먼저 정의하고 넘어가자.
API(Application Programming Interface)란
한 코드가 다른 코드와 통신할 때 사용되는 수단
을 의미한다.
여기서 코드는 백엔드, 프론트엔드, 시스템 등을 모두 포함할 수 있다.
"API를 활용하면 서로 다른 코드들 간 상호작용이 가능해진다"라는 사실을 알면 된다.
⁉️ REST API란 무엇인가?
REST는 소프트웨어 아키텍처 스타일 중 하나인 REpresentational State Transfer의 준말이다.
REST 스타일을 따르는 API를 RESTful API라고 한다.
REST API의 정의는
HTTP 프로토콜을 기반으로 자원을 URI로 식별하고 HTTP 메소드를 활용해서 CRUD를 수행하는 설계 아키텍처
이다.
HTTP 프로토콜은 기본적으로 서버-클라이언트 사이의 통신에서 작동한다.
REST역시 HTTP 기반이기 때문에 서버-클라이언트 개념을 기반으로 한다.
클라이언트는 서버에 HTTP요청으로 쿼리 매개변수, 헤더, 요청본문 형식의 페이로드 또는 입력을 보내면
서버는 클라이언트에 HTTP응답으로 성공/실패 표시와 HTTP응답으로 감싸진 응답 데이터를 전송한다.
REST관점에서 HTTP요청은 서버가 처리하기에 충분한 정보를 담고 있기에 Stateless상태이다.
따라서 REST API는 특정 상태를 유지하지 않는다.
또한 REST API는 3가지 컴포넌트를 사용해서 동작한다.
- 리소스와 URI
- HTTP메소드
- HATEOAS
이 내용에 대해서 더 작성해보려고 한다.
💎 리소스와 URI
인터넷의 모든 문서는 리소스로 여겨진다.
리소스는 URI로서 표시된다.
URI는
웹에서 리소스 위치, 이름 또는 둘 모두를 이용해서 리소스를 식별하는 문자열
을 의미한다.
URI는 URL과 URN 2가지 타입으로 나눠진다.
URL은 리소스의 전체 웹 주소를 나타내고, 스킴(프로토콜명), 호스트 이름과 포트, 경로, 쿼리(선택) 및 프레그먼트(선택)으로 이루어진다.URN은 urn 스킴으로 시작하는 URI타입을 의미하고 잘 사용되진 않는다. "urn:" <NID> ":" <NSS> 구문을 따르지만 자세히는 설명하지 않으려고 한다.
URI구문은 아래와 같이 구성된다.
Scheme:[//authority]path[?query][#fragment]
- Scheme : 공백 없는 글자 나열에 콜론이 따라옴, 문자로 시작하며 숫자, 문자, 마침표, 하이픈, 더하기문자의 조합이 이어서 쓰임.
- HTTP, HTTPS, MAILTO, FTP등이 대표적 스킴의 예시이다.
- Authority : 선택적 필드이며 //가 앞으로 온다. 사용자 정보, 호스트, 포트 정보가 선택적 하위 필드로서 구성된다.
- path : 경로에는 /문자로 구분된 일련의 세그먼트가 포함된다.
- query : 선택적 컴포넌트로 ?가 앞으로 온다. 쿼리 컴포넌트는 비계층적 데이터인 쿼리 문자열이다.
- 각 매개변수는 &로 구분되고 매개변수 값은 =연산자를 사용해 할당한다.
- fragment : 선택적 필드로 #가 앞으로 온다. 부속 리소스를 가리키는 프래그먼트 식별자를 가진다.
💻 HTTP 메소드 알아보기
REST API에서 사용하는 HTTP메서드는 대표적으로 5가지가 있다.
- POST : 생성 또는 검색
- GET : 조회
- PATCH : 부분 갱신
- PUT : 갱신
- DELETE :삭제
일부 조직에서는 REST엔드포인트의 헤더 응답을 찾는 시나리오를 위해서 HEAD메서드도 사용하기도 한다. 하지만 일반적으로는 위의 5가지 메서드만 알고있어도 문제는 없다고 생각한다.
REST에는 어떤 동작에 어떤 메서드를 사용해야 하는지 지정하는 요구사항은 특별히 없다.
그러나 널리 사용되는 업계지침 및 관행은 특정 규칙을 따를 것을 권장한다.
POST
POST는 주로 리소스를 생성하는 용도로서 사용이 되며, 예외적으로 읽기 동작에 사용하는 경우도 있다.
GET이 있는데 왜 POST를 사용하냐 라고 할 수 있는데 일반적으로 2가지 상황이 존재한다.
첫번째는 GET요청의 엔드포인트에 사용하려는 PathVariable이 민감한 정보인 경우 (User와 관련된 정보 등)이고,
두번째는 GET 쿼리의 문자열 제한인 256자를 넘어갈 정도로 매개변수가 많거나 복잡한 경우이다.
이 경우에 생성용도의 POST와 구분하기 위해 _search와 같은 파라미터를 추가하기도 한다.
GET요청은 Request body를 포함하지 않는 것이 일반적이기에 위와 같은 특수한 경우에 POST요청을 조회용으로 사용할 수 있다.
일반적으로 생성 작업으로서 POST 요청이 호출되면 성공한 경우 201 Created 상태로 응답한다.
GET
GET메서드는 일반적으로 리소스 읽기 작업의 용도로 사용된다.
앞에서 설명한 것처럼 쿼리 문자열이 256자로 제한되어있고, Request Body를 포함하지 않는다.
또한 조회 성능을 올리기 위해 GET메서드에 대해서는 캐싱을 적용한다.
캐싱을 적용하면 동일한 조회에 대해서는 서버에 요청하지 않고 캐시에서 바로 응답을 줄 수 있기에 성능이 향상된다.
성공적인 응답을 반환한 경우 200 OK 상태 코드로 연결되야 하고, Response Body가 없는 경우 204 No Content로 연결되야 한다.
PUT
PUT메서드는 일반적으로 리소스 갱신 작업 용도로 사용된다.
멱등성 보장을 위해 Request에 포함되지 않은 정보는 초기화 또는 null로 대체된다는 점이 특징이다.
따라서 PUT메서드 호출 시 리소스 전체에 대한 갱신이 발생한다.
성공적인 응답을 반환한 경우 200 OK 상태 코드로 연결되야 하고, Response Body가 없는 경우 204 No Content로 연결되야 한다.
PATCH
PATCH 메서드는 리소스 부분 갱신 작업 용도로 사용된다.
부분적인 갱신이므로 리소스 전체 데이터가 포함되지 않아도 되며 변경하고자 하는 데이터만 넣어서 보내면 된다.
일반적으로 멱등성을 보장하지 않는다는 점이 PUT과의 차이점이다.
성공적인 응답의 경우 200 OK 상태코드와 연결되어야 한다.
DELETE
DELETE 메서드는 삭제 작업과 연결된다.
성공적으로 삭제를 수행한 경우 204 No Contents로 연결된다.
HATEOAS
HATEOAS 개념은 이번에 새롭게 알게된 개념이다.
RESTful API는 HATEOAS라는 하이퍼미디어를 통해 동적으로 정보를 제공할 수 있다.
하이퍼미디어는 REST호출 응답으로 수신하는 콘텐츠의 일부로, 이 하이퍼미디어에는 텍스트, 링크, 이미지, 비디오와 같은 다양한 타입의 미디어에 대한 링크가 포함되어있다.
HATEOAS는 REST와 RPC를 구분하는 중요한 개념이다.
API 응답에 "다음에 할 수 있는 행동"을 링크로 함께 클라이언트로 전송한다는 아이디어를 바탕으로 한다.
예를 들어 "장바구니에 담기" 작업을 위한 API에 대한 응답에 "장바구니 물건 결제하기", "장바구니 조회하기", "장바구니에서 꺼내기" 와 같은 API를 링크로 전달하는 식이다.
클라이언트는 상태 분기 로직을 직접 구현할 필요 없이, 서버가 내려준 링크만 렌더링하면 되는 장점이 생긴다.
RESTful API 설계를 위한 방법
1. 리소스는 명사로 작성하기
2. 엔드포인트 경로에서 컬렉션 리소스의 이름을 지정하는 경우 복수형을 사용하기
3. 행위는 되도록 HTTP 메서드를 사용하기
간혹 login이나 sign-in과 같이 어쩔 수 없이 동사를 사용하는 경우도 있지만 되도록 동사는 엔드포인트에서 배제하는것이 좋다.
4. 계층 관계는 /로 표현하기
계층관계는 리소스간의 논리적인 계층 관계를 의미하며, 어플리케이션의 화면 구조와는 무관하다.
되도록 3단계 안으로 계층을 구성하는것이 바람직하다.
5. 소문자와 - 을 사용하여 표현 / 카멜케이스와 _는 되도록 지양
6. 필터, 정렬, 페이징 등은 쿼리 파라미터로 작성