RESTful한 API에 대한 고찰

서론

django와 react를 사용하여 api를 활용한 간단한 사이트를 만드는 프로젝트를 진행 하다보니

자꾸만 쌓여가는 api url과 view들, 그리고 각 페이지마다 연결되지 않는 api들을 보면서

과연 RESTful한(이 때 생각한건 짧고 멋진 api url을 생각했다.) api를 설계하려면 어떻게 해야하는가 의문이 들었다.

 

**추가

여기서는 이론적인 내용을 다루고 있기 때문에 좀 더 쉽게 알고싶다면 아래 링크를 참조하는것이 좋다.

상당히 쉽고 재밌게 풀어쓴 글이라 강력하게 추천한다.

https://evan-moon.github.io/2020/04/07/about-restful-api/#restful-api

프론트엔드와 백엔드가 소통하는 엔드포인트, RESTful API

 

 

1. REST란?

먼저 "RESTful 하다" 라는걸 알기 전에 근본적인 REST가 무엇인가에 대해 조사를 해 보았다.

REST 는 REpresentational State Transfer의 약자이다 (대충 번역하자면 상태 전송 표현)

WWW과 같은 분산 하이퍼 미디어의 시스템을 위한 아키텍쳐 스타일이다.

웹에 존재하는 모든 자원에 고유한 URI를 부여해 활용하는 것이다.

REST에는 다음의 6가지 지침 제약 조건을 가지고 있으며, 인터페이스가 RESTful이라고 언급되어야 할 경우 반드시 충족되어야 하는 조건이다.

 

REST의 기본 원칙

• 클라이언트-서버 구조(Client-Server)
  자원을 가지고 있는 쪽이 서버, 자원을 요청하는 쪽이 클라이언트에 해당된다. REST 서버는 API제공, 클라이언트는 사용자 인증이나 컨텍스트(세션, 로그인 정보)등을 직접 관리하는 구조로 각각의 역할이 구분되기 때문에 클라이언트와 서버에서 개발해야 할 내용이 명확해지고 서로간의 의존성이 줄어든다.
• 무상태 (Stateless)
  모든 클라이언트-서버 작업은 상태를 저장하지 않아야(Stateless) 하며, 필요한 모든 상태 관리는 서버가 아닌 클라이언트에서 수행되어야한다. 따라서 세션이나 쿠키와 같은 정보들은 전적으로 클라이언트에 유지된다.
• 캐시 처리 가능 (Cacheable)
  캐시 불가능으로 명시적으로 표시하지 않는 한 모든 리소스는 캐싱을 허용한다.
  REST는 HTTP라는 기존 웹표준을 그대로 사용하기 때문에, HTTP가 가진 캐싱 기능이 적용 가능하다.
  Last-Modified태그나 E-Tag를 이용하면 캐싱 구현이 가능하다.
• 인터페이스의 일관성 (Uniform interface)
  URI에 대한 요청을 통일되고, 한정적으로 수행하는 아키텍처 스타일을 말한다.
• 계층화 (Layered System)
  REST는 여러 계층의 서버로 구성된 아키텍쳐를 허용한다
  API서버 앞단에 사용자 인증, 암호화(ssl) 등의 계층을 추가하여 구조상의 유연성을 둘 수 있다.
• Code on demand (선택 조건)
  REST를 사용하면 애플릿 또는 스크립트 형식으로 코드를 다운로드하고 실행하여 클라이언트 기능을 확장 할 수 있다. 그러니까 서버에서 클라이언트에 실행 코드를 보낼수 있다는것이다.

 

 

여기서 REST API로 가기 전에 잠깐 API에 대해 잠깐 알아보자

2. API란?

API의 뜻을 잠깐만 알아보자면

API (Application Programming Interface)는 애플리케이션 소프트웨어를 구축하고 통합하기 위한 정의 및 프로토콜 세트이다.

API를 사용하면 구현 방식을 알지 못해도 제품 또는 서비스가 서로 커뮤니케이션(데이터를 주고 받는 행위)을 할 수 있으며 애플리케이션 개발을 간소화하여 시간과 비용을 절약할 수 있다.

 

3. REST API

REST와 API에 대하여 조금은 알았으니 REST API에 대하여 알아보자.

 

REST API의 구성요소

Rest API의 구성으로 Resource(자원), Verb(행위), Representaions(표현)이 있다.

구성요소	내용	표현 방법
Resource	자원	HTTP URI
Verb	자원에 대한 행위	HTTP Method
Representaions	자원에 대한 행위의 내용	HTTP Message Pay Load

 

REST API 디자인 방법

모델 URI 생성시

URI는 동사나 연산을 사용하지 않는다. URI는 모두 명사여야 한다.

 

일관성이 핵심이다

최소한의 모호성과 최대한의 가독성 및 유지관리를 위해 일관된 리소스 명명 규칙과 URI 형식을 사용한다.

• 슬래시(/)를 사용하여 계층 관계를 나타낸다

http://example.com/user 
http://example.com/user/{id}

 

• URI에서 후행 슬래시(/)를 사용하지 마라
  URI 경로의 마지막 문자인 슬래시 (/)는 의미있는 값을 추가하지 않으며
  혼동을 일으킬수 있으므로 없애버리는게 낫다.

http://example.com/user/
http://example.com/user

 

• 하이픈 (-)을 사용하여 URI 가독성 향상

http://example.com/device-management/managed-devices // 읽기 쉬움 
http://example.com/device-management/ManageDevices // 가독성이 낮다

 

• 밑줄 (_)을 사용하지 마라
  구분 기호로 하이픈 대신 밑줄을 사용할 수 있다. 그러나 글꼴에 따라 밑줄 (_) 문자가 일부 브라우저나 화면에서 부분적으로 가려지거나 완전히 숨겨질 수 있다.
  이런 혼동을 피하려면 밑줄(_) 대신 하이픈(-)을 사용하자.
  
• URI에는 소문자 사용
  URI 경로에서 소문자가 일관되게 선호되어야한다
  RFC3986(URI 문법 형식)은 스키마 및 호스트 구성요소를 제외하고 URI를 대소문자를 구분하는 것으로 정의하기 때문이다.

http://api.example.org/my-folder/my-doc //1 
HTTP://API.EXAMPLE.ORG/my-folder/my-doc //2 
http://api.example.org/My-Folder/my-doc //3

 

• 파일 확장자를 사용하지 마라
  파일 확장자는 별로 좋게 보이지 않고 이점도 없다. 제거하면 URI 길이도 줄어들으니 쓸 이유가 없다.

 

URI에서 CRUD 함수 이름을 사용하지 마라

URI는 리소스에 대한 작업이 아니라 리소스를 고유하게 식별하는데 사용해야한다.
HTTP 요청 메소드를 사용하여 수행되는 CRUD 기능을 표시해야한다.

 

표현 결정

대부분 표현은 XML 또는 JSON형식으로 정의한다.

당연한 이야기지만 리소스를 반환할 때 가장 중요한 정보만 포함하자.

페이로드의 크기가 작게 유지되므로 REST API의 성능이 향상된다.

 

4. 그래서 REST API(RESTful API)가 뭔데?

가장 근접한 답은 REST의 규칙을 지키면서 설계된 API를 Rest API 혹은 Restful API라고 하지만 공식적으로 정해둔 내용이 아니다.

하지만 RESTful의 목적은 이해하기 쉽고 사용하기 쉬운 REST API를 만드는 것이다.

 

5. 번외

HTTP 메서드 할당

REST API를 사용하면 가능한 모든 CRUD 작업이 포함된 모든 종류의 웹 애플리케이션을 개발할 수 있다.
REST 지침은 서버에 대한 특정 유형의 호출에 대해 특정 HTTP 메서드를 사용하도록 제안한다.(물론 그렇게 따르지 않아도 된다)
아래의 표는 그 메서드를 모아놓은 목록이다.

Method	역할
GET	GET 요청을 사용하여 리소스 표현/정보 만 검색하고 어떤식으로든 수정해서는 안된다. GET은 리소스의 상태를 변경하지 않기 때문에 안정한 방법이라고 한다. 또한 GET API는 멱등적이어야 한다.
POST	POST API를 이용하여 새 하위 리소스를 생성한다 서버에 생성된 경우 응답은 HTTP 응답코드(201 Created)여야 하며 요청 상태를 설명하고 새 자원을 참조하는 개체와 위치 헤더를 포함해야 한다 POST 메서드에서 수행한 작업으로 인해 URI로 식별할 수 있는 리소스가 생성되지 않을수 있다. 이 경우는 200(OK) 또는 204(No Content)가 적절한 응답상태이다
PUT	PUT API는 기존 리소스를 업데이트한다(리소스가 없는 경우 API가 새 리소스를 만들지 여부를 결정할 수 있음) PUT API에 의해 새 리소스가 생성된 경우 201(Created), 수정된 경우 200(OK) 또는 204(No Content)응답 코드를 전송하여 요청이 성공적으로 완료되었음을 표시해야 한다. PUT은 리소스 전체를 교체하는 경우에 사용한다.
PATCH	HTTP PATCH요청은 리소스를 부분적으로 업데이트 하는것이다. 기존 리소스를 부분적으로 업데이트 하는데 사용한다. 단 PATCH를 지원하지 않는 프레임워크가 많다.
DELETE	DELETE API는 리소스를 삭제하는데 사용된다. DELETE 요청의 성공적인 응답은 상태를 설명하는 엔터티가 포함되어 있으면 200(OK), 작업이 대기중인 경우202(Accepted) 작업이 수행되었지만 응답이 없는경우 204(No Content)

 

RESTful API를 위한 HTTP 메서드 요약

아래 표는 위에서 설명한 HTTP 메서드의 사용을 요약한 것이다

HTTP METHOD	CRUD	전체 컬렉션 (E.G. /USERS)	SPECIFIC ITEM (E.G. /USERS/123)
POST	Create	201 (Created), 새 ID를 포함하는 /users/{id}에 대한 링크가있는 'Location'헤더	단일 리소스에 POST를 사용하면 안됨
GET	Read	200 (OK), 사용자 목록, 페이징처리, 정렬이나 필터링을 사용하여 많은 리스트를 사용하라	단일 사용자. 200 (OK) ID가 없거나 유효하지 않는경우. 404 (Not Found),
PUT	Update/Replace	405 (메소드 미허용), 전체 리소스 모음의 모든 리소스를 업데이트 하지 않는 경우	200 (OK) 또는 204 (No Content). ID가 없거나 유효하지 않은 경우 404 (찾을 수 없음)를 사용한다
PATCH	Partial Update/Modify	405 (메소드 미허용), 전체 리소스 모음의 모든 리소스를 업데이트 하지 않는 경우	200 (OK) 또는 204 (No Content). ID가 없거나 유효하지 않은 경우 404 (찾을 수 없음)를 사용한다
DELETE	Delete	405 (메소드 미허용), 전체 리소스를 삭제하지 않으려면 주의해야한다	200 (OK). ID를 찾을수 없거나 유효하지 않은경우 404 (Not Found),

 

멱등성

한번 또는 여러번 실행하면 동일한 결과를 생성하는 작업을 멱등성이라고 한다.
의도하지 않은 효과를 일으키지 안고 필요한만큼 자주 작업을 반복하거나 재시도 할 수 있음을 의미하므로 많은 상황에서 편리한 속성이다.
비 멱등성 연산의 경우 알고리즘 연산이 이미 수행되었는지 여부를 추적해야 할 수 있다.

GET, PUT, DELETE, HEAD 메서드는 멱등성 메서드로 선언된다.
OPTIONS 및 TRACE는 본질적으로 멱등성이다.

 

HTTP GET, HEAD, OPTIONS 및 TRACE

GET, HEAD, OPTIONS및 TRACE방법은 서버의 리소스 상태를 변경하지 않는다. 순전히 해당 시점에서 리소스 또는 메타 데이터를 검색하기위한 것이다. 따라서 여러 요청을 호출하면 서버에 쓰기 작업이 없으므로 GET, HEAD, OPTIONS 및 TRACE는 멱등적이다.

 

HTTP POST

단 POST 메서드는 비 멱등성에 해당된다.
동일한 POST를 N번 호출하면 서버에 N개의 새 리소스가 있다. 따라서 POST는 멱등성이 아니다.

 

HTTP PUT

PUT API를 N번 호출하면 첫번째 요청이 리소스를 업데이트 한다. 나머지 N-1 요청은 동일한 리소스 상태를 반복해서 덮어 쓰고 사실상 아무것도 변경하지 않는다. 따라서 PUT은 멱등적이다.

 

HTTP DELETE

N개의 유사한 DELETE 요청을 호출하면 첫번쨰 요청은 리소스를 삭제하고 200(OK) 또는 204(No Content)응답을 준다. 다른 N-1개의 요청은 404(Not Found)응답이 온다. 당연히 응답은 첫번째와 다르지만 원래 리소스가 이미 삭제되었기 때문에 서버측의 리소스에 대한 상태 변경은 없다. 따라서 DELETE는 멱등적이다.

 

글을 마치며

이번 포스팅에선 아주 이론적인 내용으로만 가져왔다.

어느정도 이해하는 내용이지만 대개 사용하지 않았던 내용들이라 쉽게 풀지 못하고 이론적으로만 서술했다.

이 글을 보고 잘 이해가 되지 않는다면 포스팅 내 서론 부분에 링크된 포스팅이 있으니 그 내용을 참고하면 될것같다.

 

참고

REST

https://restfulapi.net/

https://mangkyu.tistory.com/46?category=925341

REST API 설계규칙

https://velog.io/@stampid/REST-API%EC%99%80-RESTful-API

기타

https://restfulapi.net/