REST 1탄: REST(ful) API는 무엇일까? REST를 위한 규칙

인터넷은 정보들을 하이퍼텍스트로 연결하여 정보를 공유합니다. 각 정보는 HTML의 형식으로 표현되며, URI(Uniform Resource Identifier)를 통해 정보를 식별합니다. 우리는 정보의 식별자인 URI에 프로토콜을 조합하여, 정보의 위치를 나타내는 URL(Uniform Resource Locator)을 이용하여 원하는 정보에 접근할 수 있습니다. 웹서비스에서의 프로토콜은 대부분 HTTP(HyperText Transfer Protocol)를 사용하죠. 참고로 HTTPS는 HTTP에 암호화를 더해 보안이 강화된 버전입니다.

 

REST란 기존의 HTTP를 기존의 WEB과 충돌하지 않으면서도 더 나은 방법으로 사용하기 위해 만들어졌습니다. 더 나은 방법이란 서버와 클라이언트의 독립적인 진화를 의미합니다. "서버의 기능이 변경되어도 클라이언트를 업데이트할 필요가 없다"는 것이 독립적인 진화입니다. 우리가 사용하는 웹에서 웹 페이지가 변경되어도 웹 브라우저를 업데이트할 필요가 없고 반대로 웹 브라우저를 업데이트했다고 웹페이지를 변경할 필요가 없다는 뜻입니다. 여담으로 HTML과 HTTP는 이러한 상호운용성(interoperability)을 지키기 위해 Referer라는 오타(Referrer가 올바른 철자)를 고치지 않고 두었습니다.

REST(Representational State Transfer)

출처: phpenthusiast.com, What is REST API?

REST는 분산 하이퍼미디어 시스템(예: WEB)에서 사용하는 아키텍쳐 스타일입니다. 쉽게 말해 웹에서 정보 교환을 위해 지켜야할 조건들을 정리해 놓은 것입니다. 즉 RESTful API는 REST라는 아키텍처 스타일을 지키는 API가 되는 것이죠. REST를 간단히 요약하면 리소스의 행위와 표현을 구분하는 것입니다. 위의 그림에서 행위는 HTTP methods이고 표현은 JSON와 HTTP 요청의 body를 의미합니다.

REST의 조건

1. 일관된 인터페이스(Uniform interface)
   URI로 지정한 리소스에 대한 조작을 통일하고 한적적인 인터페이스로 수행하여야 합니다. 일반적으로 표준 HTTP 메서드(GET, POST, PUT, DELETE)를 사용하며 데이터는 표준 형식(JSON 또는 XML)으로 전송됩니다.
2. 무상태(Stateless)
   REST는 작업을 위한 상태정보를 따로 저장하고 관리하지 않습니다. 세션 정보나 쿠키정보를 별도로 저장하고 관리하지 않는 대신 들어오는 요청을 단순히 처리하기만 하여야 합니다. 이를 위해서 각 요청은 해당 요청을 이해하고 처리하기 위한 모든 정보를 포함해야 합니다.
3. 자체표현성(Self-descriptiveness)
   REST의 특징 중 하나는 REST API 메시지만 보고도 이를 쉽게 이해 할 수 있는 자체 표현 구조로 되어 있다는 것입니다. API를 통해 전송되는 내용은 별도의 문서가 없어도 쉽게 이해할 수 있는 표현 구조를 갖추어야 합니다.
4. 클라이언트와 서버의 분리(Client-server)
   앞서 독립적인 진화로 언급했듯이 서버와 클라이언트는 서로 별도로 개발되어야 합니다. 이를 통해 클라이언트와 서버 각각에서 개발해야 할 내용이 명확해지고 상호간의 의존성을 줄여줄 수 있습니다.
5. 캐싱가능(Cacheable)
   REST는 HTTP의 캐싱 기능을 적용할 수 있습니다. 서버의 응답은 명시적으로 캐시 가능 또는 캐시 불가능으로 표시되어 클라이언트가 응답을 캐시하고 성능을 향상시킬 수 있어야 합니다.
6. 계층형 구조(Layered System)
   REST는 보안, 로드 밸런싱, 암호화 계층 등의 계층화된 구조로 구성될수 있습니다. 각 계층이 특정 기능을 가지고 인접한 계층과 상호 작용하도록 하여 프록시, 게이트웨이, 로드 밸런서와 같은 중간 단계를 사용할 수 있게 하여 유연성, 확장성 및 보안을 향상시킵니다.

REST 디자인 가이드

REST API를 설계할 때는 리소스에 접근할 수 있도록 URI를 만들어야 합니다. URI는 일관된 형식을 사용하며 리소스을 구분할 수 있게 명명되어야 합니다. URI를 설계할 때 모호성을 줄이고 가독성, 유지관리성을 극대화하여 사용하기 쉽도록 직관적이어야 합니다. RESTful한 API를 만들기 위해서는 클라이언트에서 요청할 리소스(정보)을 URI로 표현하여야 하고 리소스에 대한 행위는 HTTP Method로 표현하여 디자인하여야 합니다.

디자인 규칙

리소스를 중심으로 디자인하라.

클라이언트에서 액세스할 수 있는 모든 종류의 개체, 데이터 또는 서비스가 리소스에 포함됩니다. 리소스는 모두 객체이기 때문에 명사로 나타내어야 합니다. 각 리소스의 범주에 따라 일관된 이름을 사용하여야 합니다.
예를 들어

GET /users/delete/1

과 같이 행위(동사)를 URI에 표시해서는 안됩니다. 대신,

DELETE /members/1

처럼 리소스에 대한 행위는 HTTP Method를 사용하여 표현하여야 합니다. 일반적으로 조회(GET), 추가(POST), 수정(PUT), 삭제(DELETE)의 4가지 메서드를 사용합니다. 이를 통해 더 적은 주소로 더 많은 일을 할 수 있습니다.

출처: Microsoft, 웹 API 디자인 모범 사례, RESTful 웹 API 디자인

계층 관계를 나타내기 위해 슬래시(' / ')를 사용하라.

리소스 간의 계층 관계는 URI의 경로 상에서 '/'를 통해 나타내야 합니다. 단, '/' 기호는 리소스의 계층 관계를 나타내기 위함이기 때문에 URI 경로의 마지막 문자로는 사용해서는 안됩니다.

http://restapi.example.com/animals(○)
http://restapi.example.com/animals/(×)

해당 규칙은 보안 취약점과도 연관이 되는데 자세한 내용은 RESTful API 서버를 위협하는 한 글자, 슬래시를 참고하세요.

밑줄(' _ ')은 절대 사용하지 말고 필요하다면 하이픈(' - ')을 사용하라.

URI를 쉽게 읽고 해석하기 위해 필요하다면 하이픈을 사용해 가독성을 높일 수 있습니다.

http://rest-api.example.com(○)
http://rest_api.example.com(×)

URI 경로에는 소문자를 사용하라.

URI 경로에 대문자 사용은 피하도록 해야 합니다. 대소문자에 따라 다른 리소스로 인식하게 되기 때문입니다. 다만 Schem, HOST는 대소문가 구분이 없습니다. 아래 예시에서 첫번째 줄과 두번째 줄은 동일 하지만 세번째 줄은 다른 URI입니다.

http://restapi.example.com/animals
HTTP://RESTAPI.EXAMPLE.com/animals
http://restapi.example.com/ANIMALS

파일 확장자는 URI에 포함시키지 말아라.

파일 확장자는 가독성을 해치고 어떤 이점도 존재 하지 않습니다.

http://restapi.example.com/animals/1/photo(○)
http://restapi.example.com/animals/1.jpg(×)

만약 리소스의 유형을 강조 해야 할 필요가 있다면 Content-Type 헤더를 이용할 수 있습니다.

GET /animals/dogs/1/photo HTTP/1.1 Host: restapi.example.com Accept: image/jpg

리소스의 필터링을 위해서는 쿼리 파라미터를 사용하라.

리소스을 정렬, 필터링 하거나 제한된 수량을 요청 해야 할 때에는 새로운 API를 생성하지 않고 쿼리 파라미터를 활용해야 합니다. 동물 중에서 한국에 서식하는 동물을 이름순으로 정렬하도록 요청하려면 다음과 같이 만들 수 있습니다.

http://restapi.example.com/animals/?region=korea&sort=name

리소스의 구분

URI 설계와 이해를 돕기 위해 리소스를 문서와 컬렉션으로 구분할 수 있습니다.

문서(Document)

문서는 DB 상의 하나의 레코드 혹은 엔터티를 나타내는 개념입니다. 따라서 리소스의 명은 단수로 표현합니다.

http://restapi.example.com/animals/dog

컬렉션(Collection)

컬렉션은 관련된 리소스의 그룹입니다. 다음 주소에서 animals는 dog라는 문서를 포함하는 컬렉션입니다. 서버에서 관리하는 리소스의 디렉토리로도 볼 수 있습니다. 여러 문서들의 집합이기 때문에 콜렉션은 복수로 표현합니다.

http://restapi.example.com/animals/dog

참고 자료

Naver D2, DEVIEW 2017, 그런 REST API로 괜찮은가
MicroSoft, 웹 API 디자인 모범 사례, RESTful 웹 API 디자인
MDN, HTTP 리퍼러
NHN Cloud, Meetup! REST API 제대로 알고 사용하기