Restful API 설계하는 방법

원본 글 출처
https://blog.mwaysolutions.com/2014/06/05/10-best-practices-for-better-restful-api/

 

동사가 아닌 명사를 통한 API 설계를 할것.

• REST 디자인을 위해서는 CRUD 를 Method 를 이용하며 표현하기 때문에 그 외의 것은 전부 entity를 명시하는 명사로 표기한다.

상태를 변경할 때 GET 메서드와 쿼리 파라미터 사용금지

• PUT, POST 그리고 DELETE 메서드를 사용한다.

복수 명사 사용

/user (X) -> /users (O)
/product (X) -> /products (O)

 

관계 형태는 하위 리소스를 사용

711, 4와 같은 숫자는 해당 리소스의 고유 값

GET /cars/711/drivers/ (711 자동차의 전체 운전자 정보 리스트를 반환)
GET /cars/711/drivers/4 (711 자동차의 4 운전자 정보 반환)

 

직렬화 포맷에는 HTTP 헤더 사용

• 클라이언트와 서버가 통신을 하기 위해 필요한 데이터 포맷을 HTTP 헤더에 명시하면 된다.

HATEOAS 사용

• HATEOAS 란 Hypermedia As The Engine Of Application State 의 약자로, 하이퍼텍스트 링크를 데이터 내에 명시할 경우 API를 통해 갈 수 있는 navigator 형태로 표기해준다.
• REST API 는 실제 리소스를 담는 것이 아닌 경로를 담아서 HyperMedia 컨텐츠를 기록한다.
• 네트워크 비용도 절감되고, 성능면에서도 많은 이점을 갖는다.
• 해당 주소로 다시 접근하여 실제 리소스를 받아와야 하는 점이 있지만, 오히려 리소스를 CDN 등을 이용한 static 저장소에 두고 가져온다면 네트워크 비용 측면에서도 훨씬 저렴하고 뛰어난 성능으로 핸들링할 수 있다.
  • CDN:
    • 전 세계에 전략적으로 분산되어있는 서버 네트워크(지리적으로)
    • CDN은 사용자가 리소스를 다운로드 할 수있는 대체 서버 노드를 제공하여 작동
    • 지리, 물리적으로 떨어져 있는 사용자에게 컨텐츠를 더 빠르게 제공할 수 있는 기술

결과반환 리스트에 필터링, 정렬, 결과요소 선택, 페이징 기능을 제공하기

• 필터링
  • 모든 결과 속성에 유니크한 쿼리 파라미터를 사용하거나 필터링을 위한 쿼리 언어를 사용한다.

    GET /cars?color=red (빨간색 자동차 목록을 반환)
    GET /cars?seats<=2 (좌석이 최대 2개인 자동차 목록을 반환)

• 정렬
  • 오름차순, 내림차순 정렬을 여러 결과 속성에 사용할 수 있도록 제공한다.

    GET /cars?sort=-manufactorer,+model

• 결과요소 선택
  • select 조건문과 같이 필드만 추출해서 보여줄 수 있도록 하는것으로, 네트워크 트래픽 관리에 효과적이다.

    GET /cars?fields=manufacturer,model,id,color

• 페이징
  • limit(한 페이지 나타낼 결과 갯수)과 offset(시작점)을 이용한다.

    GET /cars?offset=10&limit=5

  • 결과의 총 갯수를 사용자에게 알려주고 싶으면 X-Total-Count 라는 커스텀 HTTP 헤더를 이용하면 된다.
    • HTTP Link 헤더에 이전, 다음 페이지에 대한 링크가 잘 제공되어야 한다. 사용자가 직접 URL을 이용하는 것 보다 헤더 값에 명시된 URL을 이용하여 페이지를 이동하게 하는 것이 중요하다.

      Link: https://blog.mwaysolutions.com/sample/api/v1/cars?offset=15&limit=5; rel="next",
      https://blog.mwaysolutions.com/sample/api/v1/cars?offset=50&limit=3; rel="last",
      https://blog.mwaysolutions.com/sample/api/v1/cars?offset=0&limit=5; rel="first",
      https://blog.mwaysolutions.com/sample/api/v1/cars?offset=5&limit=5; rel="prev",

API 버전 관리

• API 버전을 만들고 버전이 없는 API는 릴리즈 하지 않도록 한다.
• 심플한 서수를 사용하고 2.5 같은 점 표기법은 피한다.

  /blog/api/v1

HTTP 상태 코드로 에러 핸들링

• 에러는 별도의 로직으로 처리한다기 보다 HTTP 상태 코드와 메시지를 통해 처리하는 것이 좋다.
• 에러 스택과 함께 HTTP 500을 반환하는 기본 에러 반환은 그닥 도움이 되지 않는다.
• HTTP 상태 코드 이용
  • HTTP 표준에서 결과 값을 표현하기 위해 70개가 넘은 상태 코드를 제공한다.

    1xx (정보): 요청을 받았으며 프로세스를 계속한다.
    2xx (성공): 요청을 성공적으로 받았으며 인식했고 수용하였다.
    3xx (리다이렉션): 요청 완료를 위해 추가 작업 조치가 필요하다.
    4xx (클라이언트 오류): 요청의 문법이 잘못되었거나 요청을 처리할 수 없다.
    5xx (서버 오류): 서버가 명백히 유효한 요청에 대해 충족을 실패했다.

• 에러 정보제공
  • 모든 예외는 에러 페이로드에 매핑되어야 한다.
  • JSON 페이로드에 대한 예시

     

      { 
          "errors": [ 
               { 
                  "userMessage": "Sorry, the requested resource does not exist", 
                  "internalMessage": "No car found in the database", 
                  "code": 34, 
                  "more info": "http://dev.mwaysolutions.com/blog/api/v1/errors/12345" 
              } 
          ] 
      }

HTTP 메서드 오버라이딩 허용

• 몇몇 프록시 서버의 경우 POST와 GET 만을 지원하는 경우가 있다.
• 일부 프록시 서버들은 GET과 POST 메서드만 허용합니다. 이러한 제한없이 RESTful API를 제공하려면 API 단에서 HTTP 메서드를 오버라이드할 필요가 있다.
• POST 메서드에 X-HTTP-Method-Override 커스텀 HTTP 헤더를 통해 오버라이드하여 method 방식을 지원하면 된다.

 

 

참고
https://jins-dev.tistory.com/entry/Rest-API-%EC%84%A4%EA%B3%84%EB%A5%BC-%EC%9C%84%ED%95%B4-%EA%B0%9C%EB%B0%9C%EC%9E%90%EA%B0%80-%EC%95%8C%EC%95%84%EC%95%BC%ED%95%A0-10%EA%B0%80%EC%A7%80-%EC%B2%B4%ED%81%AC-%EB%A6%AC%EC%8A%A4%ED%8A%B8
https://itstory.tk/entry/%EB%8D%94-%EB%82%98%EC%9D%80-RESTful-API%EB%A5%BC-%EC%84%A4%EA%B3%84%ED%95%98%EA%B8%B0-%EC%9C%84%ED%95%9C-%EC%B5%9C%EA%B3%A0%EC%9D%98-10%EA%B0%80%EC%A7%80-%EC%97%B0%EC%8A%B5%EB%B0%A9%EB%B2%95
https://ko.wikipedia.org/wiki/HTTP_%EC%83%81%ED%83%9C_%EC%BD%94%EB%93%9C
https://goddaehee.tistory.com/173