API를 이용하는 측에 응답으로서 어떤 데이터를 반환할 것인가를 검토한다.

응답 데이터 설계에 대한 사고 방식

API 응답 데이터는 대부분의 경우에 프로그램으로 처리된다. 또한 HTTP를 통해 API가 호출되므로 HTTP 오버 헤드도 발생합니다. 그러므로

가능한 한 프로그램으로 처리하기 쉬운 응답 데이터

API에 대한 액세스 횟수는 최대한 최소로

를 염두에 고려할 필요가 있다.

응답 데이터의 형식 검토

JSON, XML 등의 포맷을 검토한다. 옛날에는 XML 형식이 많았지만 최근에는 JSON 형식이 주류. 다음은 Google 트렌드의 검색 결과(빨강은 'xml api', 파란색은 'json api').

또, 주요한 웹 서비스는 JSON을 기본으로 하고, 서비스에 따라서는 XML도 서포트하고 있다. 즉 세상의 Web API는 JSON이 디팩트 표준이 되고 있는 모양. 그래서 깊이 검토하지 않고 JSON으로 결정해 버려, 수요가 있으면 XML도 서포트한다고 하는 형태가 바람직하다고 생각한다. 또한 왜 XML이 아닌 JSON인지는 JSON에 눌려지는 XML의 존재에도 기재되어 있지만, 간결하게 정리하면 다음과 같다 있다는 것).

JSON이 더 간단합니다

JSON 쪽이 JavaScript와의 궁합이 좋다

응답 데이터 검토

실제로 어떤 데이터를 반환하는지 고려하십시오. 그 때의 사고방식으로서, 서두에서도 기재한 바와 같이 「API에의 액세스 횟수는 최대한 최소한으로」라고 하는 것을 염두에 검토한다. 이를 위해서도 RESTful API의 리소스 디자인 # 무엇을 리소스로 만드는가? 에서도 기재한 바와 같이, API의 유스 케이스를 명확화해 둘 필요가 있다. 예를 들어, 책의 정보를 반환하는 API가있는 경우, 다음과 같은 응답 데이터 (id 만)를 반환한다고 가정합니다.

{
    "books": [
        00001,
        00002,
        00003,
        00004,
        00005
     ]
}

책의 id만 반환해도, API를 이용하는 측으로부터 하면 대부분의 경우 그다지 의미는 없다. API를 이용하는 측의 유스 케이스로서는, 「책의 정보를 일람 표시한다」라고 하는 케이스를 생각할 수 있으므로, 최소한 id 외에도 책의 이름, 책의 상세를 기재한 페이지의 URL(물론 상세 URL이 아닌 출판사, 출판일 등의 상세 정보를 직접 반환해도 좋다)도 필요하다고 생각된다. 따라서, 다음과 같이 함으로써 한번의 API 호출로 필요한 정보를 모두 취득할 수 있으므로, API의 액세스 횟수를 적게 할 수 있다.

{
    "books": [
        {
            "id": 00001,
            "name": "本の名前1",
            "url": "http://example.com/books/00001"
        },
        {
            "id": 00002,
            "name": "本の名前2",
            "url": "http://example.com/books/00002"
        },
        {
            "id": 00003,
            "name": "本の名前3",
            "url": "http://example.com/books/00003"
        }
     ]
}

각 항목의 항목 이름에 대한 데이터 형식 정의

RESTful API 리소스 디자인 # 리소스의 각 항목에 대한 데이터 형식 정의에 설명 된대로 응답 데이터의 각 항목의 데이터 유형과 항목 이름을 고려하십시오. 데이터 모델 설계로 해도 문제 없다고 생각하지만, 어느 쪽인가 하면 자원 설계의 단계에서 검토해야 할 내용이라고 생각한다. 또한, 항목명을 명명할 때의 주의점으로서는 이하와 같은 것이 있다.

많은 API에서 동일한 의미로 사용되는 일반적인 단어를 사용합니다

가능한 한 적은 단어 수로 표현

이상한 약어는 가능한 한 많이 사용하지 않습니다

복수의 단어를 연결하는 경우, 그 연결 방법은 API 전체를 통일한다

단수형/복수형에주의하십시오

오류 발생시 응답 데이터 검토

RESTful API 오류 설계 에서 별도 정리한 대로.

참고

RESTful 웹 서비스
웹 API: The Good Parts