9장 설계 절차(1)

2단계 설계 절차

  • 가장 단순한 형태
    1. 표현에 사용할 미디어 유형을 선택한다.
      1. 프로토콜 의미 체계(HTTP 프로토콜 하에서 API의 행동 양식)와 애플리케이션의 의미 체계(표현이 참조할 수 있는 실제 세계의 것들)에 제약 사항들을 결정
    2. 그 외 모든 것을 다루는 프로파일을 작성한다.
  • JSON을 선택 ⇒ 프로토콜 애플리케이션 의미 체계에 아무런 제한이 없음 ⇒ 2에 모든 시간을 소비

7단계 설계 절차

  1. API에서 클라이언트가 얻길 원하는 것이나 또는 API를 통해 넣길 원하는 모든 정버를 열거함
    1. 의미 체계 서술자
  2. API를 나타내는 상태 다이어그램을 그림
    1. 연결 관계
  3. 기존에 있는 프로파일의 문자열을 이 API의 마법 문자열과 조정함
  4. 이 API의 프로토콜 의미 체계와 애플리케이션 의미 체계와 호환되는 미디어 유형을 선택하거나 새롭게 정의
  5. 애플리케이션 의미 체계를 기술하는 프로파일을 작성
  6. 코드 작성
  7. 광고판 URL 게시

미로 게임을 예시로 둔다.

1단계: 의미 체계 서술자 나열하기

  • 미로 게임에서 사용하는 모든 데이터
    • 미로, 미로 셀, 스위치, 스위치 위치 등…

2단계: 상태 다이어그램 그리기

  • 미로 목록 > 미로 > 셀
  • 미로 목록과 미로의 연결관계 : maze
  • 미로와 셀의 연결관계 : start

의미 체계 서술자는 연결 관계가 될 수도 있다.

  • 출구 : 미로 셀과 또 다른 무언가와의 연결 관계 ⇒ 출구와 입구는 연결 관계로 표현되어야 함
  • 스위치 : 자신을 포함하는 미로 셀과는 별개로 그자 체가 독립적인 리소스
  • 동서남북 : 하나의 셀과 다른 셀 간 연결 관계

홈페이지 정하기

  • 상태 다이어그램은 출발점이 없는 하나의 화살표가 있어야 함
  • 이 화살표는 광고판 URL로 향하는 클라이언트의 최초의 GET 요청을 의미

3단계: 이름 조정하기

  • 사실 큰 상관은 없어 생략해도 된다.
  • 주의할점 1: 데이터베이스 스키마나 객체 모델이 있는 항목을 이용하여 의미 체계 서술자 이름을 자동으로 생성하지 않도록 한다.
    • 클라이언트가 서버 쪽 코드에 의존하게 되기 때문
    • 서버 코드가 변경되면 클라이언트 코드도 망가진다.
  • 주의할점 2: IANA에 등록된 연결 관계의 기능과 중복되는 연결 관계를 만들지 않도록 한다.
    • flip : 스위치 상태를 반대로 변경 ⇒ 멱등하지 않음
    • edit: 스위치 상태를 전달받은 대로 변경 ⇒ 멱등
    • edit을 쓸 떄의 장점 : 클라이언트가 이미 알고 있는 IANA에 등록된 관계인 edit을 재사용하게 된다.

4단계: 미디어 유형 선택하기

  • JSON은 하이퍼미디어 유형이 아니다.
    • JSON 표준은 연결이나 연결 관계 같은 개념을 정의하지 않으며 하이퍼미디어와 같은 기능은 없다.

5단계: 프로파일 작성하기

서버에서 표현을 보낼 때 Content-Type 헤더를 포함하여, 표현에서 사용한 애플리케이션의 의미 체계를 설명하는 프로파일을 연결한다.

6단계: 구현하기

대부분의 시간을 씀. 기존에 존재하며 다른 추가적인 작업이 필요 없는, 정확히 원하는 특정 도메인 표준이 있다면 필요 없음

7단계: 게시하기

  • 정보
  • 광고판 URL
  • 프로파일
  • 새로운 미디어 유형
  • 새로운 연결 관계
  • 잘 알려진 URI

몇 가지 설계 충고

리소스는 구현의 구체적인 내용이다.

리소스는 HTTP에 있어서 가장 주요한 부분이고 API 구현에 있어서 정말 중요하다. 하지만 REST에 있어서는 그렇게 중요하지 않을 수 있다. 상태 전이와 의미 체계 서술자에 집중하여 해결하고 나면 리소스를 갖게 된다.

컬렉션 함정에 빠지지 말라

데이터베이스 스키마를 기반으로 API를 설계하지 말고, 상태 다이어그램을 그려라.

  1. 사용자들이 데이터베이스 스키마를 전혀 고려하지 않기 떄문이다.
  2. 스키마 변경이 불가능해 진다. 변경하면 문제의 범위가 커진다.

표현 형식에서 시작하지 않는다

표현 형식은 단순히 데이터를 포함하기 위한 것이 아니다. 프로토콜과 애플리케이션의 의미 체계의 가정들을 이를 이용하는 모든 API에 안내한다.

URL 설계는 상관이 없다

기술적으로는 URL은 클라이언트가 표현을 갖기 위해 사용하는 단순히 리소스의 주소일 뿐이다. 물론 어느정도는 중요하지만, URL을 보고 리소스의 애플리케이션 수준의 의미 체계를 모두 알 수 있도록 지나치게 애쓰면 안된다.

표준 이름이 직접 지은 이름보다 낫다.

API 애플리케이션 의미 체계에 전반적으로 잘 맞는 어느 것이든 프로파일 하나를 선택하고, 거기서 정의하는 이름을 사용하자.

미디어 유형을 설계해야 한다면

반드시 완전하고 모호함이 없는 처리 설명서가 포함되어야 한다.

API를 변경해야 할 때

API의 의미 체계를 사람이 이해할 수 있는 문서에서 하이퍼미디어 문서로 변경하면 API가 변화를 맞이했을 때 더 견고해진다. 기존 클라이언트에 영향을 주지 않고 API로 새로운 리소스와 상태 전이를 추가할 수 있다.

URL 공간 분리

일반적으로 버전을 만드는 것은 https://api-v1.example.com , https://api-v2.example.com 처럼 별개로 만드는 것

미디어 유형의 버전 만들기

콘텐트 협상을 사용할 수 있다.

프로파일 버전 만들기

두 가지 프로파일을 유지하면 두 종류의 애플리케이션 의미 체계를 유지하도록 해준다.

수명이 있는 계획을 만든다

  1. 현재 버전의 지원 중단을 알림
  2. 지원이 중단된 API의 버그 수정이 없음을 알림
  3. 지원이 중단된 API의 제거 기한을 알림
  4. 제거

한곳에 모든 하이퍼미디어를 유지하지 말라

서버 측 구현, 기계가 이해할 수 있는 설명, 그리고 그 설명으로부터 생성한 클라이언트 사이에 강한 결속을 만든다. 서버 측 구현이 변경되면 클라이언트에는 반영되지 않아 망가진다.

앨리스의 예시

문서 없이 알게된건 알겠는데.. 이게 API 수정과는 관련이 뭐가있는건가??

수정해도 찾아내고 알아낼 수 있다!