[TIL] RESTful API

Jene Hojin Choi·2021년 2월 21일

1. RESTful API?

RESTful API를 이해하기 위해서는 우선 REST를 알아야한다.
REST란 REpresentational State Transfer (REST)의 준말이다. 이는 상의 컴퓨터 시스템들이 서로 쉽게 통신하기 위한 규칙을 제공해주는 아키텍처 디자인이다. REST의 규칙들을 지키는 시스템을 RESTful system이라고 한다.

Components

URI (Uniform Resource Identifier)

URI는 해당 사이트의 특정 자원의 위치를 나타내는 주소이며, 다음과 같은 형식을 가진다:

<protocol>://<service-name>/<ResourceType>/<ResourceID>

예를 들어, 다음과 같은 URI가 있을 수 있다.

http://api.example.com/device-management/managed-devices
http://api.example.com/user-management/users/{id}

HTTP Method (or Verbs)

HTTP request에 담긴 action을 말한다. (POST, GET, PUT, PATCH, DELETE)

Payload
HTTP request에서 서버로 보내는 데이터, 즉 body 를 말한다.

즉, REST는 HTTP URI로 정의된 리소스를 어떤 방식 (HTTP Method + payload) 으로 처리한다 라는 것을 명확하게 표현한 것이다.
그래서 그 자체만으로도 API의 목적을 쉽게 이해할 수 있다.

이를 자체 표현 가능 (Self-descriptiveness)이라고 한다. REST API 메시지만 보고도 이를 쉽게 이해 할 수 있는 자체 표현 구조로 되어 있어야한다.

2. RESTful API의 특징

클라이언트와 서버의 분리 (client - server architecture)

자원이 있는 쪽이 서버(백엔드)가 되며, 요청을 하는 쪽이 서버에 대한 클라이언트(프론트엔드)가 된다.
이렇게 관심사를 분리함으로서 RESTful API에서는 클라이언트(프론트)와 서버가 독립적으로 기능할 수 있다. 클라이언트/서버간 개발 내용이 명확해지고 서로간 의존성이 줄어든다.

무상태 (Statelessness)

무상태성이란 서버에서 요청을 받았을때의 클라이언트의 상태를 저장하지 않고도 현재의 요청을 처리할 수 있다는 것이다.
이는 서비스의 자유도가 높아지고 구현이 단순해진다는 장점이 있다.
하지만 이러다보니 클라이언트의 요청은 서버 입장에서 필요한 모든 정보를 담고 있어야한다.

캐시 처리 기능 (Cacheable)

해당 요청이 캐시를 처리하여 캐시 사용이 가능하게 된다면 클라이언트는 응답 데이터를 재사용할 수 있어야한다.

Uniform Interface

URI로 지정된 리소스에 균일하고 통일된 인터페이스를 제공해야한다.

자체 표현 구조 (Self-descriptiveness)

REST API만 보고도 이의 내용과 메세지를 쉽게 이해할 수 있다.

계층 구조 (Layered System)

REST API는 다중 계층으로 구성된다.
(보안, 로드 밸런싱, 암호화 계층을 추가해) 구조상의 유연성을 둘 수 있다.
proxy, 게이트웨이 같은 네트워크 기반의 중간 매체를 사용할 수 있게 한다.

3. RESTful API 설계

URI는 정보의 자원 중심이어야한다. (명사를 사용!)

    GET /members/delete/1    (x)

URI의 자원에 대한 행위는 HTTP Method가 포함되어서는 안된다.
마찬가지로 동사가 들어가서도 안된다.

다음과 같이 회원 정보를 가져오는 URI가 있다고 가정해보자:

    GET /members/show/1     (x)
    GET /members/1          (o)

URI에서 /는 계층관계를 나타낼때 사용한다

    http://restapi.example.com/animals/mammals/cats
    http://restapi.example.com/products/{product_id}

URI에서 마지막 문자로 /를 쓰지 않는다.

    http://restapi.example.com/animals/mammals/cats/   (x)

불가피하게 URI가 길어지는 경우 가독성을 높이기 위해 -를 사용한다.
하지만 _는 사용하지 않는다!!

 http://api.example.com/jene-hojin-choi/posts/this-is-my-first-post

대문자보다 소문자를 사용한다! (Convention이다)

    http://api.example.com/my-folder/my-doc    (o)
    http://api.example.com/My-Folder/my-doc    (x)

파일 확장자는 URI에 포함시키지 않아야한다.

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

4. path parameter vs query parameter

Reference: When do I use path params vs. query params in a RESTful API?

Best practice for RESTful API design is that path params are used to identify a specific resource or resources, while query parameters are used to sort/filter those resources.