REST(Representational State Transfer) API 설계원칙

Posted by @Haon, July 19, 2024

API
REST API
- REST 의 구성 요소
URI 설계 규칙
HTTP 메소드 설계 규칙
REST API에서의 HTTP 상태 코드, 상태 메시지
참고

REST API 에 대해 이해하기 위해, 먼저 API 그 자체에 대한 이론부터 다시금 되짚어보자.

API

API 란 Application Programming Interface 의 약자로, 소프트웨어 사이에 요청과 응답을 주고받을 떄 데이터 통신을 하는 방법과 규칙을 뜻한다. 웹 프로그래밍 차원에서의 API 는 서버와 클라이언트간에 어떻게 통신할 것인지에 대한 일정한 규칙에 따라 다양한 종류로 구분된다. SOAP, RPC, REST 등 다양한 타입이 존재한다. 그 중 우리는 REST API 라는 API 의 다양한 종류 중 하나를 살펴볼것이다.

API 는 웹 애플리케이션 차원에서 제공하는 표준 스팩도 존재하지 만, 이외에도 API 는 OS 에서도 제공할 수 있고, 프로그래밍 언어에서도 제공할 수 있는 개념이다. 그 중 우리는 웹 애플리케이션 차원에서의 API 에 대해 학습하도록 한다.

REST API

REST API 는 Representational State Transfer API 의 약자다. REST 란 소프트웨어 프로그래밍 아키텍처의 한 형식이다. 쉽게말해, REST 란 웹 애플리케이션 차원에서 클라이언트와 서버 사이에 데이터를 통신시 정해놓은 특정한 통신 규약이라고 할 수 있다.

REST API 란 REST 라는 아키텍처의 제약 조건을 준수한 API 를 뜻한다. 이 REST 제약 조건을 준수한 API 를 Restful 하다고 표현한다.

그리고 유의할 점은, API 를 구현할 때 REST 라는 규칙에 따라서만 정의할 수 있는것이 아니다. REST 란 표준으로 정해진 것이 아니며, API 를 정의시 일반적으로 통용되는 규약이다. 따라서 API 를 구현시 REST 규약을 반드시 시킬 필요는 없으며, 단지 권장 사항이다.

또한 REST API 는 HTTP 프로토콜을 규악한 내용이므로, Restful 한 API 는 반드시 Stateless 하게 동작해야한다. 따라서 GET 요청들은 서로 연결되어 있지 않은 상태이어야 한다. 즉 요청들간에는 서로 독립적으로 동작해야한다.

REST 의 구성 요소

자원(Resource) by URI

REST API 는 URI 를 통해 사용할 자원을 명시한다. 보통은 이떄 URI 에 명시되는 자원은 PK 와 같은 고유한 ID 값이다.

행위(Verb) by HTTP Method

REST API 는 HTTP Method (GET, POST, PUT, DELETE 등) 를 사용하여 URI 에 명시된 자원에 대해 어떠한 행위를 수행할 것인지를 명시한다.

표현(Representation of Resource)

REST API 에서 리소스는 다양한 형태(JSON, XML, TEXT, RSS 등)로 표현될 수 있다. 보통은 JSON 또는 XML 을 통해 데이터를 주고받는 것이 일반적이다.

URI 설계 규칙

(1) 슬래시 구분자 "/" 는 계층 관계를 나타내는데 사용한다.
(2) URI 마지막 문자로 슬래시 "/" 를 포함하지 않는다.
- REST API 는 분명한 URI 를 만들어 통신해야 하기 떄문에 혼동을 주지 않도록 URI 마지막에는 슬래시를 사용하지 않는다.
(3) 하이픈 "-" 은 URI 가독성을 높이는데 사용한다.
- 불가피하게 긴 URI 경로를 사용하게 된다면 하이픈을 사용하여 가득성을 높이도록 한다.
(4) 밑줄 "_" 은 URI 에 사용하지 않는다.
- 밑줄은 보기 어렵거나 밑줄 떄문에 문자가 가려지기도 한다. 따라서 가독성을 위해 밑줄은 사용하지 않는다.
(5) URI 경로에는 소문자가 적합하다. 대문자 사용은 피하도록 한다.
- RFC 3986(URI 문법 형식) 은 URI 스키마와 호스트를 제외하고는 대소문자를 구별하도록 규정하기 떄문이다.
(6) REST API 에서는 Message Body 내용의 포맷을 나타내기 위한 파일 확장자를 URI 안에 포함시키지 않는다.
- Accept Header 를 사용한다.

HTTP 메소드 설계 규칙

HTTP Method 는 어떻게 설계하는가? 앞서 말했듯이, HTTP Method 는 URI 에 명시된 해당 리로스에 대한 행위를 표현하는 것이 주 목적이다. 따라서 URI 에 get, post, .. 등을 명시하여 행위를 표현하지 않아야 한다. 이 대신 행위는 HTTP Method 에 표현하는 것이다.

만약 유저 리스트를 받아오고 싶은 상황에서 API 를 설계한다면, URI 를 "/getUser" 로 명시하는 대신에 "/user" 로 명시하고, HTTP 메소드로 GET 요청을 선택하자.

이어서 HTTP 메소드를 아래와 같은 행위에 맞도록 선택하여 디자인하자.

GET : URI 에 명시된 리소스에 대한 정보를 가져올 때 사용한다. 일반적인 경우 HTTP 상태코드 값을 200을 반환한다.
POST : 명시된 URI 에 새로운 리소스를 생성한다. 리소스가 성공적으로 생성되었다면 HTTP 상태코드 값을 201을 반환한다. 딱히 반환할 결과가 없다면 204를 반환한다.
PUT : 명시된 URI 를 새로운 리소스로 대체하거나, 없다면 새로운 리소스를 생성한다.
PATCH : 명시된 URI 에 해당하는 리소스의 일부분 업데이트 한다. 또한 PUT 은 리소스의 모든 정보를 업데이트한다는 특징이 있는 반면, PATCH 는 리소스의 일부분만을 업데이트한다는 특징이 존재한다.
DELETE : 명시된 URI 에 해당하는 리소스를 제거한다.

삭제 성공시 빈 본문을 반환하고, 상태코드값 204를 반환한다. 존재하지 않는 리소스에 요청한 경우 404를 반환한다.

REST API에서의 HTTP 상태 코드, 상태 메시지

200번대

200번대 상태 코드들은 서버가 클라이언트의 요청을 성공적으로 처리했다는 뜻이다.

200 OK : 클라이언트 요청을 서버가 정상적으로 처리했다.
201 Created : 클라이언트의 요청을 서버가 정상적으로 처리했고, 새로운 리소스가 생겼다.
202 Accepted : 클라이언트의 요청은 정상적이지만, 서버가 요청을 완료하지 못했다.
204 No Content : 클라이언트의 요청은 정상적이다. 하지만 컨텐츠를 제공하지 않는다.

400번대

400번대 상태 코드들은 클라이언트의 요청이 유효하지 않아서, 서버가 해당 요청을 수행하지 않았다는 뜻이다.

400 Bad Request : 클라이언트의 요청이 유효하지 않아서, 더 이상 작업을 진행하지 않는다.
401 Unauthorized : 클라이언트가 인증이 되지 않아서 작업을 진행할 수 없는 경우
403 Forbidden : 클라이언트가 인증이 됐으나 권한이 없기 때문에 작업을 진행할 수 없는 경우
404 Not Found : 클라이언트가 요청한 자원이 존재하지 않는다.
405 Method Not Allowed : 클라이언트의 요청이 허용되지 않는 메소드인 경우
409 Conflict : 클라이언트의 요청이 서버의 상태와 충돌이 발생한 경우
429 Too Many Requests : 클라이언트아 일정 시간동안 너무 많은 요청을 보낸 경우

500번대

500번대 상태 코드들은 서버 오류로 인해 요청을 수행할 수 없다는 뜻이다. 클라이언트의 요청은 유효하여 작업을 진행했는데, 도중에 오류가 발생한 경우다.

API 서버의 응답에서 500번대 오류가 발생해서는 안되다. 보통 개발 과정에서 유효하지 않은 요청을 사전에 처리하지 않은 경우 400번대에서 많이 발생한다. API 서버 차원에서 완벽한 예외처리를 통해 500 번대 서버 오류 상태 코드를 방지해야 한다.

500 Internal Server Error : 서버에 대한 클라이언트와 소통을 하지 않는것이 보안적인 측면에서 더 좋기 떄문에, 서버 에러를 대부분 500 으로 통일해서 응답한다.

참고

More.

🪐 prev

데이터베이스 트랜잭션(Transaction)

🚀 next

DTO(Data Transfer Object) 의 올바른 사용 방식에 대해

Haon

꾸준히, 배움에 대한 생각을 글로 정제하기 위한 블로그입니다.

gatsby-starter-haonkakaotech