REST API의 개념과 디자인 가이드

1. REST API

1.1 배경

REST는 Representational State Transfer라는 용어의 약자로서 2000년도에 로이 필딩 (Roy Fielding)의 박사학위 논문에서 최초로 소개되었다. 로이 필딩은 HTTP의 주요 저자 중 한 사람으로 그 당시 웹(HTTP) 설계의 우수성에 비해 제대로 사용되어지지 못하는 모습에 안타까워하며 웹의 장점을 최대한 활용할 수 있는 아키텍처로써 REST를 발표했다고 한다.

1.2 개념

HTTP를 이용해 통신할 때의 모범 형식

REST는 정보들이 주고받아지는 데 있어서 개발자들 사이에 널리 쓰이는 일종의 형식이다. 어떤 기술이나 제품이 아니라 형식이기 때문에 어떤 프로그래밍 언어를 쓰든 무슨 프레임워크를 쓰든 상관없이 형식(REST API 디자인 가이드)에 맞춰서 기능을 만들어 내면 되는 것이다.

∴ REST는 HTTP 요청을 보낼 때 어떤 URI에 어떤 메소드를 사용할지, 각 요청이 어떤 동작이나 정보를 위한 것인지를 그 요청의 모습 자체로 추론이 가능하도록 하기 위해 개발자들 사이에 널리 지켜지는 약속이다.

🔔 REST API = RESTful한 API = HTTP 통신 시 REST 원리를 따르는 API

1.3 사용 이유

기능 자체만을 중요시한다면 그냥 요청에 맞춰 동작하게만 만들면 되지만, 협업을 하거나 유지보수할 때 힘들다.

RESTful 하게 만든 API는 누가, 언제 이 요청을 보더라도 대략 무엇을 하는 요청인지 파악이 가능하다.

1.4 REST의 구성

• 자원(Resource) - URI
  
• 행위(Verb) - HTTP Method
• 표현(Representations)

1.5 REST의 특징

• Uniform Interface(유니폼 인터페이스)
  : URI로 지정한 리소스에 대한 조작을 통일되고 한정적인 인터페이스로 수행하는 아키텍처 스타일이다.

• Stateless(무상태성)
  : 작업을 위한 상태 정보를 따로 저장 및 관리하지 않고 단순히 들어오는 요청만 처리한다. 무상태성 덕분에 서비스의 자유도가 높아지고 서버에 불필요한 정보를 관리하지 않음으로써 구현이 단순해짐

• Cacheable(캐시 가능)
  : HTTP라는 기존 웹표준을 그대로 사용하기 때문에 Last-Modified 태그나 E-Tag를 사용하면 HTTP가 가진 캐싱 기능이 구현 가능하다.

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

• Client-Server 구조
  : REST 서버는 API제공, 클라이언트는 사용자 인증이나 컨텍스트(세션, 로그인 정보)등을 직접 관리하는 구조로 각각의 역할이 확실히 구분되기 때문에 클라이언트와 서버에서 개발해야 할 내용이 명확해지고 서로간 의존성이 줄어들게 된다.

• 계층형 구조
  : REST 서버는 다중 계층으로 구성될 수 있으며 보안, 로드 밸런싱, 암호화 계층을 추가해 구조상의 유연성을 둘 수 있고 프록시, 게이트웨이 같은 네트워크 기반의 중간매체를 사용할 수 있게 한다.

2. REST API 설계 디자인 규칙

REST API 설계 시 가장 중요한 항목은 다음의 2가지로 요약할 수 있습니다.

첫 번째, URI는 정보의 자원을 표현해야 한다.
두 번째, 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현한다

개인적으로 중요하다고 생각하는 부분만 요약 정리한 것으로 자세한 설계 가이드가 궁금하다면 다음 블로그를 참고해도 좋을 것 같다.

2.1 URI Rules

• 정보의 자원을 표현해야 한다. (동사보다 명사 사용)

• 마지막에 / 포함하지 않는다.

• _(underbar) 대신 -(dash)를 사용한다. (정확한 의미, 표현을 위해 단어의 결합이 불가피한 경우만 사용)

• 대문자보다 소문자를 사용하자.

• 행위(method)를 URI에 포함하지 않는다.

• 컨트롤 자원을 의미하는 URI은 예외적으로 동사를 허용한다.
  (ex. http://api.test.com/posts/duplicate)

• 파일 확장자는 URI에 포함시키지 않고 Accept header를 이용하자.

• 컬렉션과 도큐먼트 사용 시 단수 복수를 지키자. → 컬렉션 복수로 표현

2.2 HTTP Headers

• Content-Location
  : POST 요청은 GET이나 PUT과 달리 대부분 idempotent(멱등: 반환되는 응답 리소스의 결과가 항상 동일)하지 않다. 따라서 요청의 응답 헤더에 새로 생성된 리소스를 식별할 수 있는 Content-Location 속성을 이용하자.
  

POST /users
{
  "name": "noma"
}
----------------------------
HTTP/1.1 200 OK
Content-Location: /users/1

• Content-Type
  : 되도록이면 application/json만을 제공하자. applicaion/xml 등을 사용하여 응답 포맷을 이원화하지 말자.

2.3 HTTP Methods

다음과 같이 상황에 따라 알맞은 method를 사용하자.

• GET: 리소스 조회. 해당 도큐먼트에 대한 자세한 정보를 가져온다.
• POST: 리소스 생성.
• PUT : 리소스 전체 수정. 바뀌지 않는 속성도 모두 보내야 한다. 만약 요청에 일부 속성만 보낸 경우 나머지는 default값으로 수정해주는 게 원칙이다.
• PATCH : 리소스 일부 수정. 변경하려는 속성만 보내면 된다.
• DELETE: 리소스 삭제.

2.4 HTTP Status Code

• HTTP status만으로 상태 에러를 나타낸다. (응답 객체에 중복으로 상태 코드를 표시할 필요X)
• 성공은 2XX, 실패는 4XX (5XX는 절대 사용자에게 나타내지 말자.)

다음과 같이 상황에 따라 알맞은 status를 사용하자.

2XX

• 200: [OK] - 요청을 정상적으로 수행함

• 201: [Created] - 요청에 성공하고 새로운 리소스를 만든 경우(POST, PUT에 사용)

• 202: [Accepted] - 요청을 받았으나 서버가 아직 처리하지 않은 경우(응답이 일정 시간 후 완료되는 작업의 경우)
  → 작업이 완료되면 클라이언트에 알릴 수 있는 server push를 하거나, 클라이언트가 해당 작업의 진행 상황을 조회할 수 있는 URL을 같이 응답해줘야함

• 204: [No Content] - 응답 body가 필요 없는 자원 삭제 요청(DELETE) 같은 경우에 응답

4XX

• 400: [Bad Request] - 클라이언트 요청이 미리 정의된 파라미터 요구사항을 위반한 경우
  → 파라미터의 위치(path, query, body), 사용자 입력 값, 에러 이유 등을 반드시 알리자.

• 401: [Unauthorized] - 클라이언트가 인증되지 않은 상태에서 보호된 리소스를 요청했을 때 사용하는 응답 코드 (서버가 클라이언트가 누군지 모름)

• 403: [Forbidden] - 요청자가 접근 권한이 없는 자원에 접근을 시도한 경우 응답 (서버가 클라이언트가 누군지 앎)

• 404: [Not found] - 요청한 리소스를 찾을 수 없을 경우

• 405: [Method Not Allowed] - 요청한 URI가 해당 method를 제공하지 않는 경우

• 409: [Conflict] - 해당 요청의 처리가 비지니스 로직상 불가능할 경우
  (ex. 비지니스 로직상 사용자의 모든 자원이 비어있을 때만 사용자를 삭제 할 수 있는 규칙이 있을 때 DELETE /users/noma 할 경우 409로 응답)

• 429:[Too Many Requests] - DoS, Brute-force attck과 같은 비정상적인 접근을 막기위해 요청의 수를 제한

5XX

• 500: 서버에 문제가 있을 경우 사용 → API Server가 모든 발생 가능한 에러를 핸들링하여 이 에러가 나지 않도록 해야 한다.

마치며

REST API는 정해진 명확한 표준이 없기 때문에 REST API를 사용함에 있어 '무엇이 옳고 그른지'가 아닌 개발하는 서비스의 특징과 개발 집단의 환경과 성향 등을 충분히 고려해 설계하도록 하자.

Reference

https://www.youtube.com/watch?v=iOueE9AXDQQ
https://www.youtube.com/watch?v=PmY3dWcCxXI
https://meetup.toast.com/posts/92
https://sanghaklee.tistory.com/57