rest - Api ブループリントが理解できる 2 次元のキーと値の形式は何ですか?

Question

API ブループリントを使用して RESTful 検索 API の API ドキュメントを開発しています。フィルターを API に渡して組み立てられるようにしたいと思います。

filter[filtername1]=filtervalue1
filter[filtername2]=filtervalue2

この質問に従って、私はパーセントでエンコードされた角括弧を使用していますが、この質問とは異なり、考えられるすべてのキー名を説明することはできません。

ソースデータの任意のフィールドになる可能性があるため、キー名を可変にしたいと考えています。これは機能しますか？

## Key-Value-Test [/api/v1/keyvaluetest?term={term}&filter%5B{field_name}%5D={field_value}]

+ term
+ filter_field
+ filter_value

このような 2 次元配列の推奨形式はありますか? + filter_field実際には一致しないため、これは Dredd では機能しないようです。filter[filter_field]

score 5 · Accepted Answer

残念ながら、API Blueprint と Apiary では、この種の動的 URL 定義はまだ許可されていません。

次の URI テンプレートは、その RFC によれば有効ではありません

GET /resource?year={year}&month={month}

URL を変更して、次のように定義できます。

## Key-Value-Test [/api/v1/keyvaluetest{?term,field_name,field_value}]

+ Parameters
    + term: a
    + field_name: b
    + field_value: c

この方法には 2 つの注意事項があります。

score 3 · Accepted Answer

API ブループリントはURI テンプレート標準を使用します。配列を表現および展開する方法はありますが (セクション 3.2.1を参照)、「標準 URI アプローチ」を想定しています。つまり、URI は次のように展開されます。

/api/v1/keyvaluetest?term=yourterm&filter=filtervalue1&filter=filtervalue2

これは、最も人気のある Web 言語が 2000 年代に普及したことを除いて、配列を行う「標準的な」方法です。

テンプレートは拡張用に設計されています。一連の変数と文字列を与えると、適切にフォーマットされた文字列が得られます。私の知る限り、「ワイルドマッチ」(文字列の特定の位置にパターンマッチ変数を挿入する) はありません。

URL テンプレートの領域内で考えられる唯一の解決策は、爆発修飾子を利用することです (複合値を参照)。

/api/v1/keyvaluetest{?keys*}

これは、値の連想配列が適切に展開される[(filter%5Bfiltername1%5D, filtervalue1), (filter%5Bfiltername2%5D, filtervalue2) ] 必要があります。

ただし、「動的キー」がサポートされているとは思えず、ほとんどのツールが (まだ) それを処理しないと思うので、 MSONでそれらを指定する方法がわかりません。

尋ねる価値があるかもしれません。

2 に答える 2