Restful한 API 설계 규칙

Restful한 API 설계 규칙

2024. 7. 12. 22:54ㆍNestJs

728x90

API란?

API는 Application Programming Interface의 약자입니다. 서로 다른 소프트웨어 응용 프로그램이 서로 통신하고 데이터를 교환할 수 있도록 하는 일련의 규칙 및 프로토콜 역할을 합니다.

REST란?

RESTful한 API에서 ‘REST’는 어떤 의미일까요? REST란 Representational State Transfer의 약자로 서버와 클라이언트간에 데이터를 쉽게 주고 받을 수 있도록 하는 아키텍처 스타일입니다. HTTP 위에서 별도의 전송 계층없이 전송하는 아주 간단한 인터페이스입니다.

REST는 자원을 중심으로 설계됩니다. 자원은 문서, 이미지, 비디오 등 다양한 유형의 콘텐츠가 될 수 있으며, 각 자원의 이름은 고유한 URI(Uniform Resource Identifier)로 식별됩니다. 예를 들어, http://example.com/users/123와 같이 우리가 인터넷에 흔히 볼 수 있는 주소이죠. 즉, REST는 해당 자원에 대해 어떤 작업을 할 것 인지, HTTP Method*를 이용해 서버와 클라이언트간의 데이터를 주고 받을 수 있습니다.

*HTTP Method 종류

자원을 조회할 때는 GET, 새로운 자원을 생성할 때는 POST, 기존 자원을 갱신할 때는 PUT, 자원을 삭제할 때는 DELETE를 사용합니다.

REST의 장단점

장점

HTTP 프로토콜의 인프라를 그대로 사용하므로 REST API를 구현하기 위한 별도의 인프라가 필요없습니다.

HTTP 프로토콜의 표준을 최대한 활용하기 때문에 HTTP의 추가적인 장점을 함께 가져갈 수 있다.

HTTP 표준 프로토콜에 따르는 모든 플랫폼에서 사용이 가능하다.

자원의 이름과 행위를 통해 메시지를 만들기 때문에 해당 메시지가 의도하는 바를 쉽게 파악할 수 있다.

단점

사용할 수 있는 행위, HTTP 메소드가 제한적입니다.

브라우저를 통해 테스트할 일이 많은 서비스라면 쉽게 고칠 수 있는 URL보다 Header 값을 처리해야 하므로 전문성이 요구된다.

Explorer같은 구형 브라우저에서 호환이 되지 않아 지원하지 못하는 동작이 있을 수도 있습니다.

RESTful API

RESTful API란?

RESTful한 API란 위에서 언급한 REST의 원리를 따르는 API입니다. RESTful API는 이해하기 쉽고 사용하기 편리한 인터페이스를 제공하는 것을 목표로 합니다. 하지만 RESTful API를 구현하는 근본적인 목적은 성능 향상이 아니라는 점을 유의해야 합니다. 따라서 시스템의 성능이 매우 중요한 요소로 작용하는 경우에는 RESTful API를 반드시 구현해야 할 필요는 없습니다. 이러한 상황에서는 성능 최적화에 더 초점을 맞춘 다른 방식의 API 설계를 고려할 수 있습니다.

RESTful 하지 못한 경우

REST 아키텍처 스타일의 원칙을 일부 사용했다고 해서 해당 API를 RESTful하다고 말할 수는 없습니다. RESTful API라고 하려면 REST의 설계 규칙을 올바르고 일관되게 따라야 합니다. 다음은 RESTful하지 않은 API 설계의 예시입니다.

예시1) CRUD 기능을 모두 POST로만 처리하는 API

RESTful API에서는 자원에 대한 작업을 HTTP 메서드를 통해 명확하게 구분합니다. 예를 들어, 자원의 조회는 GET, 생성은 POST, 수정은 PUT 또는 PATCH, 삭제는 DELETE 메서드를 사용하는 것이 일반적입니다. 하지만 모든 작업을 POST 메서드로만 처리한다면, 해당 API는 RESTful하다고 볼 수 없습니다.

예시2) route에 resource, id 외의 정보가 들어가는 경우(/students/updateName)

RESTful API의 URI는 자원을 식별하는 데 중점을 둡니다. 따라서 URI에는 리소스의 이름과 해당 리소스의 고유한 식별자만 포함되어야 합니다. 만약 URI에 액션이나 추가적인 정보가 들어간다면, 해당 API는 RESTful하지 않습니다. 예를 들어, http://api.example.com/getUsers?sort=asc와 같은 URI는 RESTful하지 않은 설계입니다. 대신 http://api.example.com/users?sort=asc 와 같이 리소스 이름 'users'만 포함하는 것이 올바른 RESTful API 설계입니다.

REST API 설계 기본 규칙

1) URI는 정보의 자원을 표현해야 한다.

자원을 표현할 때는 동사보다는 명사를, 대문자보다는 소문자를 사용한다.

단일 자원을 나타내는 문서 이름으로는 단수 명사를 사용해야 한다.

자원의 집합을 나타내는 컬렉션 이름으로는 복수 명사를 사용해야 한다.

자원의 저장소 이름으로는 복수 명사를 사용해야 한다.

2) 자원에 대한 행위는 HTTP 메서드(GET, PUT, POST, DELETE 등)로 표현한다.

URI에 HTTP 메서드를 포함해서는 안 된다.

URI에 CRUD 기능을 나타내는 동사를 사용해서는 안 된다.

URI 경로 중 변하는 부분은 리소스를 식별하는 고유한 값으로 대체한다. (:id는 특정 리소스를 나타내는 고유 식별자이다.)

REST API 표시 규칙

1) 슬래시 구분자(/ )는 계층 관계를 나타내는데 사용한다.

예) http://restapi.example.com/houses/apartments

2) URI 마지막 문자로 슬래시(/ )를 포함하지 않는다.

URI에 포함되는 모든 글자는 리소스의 유일한 식별자로 사용되어야 하며 URI가 다르다는 것은 리소스가 다르다는 것이고, 역으로 리소스가 다르면 URI도 달라져야 한다.

REST API는 분명한 URI를 만들어 통신을 해야 하기 때문에 혼동을 주지 않도록 URI 경로의 마지막에는 슬래시(/)를 사용하지 않는다.

Ex) http://restapi.example.com/houses/apartments/ (X)

3) 하이픈(- )은 URI 가독성을 높이는데 사용

불가피하게 긴 URI경로를 사용하게 된다면 하이픈을 사용해 가독성을 높인다.

4) 밑줄(_ )은 URI에 사용하지 않는다.

밑줄은 보기 어렵거나 밑줄 때문에 문자가 가려지기도 하므로 가독성을 위해 밑줄은 사용하지 않는다.

5) URI 경로에는 소문자가 적합하다.

URI 경로에 대문자 사용은 피하도록 한다.

RFC 3986(URI 문법 형식)은 URI 스키마와 호스트를 제외하고는 대소문자를 구별하도록 규정하기 때문

6) 파일확장자는 URI에 포함하지 않는다.

REST API에서는 메시지 바디 내용의 포맷을 나타내기 위한 파일 확장자를 URI 안에 포함시키지 않는다.

Accept header를 사용한다.

Ex) http://restapi.example.com/members/soccer/345/photo.jpg (X)

Ex) GET / members/soccer/345/photo HTTP/1.1 Host: restapi.example.com Accept: image/jpg (O)

7) 리소스 간에는 연관 관계가 있는 경우

/리소스명/리소스 ID/관계가 있는 다른 리소스명

Ex) GET : /users/{userid}/devices (일반적으로 소유 ‘has’의 관계를 표현할 때)