RESTful API - REST는 무엇이고, 어떻게 구성되어 있을까? URI는 어떻게 작성해야 할까? (Query / Path parameter)
Basic CS
RESTful API?
Rest한 API, REST API라고도 한다.
REST하게 API를 제공하는 것
프론트엔드에서 백엔드 API를 호출할 때 정해진 url을 엔드포인트로 삼아 요청을 하게 된다.
이 때 이 url을 어떻게 구성할 것인지 규칙을 정하게 되는데, RESTful API란 REST하게 규칙을 지켜 이 url을 작성하여 사용한 API를 말한다.
API가 정확하게 뭘까?
Application Programming Interface (API)
소프트웨어가 다른 소프트웨어로부터 지정된 형식으로 요청과 응답을 주고받는 수단을 말한다.
💎 RESTful API의 특징
1. Uniform Interface
URI로 지정한 리소스에 대한 조작을, 통일된 인터페이스로 수행한다.
2. self-descriptiveness
그 자체만으로도 API의 목적이 쉽게 이해된다.
3. Stateless
작업을 위한 상태정보(세션/쿠키 정보)를 별도로 저장하고 관리하지 않는다. API서버는 들어오는 요청만을 단순히 처리하면 되기 때문에 서비스의 자유도가 높아지고 구현이 단순해진다.
4. Cacheable
HTTP기존 웹표준을 그대로 사용하기 때문에 웹의 기존 인프라를 그대로 활용할 수 있다. 즉, HTTP가 가진 캐싱기능이 적용가능하다.
5. Client-server구조
REST 서버는 API 제공, 클라이언트는 사용자 인증이나 로그인 정보등을 직접 관리하는 등 각각의 역할이 확실히 구분되어 각 영역에서 개발할 내용이 명확해지고 서로간의 의존성이 줄어든다.
6. 계층형 구조 (Layered System)
다중 계층으로 구성될 수 있으며 보안, 암호화 계층을 추가해 구조상의 유연성을 둘 수 있고, 게이트웨이같은 네트워크 기반 중간 매체를 사용할 수 있다.
*(참고) REST 외에 이러한 설계규칙으로는 GraphQUL, SOQP, GRPC등이 있다.
아직 와닿지 않는다. 좀 더 쉽게 풀어 정리해보자.
서버에 REST API로 요청을 보낼 때는 HTTP라는 규약을 따른다.
HTTP로 요청을 보낼때 REST API에서는 CRUD를 위해 GET, DELETE, POST, PUT, PATCH 5가지의 HTTP 메서드를 주로 사용한다.
REST가 무엇인지 짚고 넘어가자.
💎 REST
Representational State Transfer
자원 Resource의 표현 Representation에 의한 상태전달
웹에 존재하는 자원에 고유한 URI를 부여하여 자원에 대한 주소를 지정하는 규칙으로, 네트워크 상에서 클라이언트와 서버가 통신하는 방식 중 하나이다.
API 시스템을 구현하기 위한 설계규칙 중 하나로, 가장 널리 사용되는 형식이다.
가장 큰 특징은 각 요청이 어떤 정보나 데이터를 위한 것인지 요청 자체로 추론 가능하다는 것이다.
왜 이것이 중요한 특징일까?
요청을 보내는 주소만으로도 어떤 요청인지 추론이 쉽기 때문에 다른 개발자들이 읽고 이해하기 쉽도록 코드를 작성할 수 있다.
💎 REST, 어떻게 사용할까?
어떤 자원에 대해 CRUD연산을 수행하기 위해 URI로 GET, POST등의 메서드를 사용해 요청을 보내며, 요청을 위한 자원은 특정한 형태(Representation of Resource, 자원의 표현에 의한 상태전달)로 표현된다.
Representation of Resource라는 표현 자체가 생소한데, 이에 대한 내용은 아래에 따로 적어두었다.
웹상에서 사용되는 여러 리소스를 HTTP URI로 표현하고 그 리소스에 대한 행위를 HTTP method로 정의하는 방식. 즉, 리소스를 어떻게 한다(HTTP Method + payload)를 구조적으로 표현한다.
더 명확하게는, 다음과 같은 구성으로 이루어져 있다.
- 자원(RESOURCE) - URI
- 행위(Verb) - HTTP METHOD
- 표현(Representations)
따라서 REST API를 설계하기 위해서는
1. URI에 정보의 자원을 표현해야 하며,
2. 자원의 대한 행위는 HTTP MEthod로 표현해야 한다.
3. 표현(Representation of Resource) : 클라이언트가 자원의 상태에 대한 조작을 요청하면 서버는 이에 적절한 응답(Representation)을 보낸다. REST에서 하나의 자원은 JSON, XML 등 여러 형태의 Representation 으로 나타낼 수 있다.
URI가 뭘까? URL과는 다른걸까?
🔹 URI (Resource, 자원)
Uniform Resource Identifier
하나의 리소스를 가리키는 문자열로, 가장 흔한 URI는 URL이다.
URL은 웹 상에서의 위치로 리소스를 식별하는 URI이다.
Uniform?
Uniform Interface는 URI로 지정한 리소스에 대한 조작을 통일되고 한정적인 인터페이스로 수행하는 아키텍처 스타일을 말한다.
*URN이라는 URI도 있는데, 주어진 이름공간안의 이름으로 리소스를 식별하는 것으로, 도서의 ISBN을 그 예시로 들 수 있다.
모든 자원에는 고유한 ID가 존재하고, 이 자원은 서버에 존재하므로, 원하는 특정 자원을 URI를 통해 식별해 지정하고, 이 자원을 어떻게 처리할 것인지(CRUD) 상태조작을 서버에 요청한다.
URI 작성시 주의할 점
- /구분자를 사용해 자원의 계층 관계를 나타내는데 사용한다.
- URI 마지막 문자로 /를 포함하지 않는다.
- 불가피하게 URI가 길어질 경우-를 사용해 가독성을 높인다.
- URI 정보를 명확하게 표현해야 한다.
- resource는 동사가 아닌 명사를 사용한다.
GET/user/show/1 //Bad- resource에 대한 행위를 HTTP method로 표현하기 때문에 URI에 메소드가 포함되면 안된다.
GET delete/user/1dl //Bad
DELETE/users/1 //Good- resource 사이에 연관관계가 있는 경우 차례대로 작성한다.
/리소스/고유ID/관계 있는 리소스
GET/users/{user_id}/profileCRUD?
🔹 CRUD (Method)
대부분의 컴퓨터 소프트웨어가 가지는 기본적인 데이터 처리 기능으로, Create, Read, Update, Delete를 말한다. 사용자 인터페이스가 갖추어야 할 기능을 가리킨다.
이 5가지의 용도가 정확하게 정해져있는 것은 아니다. 예를들면, POST로도 데이터를 지우고, 업데이트할 수 있다. 하지만 이 5가지를 구분해서 사용하는 이유는 사용하는 것만으로도 의미를 쉽게 알 수 있도록, 즉 RESTful 하게 API를 만들기 위함이다. 즉, 목적에 따라 구분해 사용하는 것이다.
- GET : Read
- POST : Create
- PUT, PATCH: Update (put은 정보를 통째로 변경할때, PATCH는 정보 중 일부를 특정 방식으로 변경할 때 주로 쓰인다.)
- DELETE : Delete
즉, RESTful API는 어떤 URI를 사용하고 어떤 메서드를 사용할지에 대한 규칙을 따르는 API로, 그 요청만으로도 쉽게 용도와 목적을 파악할 수 있도록 하는 것이다.
만약 한 번에 여러 종류의 정보를 다루어야 한다면,
RESTful API는 그 코드만으로 하나의 목적을 추론할 수 있어야 하기 때문에
이를 나누어서 여러 개의 endpoint를 RESTful하게 작성한뒤,
프론트엔드 개발자가 동시에 호출하는 것이 좋다.
우리는 마켓 컬리 클론 프로젝트에서 장바구니 페이지에서 위의 메서드를 적극적으로 사용했다.
- 각각 장바구니 데이터를 GET을 사용해 불러오고,
- POST를 사용해 장바구니에 상품을 담고,
- PATCH를 사용해 수량 변경을 하고,
- DELETE를 사용해 장바구니에 담겨있던 상품을 삭제했다.
🔹 Representation of Resource (표현)
클라이언트와 서버가 데이터를 주고받는 형태
이 용어가 생소하게 느껴졌는데, 클라이언트와 서버가 데이터를 주고받는 형태로서 JSON, XML, TEXT, RSS등이 있다.
주로 JSON, XML을 통해 데이터를 주고 받는 것이 일반적이다.
💎 URI 작성 - query/path parameter
🔹 query parameter (GET parameter)
url?key=value
- 필터링,정렬,검색 시에 사용한다. ?뒤 부터 query parameter를 사용하며, 여러개의 조건을 함께 사용할 때는 &을 사용해 연결한다.
우리는 다음과 같이 사용했다.
![]
🔹 filtering
GET/products?price=3000원
🔹 searching
GET/users?search=name
- GET method를 사용해 특정 정보를 호출한다.
- 검색 키워드는 body를 통해 전달하지 않고 query string을 활용한다.
마켓컬리 클론프로젝트에서는 상품 카테고리 페이지에서,대카테고리와 소 카테고리의 아이디를 각각 지정해 필터링된 상품의 데이터를 백엔드에서 불러와 보여줄 수 있도록 했다.
🔹 pagination
GET/products?offset=0&limit=100
마켓컬리 클론프로젝트에서는 메인페이지에서 보여줄 각 상품들의 컬렉션을 번호로 지정하고, 어느 인덱스부터 몇 개를 가져올 것인지 지정해주었다.
🔹 sorting
마켓컬리 클론프로젝트에서는 상품목록페이지에서 특정 카테고리의 데이터를 특정기준으로 sort해오기 위해 다음과 같이 URI를 작성했다.
🔹 path parameter
정렬,필터, 검색 기능에는 query parameter를 사용하면 된다면,
특정 리소스를 명시해 가져올 때는 path parameter를 쓰는 것이 좋다.
두 가지를 비교하면,
아이디가 123인 사용자의 데이터를 요청한다고 할 때
- query parameter :
/users?id=123 - path parameter:
/users/123
이렇게 작성할 수 있다.
path parameter를 사용한다면 CRUD기능을 요청할 때마다 HTTP메서드만 바꾸어주면 된다.
/users [GET] # Fetch a list of users
/users [POST] # Create new user
/users/123 [PUT] # Update user
/users/123 [DELETE] # remove user즉, 추가적인 엔드포인트 없이 간결하고 예측 가능하게 API를 작성할 수 있다.
Reference
