REST API 디자인 15가지 팁

사이드 프로젝트를 진행하면서 올바른 REST API 디자인을 숙지해야겠다고 느껴 아래 포스트를 번역하게 됐습니다 (약간에 의역이 있을 수 있습니다)

오타나 오역이 있을 경우 댓글로 알려주시면 빠르게 수정하도록 하겠습니다.

 

15 fundamental tips on REST API design

 

REST API 는 가장 일반적인 웹 서비스 디자인으로 알려져 있지만 동시에 설계하기 어려운 특징도 있다.

브라우저, 데스크톱 앱, 모바일 애플리케이션 및 기본적으로 인터넷이 연결된 모든 장치의 클라이언트에서 REST API로 서버와 통신할 수 있다. 때문에 에러가 발생하지 않도록 REST API 를 제대로 설계하는 것이 매우 중요하다.

 

 기본적인 보안, 올바른 HTTP 메서드 사용, 인증 구현, 다양한 요청 및 응답 처리까지 모든 것을 고려하면  API 를 처음부터 만드는 것은 쉬운 일이 아니다. 이번 포스팅에서 좋은 API 를 만들 수 있는 15가지 항목을 소개하겠다., 이 방법들은 언어에 구애받지 않으며 모든 프레임워크와 기술에 적용될 수 있음을 밝힌다.

 

1. endpoint 에 명사를 사용할 것.

URL 경로(엔드포인트)를 설정할 땐 클라이언트가 조회하고자 하는 엔티티(명사)를 사용해야 하며, 항상 복수형으로 지정해야한다. HTTP 요청 메서드 자체가 동사를 나타내기에 URL에 동사형은 사용하지 않는다.

가장 일반적으로 사용되는 HTTP 메서드는 GET, POST, PATCH, PUT, DELETE로 REST API 의 행위는 반드시 HTTP 메서드에서 드러나야한다.

• GET :  리소스를 조회한다.
• POST : 새로운 데이터를 서버에 보낸다.
• PUT/PATCH : 기존 데이터를 업데이트 한다.
• DELETE : 데이터를 제거한다.

이러한 원칙을 염두해서, 책 목록을 조회할 땐 GET/books 같은 경로를 만들어야 한다. 마찬가지로 POST /books는 새 책을 추가하기 위한 엔드포인트며, PUT /books/:id는 지정된 id로 전체 책 데이터를 업데이트, PATCH /books/:id는 책의 부분적인 변경 사항을 업데이트한다. 마지막으로, DELETE /books/:id는 지정된 id의 리소스를 삭제한다.

 

위의 원칙을 염두하여 books 엔티티를 조회해보자.

GOOD : GET /books 

BAD : GET /get-books 

 

마찬가지로, 다른 HTTP 메서드도 아래처럼 정의할 수 있다.

POST : POST /books

PUT : PUT /books/:id

PATCH : PATCH /books/:id

DELETE : DELETE /books/:id

 

실제로 저는 사이드 프로젝트에서 post 메서드를 사용하는 대신 GET 메서드를 사용하면서 end-point 를 /save-store 라고 짓는 어처구니 없는 실수를 하기도 했습니다..

 

2. 데이터 전송 포맷: JSON (JavaScript Object Notification)

 몇 년 전까지만 해도 API 요청/응답 작업에는 대부분 XML이 사용됐다. 요즘은 JSON 이 대부분의 프로그램에서 API 데이터를 전송하는 표준 형식이 됐다.

엔드포인트의 응답으로 JSON 데이터 형식을 반환하고, 마찬가지로 HTTP 의 페이로드를 통해 정보를 요청할 때도 JSON 형식을 사용한다.

 

클라이언트 측에서 파일을 보낼 경우엔 Form data 를 사용하는 것이 좋지만, 텍스트와 숫자를 보내는데엔 Form Data 가 굳이 필요하지 않다. 대부분의 프레임워크가 클라이언트 측에서 JSON 을 직접 전송할 수 있기 때문에 굳이 Form Data 형식을 사용하지 않아도 된다.

클라이언트 측에서 데이터를 전송할 땐, JSON 데이터를 올바르게 해석할 수 있도록 응답 헤더의 Content-Type을 application/json으로 설정해야 한다. 포스트맨에서 테스트용도로 api 통신을 할 때 reqeust header 에서 이를 확인할 수 있다.

 

3. 적절한 HTTP 상태 코드

요청의 성공/실패를 나타내기 위해 HTTP 상태 코드를 항상 사용해야한다. (비즈니스 정책에 따라 디테일한 상태 코드가 의미하는 것은 달라질 수 있음을 인지하자). 상태코드의 의미는 아래처럼 사용할 수 있다

 

200 : 통신 성공

201 : 생성 성공

400 : 클라이언트 측의 잘못된 경로 요청

401 : 인증되지 않은 요청(사용자)

403: 인가되지 않은 요청(사용자)

404 : NOT FOUND

429: 너무 많은 요청

5xx : 서버 에러를 의미

 

경우에 따라 더 다양한 상태코드가 있지만, 상태 코드 범위에 제한을 두면  클라이언트가 보다 예측 가능한 API를 사용할 수 있다.

 

4. 표준화된 메시지를 반환하라

유사한 엔드 포인트에 대해 항상 표준화된 응답을 사용해야 한다. 클라이언트는 동일한 구조의 응답 형식을 기대하며 그에 따라 행동할 수 있다. 이는 정상 응답 뿐 만 아니라, 오류 메시지에도 적용된다. 컬렉션 구조를 조회하는 경우엔 response 본문에 아래처럼 특정한 구조를 유지하도록 응답 포맷을 표준화 한다.

아래의 두 방법 중 어느것을 사용하든, 하나의 표준화된 형식을 유지 해야한다.

// array of data
[
  {
     bookId: 1,
     name: "The Republic"
  },
  {
     bookId: 2,
     name: "Animal Farm"
  }
]


// Or like this
{
   "data":
	// array of data
      [ 
         {
           "bookId": 1,
           "name": "The Republic"
         },
         {
           "bookId": 2,
           "name": "Animal Farm"
         }
       ],
   "totalDocs": 200,
   "nextPageId": 3
}

 

 

// POST /books 요청이 성공적으로 반환됐을 때
 {
     "bookId": 3,
     "name": "Brave New World"
 }

큰 문제는 아니지만 "Book Successfully created" 같은 메시지를 반환하는 것은, HTTP 상태 코드에 이미 함축된 의미를 중복해서 표현하는 것과 같다.

 

 

{
  "code": "book/not_found",
  "message": "A book with the ID 6 could not be found"
}

반복해서 말하자면, 응답 내용에 상태 코드를 반드시 넣어야 할 필요는 없지만 book/not_found와 같은  자체 오류 코드를 정의하는 것은 클라이언트 입장에서는 매우 유용하다. 특히 개발 환경에서는 에러 스택을 응답에 포함시켜 버그를 디버깅 하는 것이 적절할 수 있다. 물론 프로덕션 환경에서는 에러 스택을 노출 시킴으로 보안 문제를 초래할 수 있으므로 이러한 정보를 배제해야 한다.

 

5. 응답 값으로 컬렉션을 받으면 페이징과 필터링, 정렬 처리를 해야한다. 

 

응답 값으로 리스트를 받는 endpoint 를 설계할 땐 페이징 처리를 해줘야 한다. 시스템이 발전함에 따라 컬렉션 값도 규모가 점차 커지기 때문에, 항상 정해진 양의 데이터를 반환하도록 제어해야 한다. 물론 클라이언트 측에서 전달받을 데이터의 규모를 정하는 것이 공정하겠지만, API 측에서 미리 그 규모와 최대 값을 규정해 두는 것이 좋다. 이런 페이징 처리를 하는 이유는, 방대한 양의 데이터 배열을 반환하는 데 많은 시간과 대역폭이 소모되기 때문이다 .

 

skip/limit 과 keyset 이 대표적인 페이징 처리 기법이다. skip/limit 옵션은 데이터를 가져오는 익숙한 방법에 속하지만, 테이블 후반부에 위치한 데이터를 가져올 땐 시간이 많이 소모되기 때문에 일반적으로 성능이 떨어진다. 반면 keyset 페이징 기법은 식별자/ID를 참조값으로 받아 리스트나 테이블을 스캔할 필요없이 조건에 따라 데이터를 페이징할 수 있다.

 

동일한 측면에서, API 는 데이터를 조회할 때 필터와 정렬 기능도 제공해야 한다. 성능 향상을 위해 DB 인덱스는 필터와 정렬을 통해 적용되는 Access 패턴을 사용하기도 한다. API를 설계할 때 필터와 정렬은 쿼리 파라미터에 정의된다. 예를 들어 "romance" 범주에 속하는 초기 10권의 책을 조회하려면 엔드포인트는 아래처럼 설계해야한다.

GET /books?limit=10&category=romance

 

6. PUT 대신 PATCH 을 사용하라 .

엔티티의 모든 상태값을 한번에 수정하는 일은 흔히 일어나지 않는다. 또한 클라이언트가 수정하지 못하게 유지하고 싶은 복잡하거나 민감한 데이터도 존재하기 마련이다. PUT 메서드는 리소스의 모든 요소를 수정해버리기 때문에, 데이터의 부분적인 수정이 필요할 땐 PATCH 메서드를 사용한다. 두 메서드 모두 업데이트 해야하는 정보를 HTTP Body 에 담아 보내야한다.

하지만 그렇다고 하여 부분 업데이트를 할 때 PUT 메서드를 아예 사용하지 말라고 강제할 수도 없는 노릇이다. 정해진 "네트워크 전송 제한" 규범이 있는 것도 아니며, 그저 PATCH 메서드를 사용하는 것이 좋은 방법이라 권장될 뿐이다. 

 

7. 확장된 응답 옵션을 제공하라. 

시스템이 확장됨에 따라, 응답 값의 프로퍼티가 늘어날 수 도 있지만, 클라이언트에게 모든 프로퍼티가 필요하지 않을 수 있다. 이런 경우에는 동일한 엔드포인트에 

1) 필요한 프로퍼티만 제공하는 축소된 응답 포맷을 내려주거나 

2) 축소하지 않은 기존 응답 포맷을 내리는

2가지 선택권을 줄 수 있다.

클라이언트가 응답 값의 일부만 필요로 할 땐, 간략화된 응답 포맷을 내리는 것이 대역폭 낭비를 줄일 수 있다.

아래 예시처럼 exteneded 라는 추가 쿼리를 매개 변수로 제공하면 확장된 응답 제공을 쉽게 활성/비활성화 할 수 있다.

GET /books/:id
{
   "bookId": 1,
   "name": "The Republic"
}
GET /books/:id?extended=true
{
   "bookId": 1,
   "name": "The Republic"
   "tags": ["philosophy", "history", "Greece"],
   "author": {
      "id": 1,
      "name": "Plato"
   }
}

 

8. 엔드포인트의 책임을 생각하라

API 가 하나의 작업을 잘 수행하는 동시에 변하지 않는다면,  해당 API는 잘 설계된 것이라 할 수 있다. 잘 설계된 API 는 클라이언트가 API 를 쉽게 이해하고, 전반적인 통합을 용이하게 하여 예측 가능하게 만든다. 한번에 많은 작업을 해결하는 복잡한 엔드포인트를 구축하는 것 보다, 사용 가능한 엔드포인트 목록을 전체적으로 확장하는 것이 바람직하다. 

 

9. 정확한 API 문서를 제공하라. 

API를 잘 정리한 문서가 있어야 클라이언트는 사용가능한 엔드포인트를 어떻게 사용할 것이며, 어떤 결과를 받을 수 있을지 예측할 수 있다.

정리된 문서를 제공하기 위해선 다음과 같은 측면을 고려해야 한다.

• 엔드포인트의 목적을 설명
• 엔드포인트를 실행할 때 필요한 권환
• 호출 및 응답 예제
• 에상 오류 메시지

시스템이 업데이트 되고 변경될 때 마다 API 문서 역시 업데이트 해주는 것이 중요하다. 이를 지킬 수 있는 가장 좋은 방법은 API 문서화를 개발의 기본으로 삼는 것이다. Swagger와 Postman이 잘 알려진 API 문서화 도구로 대부분의 API 개발 프레임워크에서 사용할 수 있다.

 

10. 보안을 위한 SSL 사용 및 CORS 설정

 보안 역시 API가 갖춰야 할 기본적인 속성 중 하나다. 

서버에 유효한 인증서를 설치하여 SSL 을 설정하면, 클라이언트와의 안전한 통신을 보장하고 몇 가지 잠재적인 공격을 방지할 수 있다.

CORS(Cross Origin Resource Sharing) 는 브라우저 보안 기능으로, 브라우저의 스크립트에서 시작되는 크로스 오리진(Cross origin) HTTP 요청을 제한한다. 복잡한 크로스 오리진 HTTP 요청을 수신하는 REST API는, 그에 대응할 수 있는 CORS 지원을 활성화 해야 한다.

CORS 프로토콜은 브라우저가 서버에 사전 요청preflight 을 보내도록 하며, 실제 요청을 보내기 전까지 서버의 승인을 기다린다. 사전 요청(preflight request)은 OPTIONS 메서드를 사용하는 HTTP 요청을 의미한다. 즉 REST API가 CORS에 대응하려면 사전 요청(preflight)의 OPTIONS 메서드를 수행할 수 있도록,  FETCH 표준에서 요구하는 아래의 사항을 응답 헤더에 넣어야한다.

• Access-Control-Allow-Methods
• Access-Control-Allow-Headers
• Access-Control-Allow-Origin

위 3가지 key 값에 할당될 값은 API 가 얼마나 개방적이고 유용한지에 따라 달라진다. 잘 알려진 Origin 을 할당하거나 와일드 카드를 사용하는 방법 등으로 CORS 를 설정할 수 잇다. 

 

11. API 버전

개발 프로세스의 일환으로, API 엔드포인트가 변경되거나 재구축 되는 경우가 있더라도, 클라이언트 통신을 위해 갑자기 엔드포인트를 변경하는 일은 피해야한다. API는 새로운 엔드포인트가 이전 버전의 표준에 영향을 주지 않는 하위 호환 리소스로 생각하는 것이 바람직하다. 클라이언트는 자신이 요청할 API 주소를 선택할 수 있어야하고, 아래처럼 API 버전을 관리하는 여러 방법이 있다 .

1. 새로운 헤더 추가 "x-version=v2"
2. 쿼리 파라미터 사용 "?apiVersion=2"
3. URL의 일부로 버전을 표기 "/v2/books/:id"

 

12. 성능 향상을 위한 캐시 데이터 활용

API 의 성능 향상을 높이려면 빈번히 사용되며, 쉽게 변하지 않는 데이터를 캐싱해두는 것이 좋다. 접근 빈도가 높은 데이터를 잘 활용하려면,  인메모리나 캐시 데이터베이스를 사용하여 메인 데이터베이스에 접근하는 비용을 줄이는 방법을 고려할 수 있다. 캐싱된 데이터가 outdated 될 수 있으므로 최신 상태의 데이터로 교체 하는 방법 역시 고민해야 한다.

클라이언트 입장에서는, 설정이나 카탈로그 정보 처럼 시간이 지나도 잘 변하지 않는 정보를 캐시 데이터로 활용하면 매우 유용하다. 캐시 데이터를 사용할 땐 HTTP 헤더에 Cache-Control 프로퍼티를 꼭 포함해야 한다. 

 

 

13. 표준 UTC 사용

데이터 수준에서 클라이언트 측의 날짜 표준 방식을 일관성 있게 보여주도록 유지하는 일은 중요하다. ISO 8601 는 날짜/시간 데이터의 국제 표준 형식으로, 날짜는 'Z' 또는 UTC 형식이어야 하며, 클라이언트는 어떤 조건에서든 해당 날짜를 표시해야 할 경우 시간대를 결정할 수 있다.

다음은 날짜 형식의 예시를 보여준다.

{
    "createdAt": "2022-03-08T19:15:08Z"
}

 

14. 헬스 체크 엔드포인트

API 에 문제가 생겨 다운될 때, API 를 재가동하고 실행하는데 시간이 걸릴 수 있다. 이러한 상황에서 클라이언트는 문제 상황을 파악하고 그에 따라 서비스를 이용할 수 없다는 사실을 알아야 한다.  이를 위해 API 가 정상적으로 동작하는지 확인할 수 있는 엔드포인트 (ex GET /health) 를 제공해야한다. 이런 엔드포인트는 로드밸런서 같은 다른 어플리케이션에 의해 호출될 수 있으며, 더 나아가 API의 헬스 체크나 유지 보수 기간을 알려줄 수도 있다.

 

15. API Key 인증을 허용하라

API key 를 통한 인증은 써드 파티 어플리케이션이 우리의 API에 손쉽게 사용되도록 만들 수 있다. API key 값은 X-Api-Key 나 Api-Key 같은 커스텀 HTTP 헤더를 통해 전달돼야 한다. Key의 만료 기한 역시 지정돼야 하며, 보안상 문제가 있을 땐 무효화 되도록 해지할 수 있어야 한다.