web-dev-qa-db-ja.com

リソース表現とREST APIドキュメントツール

RESTfulなリソースのさまざまな表現を持つことの正確な意味がわからない。正規の例は、APIがエンドポイントを提供するためのものです-/v1/users/:id-メディア範囲の値に応じて、クライアントがJSON、XML、HTMLまたはPDFからリソースの最適な表現を選択できるようにしますACCEPTヘッダー。

このrepresentationの定義を拡張して、コンテンツタイプだけでなく実際には応答スキーマも含めることができるという印象を受けました。たとえば、クライアントが、サポートされているヘッダーを指定することで取得できるユーザーに関する詳細情報を必要としているとします。

したがって、たとえば、私のアプリケーションは、同じリソースに対して異なるスキーマを提供できます。

# get the default user representation
GET /v1/users/1234
ACCEPT: application/vnd.myapp.v1+json

# server responds with
{"id": 1234, "name": "Jeffery Lebowski"}

# get the extended user representation
GET /v1/users/1234
ACCEPT: application/vnd.myapp.v1.extended+json

# server responds with
{"id": 1234, "name": "Jeffery Lebowski", "sport": "Bowling"}

RESTでの表現の概念を正しく理解していますか？または、リソース表現の概念はコンテンツタイプとコンテンツネゴシエーションにのみ適用できますか？

もしそうなら、私のAPIが返すことができるさまざまな表現をどのように文書化できますか？大きなドキュメントツール（ swagger.io または [〜＃〜] raml [〜＃〜] ）のどちらも、複数のスキーマ表現のドキュメント化をサポートしているようには見えません。単一のリソース。

restapi-designdocumentation-generation
6
Jason

https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_Arch_style.htm#sec_5_2_1_2

あなたは表現についてのあなたの理解がまったく正しいです。そして、同じものの異なる表現を取得するRESTfulな方法は、クライアントとサーバー間で標準化されたメディアタイプを使用してコンテンツネゴシエーションを行うことです。

HTTPでは、表現/コンテンツネゴシエーションを行う標準的な方法は、ACCEPTヘッダー（RFC 7231＃section-5.3.2）と標準化されたメディア範囲（RFC 6838＃section-4.2）を使用することです。

メディアタイプスキーマは、ファセット "。"を使用すると思います。また、メディアタイプの命名方式の接尾辞「+」の部分は許可および推奨する必要があります。あなたがしたその拡張、私見それはそれを行うための正しいそして実用的な方法でもあります。

RAMLは複数の表現をサポートします：

#%RAML 0.8
title: REST Content Negotiation Example
version: 0.1
baseUri: http://example.com

/v1/users/:
  displayName: users
  /{id}:
    displayName: id
    uriParameters:
      id:
        type: integer
    get:
      responses:
        200:
          body:
            application/vnd.myapp.v1+json:
              example: |
                {"id": 1234, "name": "Jeffery Lebowski"}

            application/vnd.myapp.v1.extended+json:
              example: |
                {"id": 1234, "name": "Jeffery Lebowski", "sport": "Bowling"}
8
Bruno Laturner