REST API 디자인 규칙 - 5장

5.1 메시지 바디 포맷

• REAT API는 요청 메시지가 지정한 리소스의 상태를 응답 메시지의 바디를 이용해서 전달 → 주로 텍스트 기반의 포맷(XML, JSON)을 이용한다.
• 규칙
  • JSON 리소스 표현을 지원해야 한다.
    • JSON은 데이터 교환용 포맷으로, 가볍고 간단한 상호 연동을 지원한다.
    • 특정 리소스 타입에 대한 표준 포맷이 없을 경우, REST API에서는 그 정보를 구조화하기 위해서 JSON 포맷을 사용해야 한다.
  • JSON 문법에 잘 맞아야 한다.
    • JSON 객체는 키-값 쌍으로 구성되며 순서와 무관한 집합이고, 키 값을 문자열로 정의하며, 이 문자열은 항상 큰따옴표 안에 넣는다.
    • XML과 다른 표현 형식은 선택적으로 지원할 수 있다.
      • 클라이언트에서는 사용하고자 하는 표현 방법을 나타내야 한다.
    • 추가 봉투는 없어야 한다.

5.2 하이퍼미디어 표현

• REST API 응답 메시지 바디에 포함된 링크는 리소스의 연관성과 액션을 나타낸다. 리소스의 상태 표현에서 다른 필드 값을 가지고, 링크는 리소스 간 관련성을 전달하며 클라이언트에 상황에 맞는 리소스 관련 액션 메뉴를 제공한다.
• 규칙
  • 링크는 일관성된 형태로 나타내야 한다.
  • 링크 관계를 표현할 때에는 일관된 형태를 사용해야 한다.
    • self..
  • 링크를 표현할 때는 일관된 형태를 사용해야 한다.
    • 리소스의 현재 상태에서 가능한 모든 링크를 포함하고 있는 ‘links 구조’로 표현되어야 한다.
  • 응답 메시지 바디 표현에 셀프 링크를 포함해야 한다.
  • 진입 API URI 수를 최소화하라
  • 리소스의 상태에 따라 가능한 액션을 표현하기 위해서 링크를 사용해야 한다.

5.3 미디어 타입 표현

• 규칙
  • 미디어 타입 format은 일관성 있는 폼을 사용해야 한다.
  • 미디어 타입 스키마를 표현할 때는 일관성 있는 형식을 사용해야 한다.
    • 필드 표현
      • Boolean, Choice, DateTime, Double, Integer, List, Schema, Text, Null
    • 제약 표현
      • 범위 제약 : 특정 최솟값에서 최댓값 사이로 제한
      • Menu 제약 : Choice 필드에서 선택할 수 있는 값을 미리 정의한 텍스트 리터럴 집합으로 제한
      • ElementType 제약 : List 필드에서 선택할 수 있는 값을 일정한 요소로 제한
      • Text 제약 : 필드 값을 특정한 문법으로 제한
    • 링크 공식 표현
      • e.g., self, parent, update, recap, scoreboaard..
    • 도큐먼트 스키마 표현
      • 도큐먼트는 모든 리소스 타입의 기본 양식
    • 컨테이너 스키마 표현
    • 컬렉션 스키마 표현
    • 스토어 스키마 표현

5.4 오류 표현

• HTTP 4xx, 5xx 오류 상태 코드는 응답 메시지 엔티티 바디 안에 클라이언트가 읽을 수 있는 정보를 추가해야 한다. 이 부분에서 제시하는 규칙은 오류와 응답에 적용되는 일관된 폼을 제공한다.
  • 규칙
    • 오류는 일관성 있게 표현한다.

      {
        "id" : "Text",
        "descriptions" : "Text"
      }
      

    • 오류 응답은 일관성 있게 표현한다.

      {
        "id" : "Update Failed",
        "descriptions" : "Failed to update /users/1234"
      }
      

  • 일반적인 오류 상황에서는 일관성 있는 오류 타입을 사용해야 한다.
    • API의 다양성으로 말미암아 일반적 오류 타입은 중요해진다. 오류 타입은 한 번 정의되면 서비스를 제공하는 오류 스키마 문서를 통해 모든 API에 공유되어야 한다.