예시로 알아보는 RESTful API

jomminii_before·2020년 4월 12일

위코드에서 프로젝트를 할 때도 RESTful API에 대해서 고민을 하면서 진행하긴 했지만, 브랜디에서 인턴을 하면서 좀 더 타이트한 개념 적용을 요구 받고 있는데요, 기본 개념을 먼저 짚어보고 실제로 RESTful API를 적용한 내용도 살펴보도록 하겠습니다. 기본 개념은 참고자료에 나와있는 문구들을 많이 참고하였고, 예시는 실제 작성했던 내용으로 적었습니다.

REST는 Representational State Transfer(대표적인 상태 전달)의 월드 와이드 웹(www)과 같은 분산 하이퍼미디어 시스템을 위한 소프트웨어 개발 아키텍처의 한 형식입니다. 구체적으로는 웹상에서 사용되는 여러 리소스를 HTTP URI로 표현하고, 그 리소스에 대한 행위를 HTTP Method 로 정의하는 방식을 의미합니다. REST는 아래와 같은 구성요소를 지니고 있습니다.

구성요소

1) Resource(자원) = URI(Uniform Resource Identifier)

URI는 해당 사이트의 특정 자원의 위치를 나타내주는 유일한 주소를 의미하며, https://localhost:5000/news/10 와 같이 모든 것을 Resource(명사)로 표현하고, 세부 리소스에는 id를 붙입니다. 클라이언트는 URI를 이용해서 자원을 지정하고, 해당 자원의 상태(정보)에 대한 조작을 서버에 요청합니다.

2) Method(행위)

자원에 대한 행위를 나타내며, HTTP 프로토콜의 Method를 사용합니다.

GET : 정보의 선택
POST : 정보의 생성
PUT : 정보의 업데이트
DELETE : 정보의 삭제

3) Representation(표현)

JSON 등을 통해 서버와 클라이언트가 주고받는 표현(응답)을 의미합니다.

REST API 설계 규칙

슬래시(/)는 계층 관계를 나타내는데 사용합니다.
- ex) https://localhost:5000/products/categories
URI 마지막 문자로 슬래시(/)를 사용하지 않습니다. URI는 리소스의 유일한 식별자로 사용되어야하기 때문에, 슬래시를 붙인 것과 안 붙인 것의 차이가 명확하므로 괜한 혼동을 일으키지 않기 위해 슬래시를 마지막에 사용하지 않습니다.
- ex) https://localhost:5000/products/categories/
하이픈( - )은 URI 가독성을 높이는데 사용합니다.
밑줄( _ )은 가독성을 위해 사용하지 않습니다.
URI 경로에는 소문자를 사용합니다.
파일 확장자는 포함하지 않습니다. 필요한 경우 Accept header에 명시합니다.

RESTful API는 위와 같은 REST 원리를 따르는 시스템을 의미합니다. REST를 따르면 여러 장점들이 있는데 그중 가장 명확한 점은 self-descriptiveness 인데, 이 자체만으로도 API 목적이 쉽게 이해가 되기 때문입니다. 구조를 이루고 있는 Resource와 Method만 봐도 어떤 행위를 하는지 직관적으로 이해할 수 있습니다.