REST API

곽태민·2023년 3월 24일

TIL

목록 보기

8/63

개요

회사에서 다른 개발자분과 협업하는 도중에 Path Parameter와 Query String의 차이점에 대해서 질문을 받았는데, 제대로 설명을 못 해드려서 정리를 해야겠다는 생각이 들었다.

여태 안다고 생각했지만 그냥 이렇게 쓰니까 썼던 것 같다는 생각이 들어서 정리를 해보게됐다.

REST

💡 Representational State Transfer의 약자로, 자원의 이름(자원의 표현)으로 구분해서 해당 자원의 상태(정보)를 주고 받는 것을 의미한다.

위에 설명하듯이 요약해보자면 자원(Resource)의 표현(Represhntation)에 의한 상태 전달을 한다.

자원(Resource)의 표현(Represhntation)
- EX) 문서, 그림, 데이터, 해당 소프트웨어 그 자체 등
- 자원의 표현 = 그 자원을 표현하기 위한 이름
- EX) DB에서 학생 정보가 자원이면 ‘Students’를 자원의 표현으로 정함.
상태(정보) 전달
- 데이터가 요청되는 시점에서 자원의 상태(정보)를 전달
- JSON or XML을 통해 데이터를 주고 받음.
월드 와이드 웹(www)과 같은 분산 하이퍼 미디어 시스템을 위한 소프트웨어 개발 아키텍처 중 하나.
- REST는 기본적으로 웹의 기존 기술과 HTTP 프로토콜을 그대로 활용하여 웹의 장점을 최대한 활용할 수 있다.
- REST는 네트워크 상에서 Client와 Server 사이의 통신 방식 중 하나다.

REST를 조금 더 구체적으로 개념을 정리하자면 HTTP URI(Uniform Resource Identifier)를 통해서 자원(Resource)를 명시하고, HTTP Method(POST, GET, PUT, PATCH, DELETE)를 통해서 해당 자원에 CRUD Operation을 적용하는 것을 의미한다.

REST는 자원 기반의 구조(ROA, Resource Oriented Architecture) 설계 중심에 Resource가 있으먀, HTTP Method를 통해서 Resource를 처리하도록 설계된 아키텍쳐를 의미한다.

또한 웹 사이트의 이미지, 텍스트, DB 내용 등의 모든 자원에 고유한 IDdls HTTP URI를 부여한다.

CRUD Operation
- Create: 생성 (POST)
- Read: 조회 (GET)
- Update: 수정 (PUT, PATCH)
- Delete: 삭제 (DELETE)
- HEAD: Header 정보 조회 (HEAD)

REST 장단점

장점
- HTTP 프로토콜의 인프라를 그대로 사용하기 때문에 REST API를 사용하기 위해서 별도의 인프라를 구축하지 않아도된다.
- HTTP 프로토콜의 표준을 최대한 활용해서 여러 추가적인 장점을 가져갈 수 있게 해준다.
- HTTP 표준 프로토콜에 따르는 모든 플랫폼에서 사용이 가능하다.
- Hypermedia API의 기본을 충실하면서 범용성을 보장한다.
- REST API 메시지가 의도하는 바를 명확하게 나타내므로 의도하는 바를 쉽게 파악 가능하다.
- 여러 서비스 디자인에서 생길 수 있는 문제를 최소화한다.
- Server와 Client의 역할을 명확히 분리한다.
단점
- 표준이 존재하지 않는다.
- 사용할 수 있는 Method의 개수가 4가지 밖에 없어서 HTTP Method 형태가 제한적이다.

REST의 필요성

애플리케이션 분리 및 통합
다양한 클라이언트의 등장
최근 서버 프로그램은 다양한 브라우저, 안드로이드폰, 아이폰 등 모바일에서도 통신 가능

REST 구성 요소

자원 (Resource): URI
- 모든 자원에는 고유 ID 존재, 이 자원은 Server에 사용.
- 자원 구별 ID = ‘users/:userId’와 같은 HTTP URI.
- Client는 URI를 이용해서 자원을 지정하며, 해당 자원의 상태(정보)에 대한 조작을 Server에 요청.
행위 (Verb): HTTP Method
- HTTP 프로토콜의 Method 사용.
- HTTP 프로토콜 = GET, POST, PUT, PATCH, DELETE와 같은 메서드 제공.
표현 (Representation Of Resource)
- Client가 자원의 상태(정보)에 대한 조작을 요청하면 Server는 이에 적절한 응답을 보냄.
- REST에서 하나의 자원은 JSON, XML 등 여러 형태의 응답으로 나타날 수 있다.
- JSON or XML을 통해 데이터를 주고 받는게 일반적.

REST API

위에 REST의 개념을 간단한게 짚고 나서 본론으로 돌아와 REST API를 소개하려고한다.

REST API는 위에서 설명한 REST를 기반으로 서비스 API를 구현한 것이다. 최근에는 OpenAPI, MSA 등을 제공하는 업체 대부분은 REST API를 제공한다.

API(Application Programming Interface)란?
데이터와 기능의 집합을 제공해서 컴퓨터 프로그램간 상호작용을 촉진해서 서로 정보를 교환 가능하도록 하는 것.

REST API 특징

REST 기반으로 시스템을 분산해서 확장성과 재사용성을 높여 유지보수와 운용을 편리하게 할 수 있다.
REST는 HTTP 표준을 기반으로 구현하므로, HTTP를 지원하는 프로그램 언어로 Client, Server를 구현할 수 있다.
REST API를 만들면 델파이 클라이언트 말고도, Java, C#, 웹 등을 이용해서 Client를 만들 수 있다.

REST API 설계 기본 규칙

URI는 정보 자원을 표현한다.
1. Resource는 동사보다 명사를 사용하고, 대문자보다는 소문자를 사용한다.
2. Resource는 Document 이름으로 단수 명사를 사용한다.
3. Resource의 컬렉션 이름은 복수 명사를 사용한다.
4. Resource의 스토어 이름은 복수명사를 사용한다.
  1. GET /User/1 → GET /users/1
자원 행위는 HTTP Method로 표현한다.
1. URI에 HTTP Method가 들어가면 안된다.
  1. GET /users/get/1 → GET /users/1
2. URI 행위에 대한 동사 표현이 들어가면 안된다. ( 기능을 나타내는 것을 넣으면 안됨.)
  1. POST /users/insert/1 → POST /users/1
3. 경로 부분 중 변하는 부분은 유일 값으로 대체 (id는 하나 특정 자원을 나타내는 고유값)
  1. user 생성 route일 경우 POST /users
  2. 고유 ID가 12인 user를 삭제하는 경우 DELETE /users/12

REST API 설계 규칙

/ 구분자는 계층 관계를 나타내는데 사용.
URI 마지막 문자로 / 를 포함하지 않는다.
-은 URI 가독성 높이는데 사용
1. 불가피하게 긴 URI는 -을 사용해서 가독성을 높인다.
_은 URI에 사용하지 않는다.
1. _은 보기 어렵거나 이것 때문에 문자가 가려지기도 해서 가독성에 좋지 않다.
URI 경로에 소문자를 사용한다.
파일 확장자는 URI에 포함하지 않는다.
자원 간 연관 관계가 있는 경우
1. /자원명/자원ID/관계 있는 다른 자원명

REST API 설계 예시

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

RESTful

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

RESTful은 REST를 REST답게 쓰기 위한 방법으로 누군가 공식적으로 정한 것은 아니다. 즉, REST 원리를 따르는 시스템은 RESTful이란 용어로 지정된다.

RESTful 목적

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