web-dev-qa-db-ja.com

key = valueストレージREST APIを正しく実装する方法

私はREST APIを初めて使用するので、小さなWebサービスAPIを設計することで、このAPIに慣れることにしました。その設計を書き留めて、レビューしてもらいたいと思います。私はそれを設計し、RESTの概念を理解する際にいくつかの間違いを犯しました。これらの概念は、最後に自分の設計に関する質問で対処しようとしています。APIでのURLの使用についてはほとんど確信がありません。

私が設計しようとしているWebサービスは、ユーザーがkey = valueペアを保存する方法を提供します。つまり、キーを知っている値を取得し、既存のキーの値を更新し、既存のキーを削除します。アクションのCRUDセット全体！

これが私が思いついたものです。

バージョン管理

APIが進化する可能性があるため、APIバージョンの概念が必要なので、

GET api.example.com/supported-versions

サポートされているAPIバージョンを示す整数のJSONリストを返します。

APIはapi.example.com/{VERSION}/エンドポイントで使用できます。 api.example.com/1/：最初のバージョン。

Key = Valueストレージ

GET api.exmaple.com/1/keys/{KEY}

ユーザーがキーKEYに関連付けられた値を取得できるようにします。サーバーは、ステータスコード（200、404など）と成功時にテキスト値で応答します。どちらもJSONでエンコードされています。

POST and PUT api.exmaple.com/1/keys/{KEY}?value={VALUE}

ユーザーがキーKEYに関連付けられた値を作成/更新できるようにします。サーバーはステータスコード（200、404など）を返します。 VALUEはテキスト文字列です。

DELETE api.exmaple.com/1/keys/{KEY}

ユーザーがキーKEYを使用してkey = valueペアを削除できるようにします。 key = valueペアを削除し、ステータスコード（200、404など）を返すサーバー。

上記のPOST/PUT/DELETEメソッドに使用されるOAuth2認証が設定されていると想像してみましょう（ただし、GETでは誰もがGETできません。そのための認証は必要ありません）。一意に識別する方法があります。ユーザーと、どのキー=値のペアがどのユーザーに属するかを追跡します。

ここで、認証されたユーザーが所有するすべてのキーのリストを取得できるようにして、後でDELETEまたはPUTリクエストを送信するためにクライアント側にこの情報を保存する必要がないようにします。

GET api.exmaple.com/1/keys?page={PAGE}

これにより、ユーザーは作成した既存のすべてのキーのリストを取得できます。 PAGEはオプションのパラメーターです。ユーザーは、エラーステータスコードを受け取るまでページ数を増やすことができます。これは、ユーザーが作成したすべての既存のキーのページ化されたリストとステータスコード（200、404など）を返します。

このAPIに問題はありますか？

Key = value storageセクションからの最初のGET/POST/PUT/DELETEは/keys/または/values/にある必要がありますか？

最後の「GET」、つまりユーザーが持っているすべてのキーを返すものも/keys/で問題ないでしょうか？

restapiapi-designweb-api
6
Waffle Lord

あなたの解決策は大丈夫です、いくつかのことのために保存してください：

  1. バージョン管理RESTリソースレベルでのAPIは、必ずしもコンセンサスビューである必要はありませんが、一般的には良い方法ではありません。コメントや詳細な議論へのリンクについては こちら を参照してください。

  2. 2番目の質問では、おそらく/keys/{id}/または/values/{id}/が正しいかどうかについてどちらかの方法で議論できますが、私の本能はkeysを使用することです。タプル、または/data/や/elements/などのまったく異なる名前、またはこれらが実際に表すものを使用します。

  3. 私はおそらく、キーと値の辞書全体に対して異なるGETメソッドを持っているでしょう。 /keys/{id} /、および特定のユーザー向けの個別のリソース。 /users/{id}/keys/{keyId}。

最後に、POST/PUT/DELETEメソッドでクエリ文字列を使用することは（可能ですが）良くありません。結局のところ、これはquery文字列です。代わりに、POST /data/を使用して、Key-ValueペアをJSONデータとしてリクエストの本文に含めることができます。 この質問 も参照してください。

8
Dan1701

RESTサービスがユーザーのキーや使用可能なバージョンなどのリソースのリストを返す場合、これらのリソースへのURLを含む（json）構造体を返します。このアプローチの利点。

例えば。リクエスト：

HTTP> GET /Data/Version=1/User=Kasper/My_keys

結果は次のようになります。

200

{ keys: 
   [ 
      { name: "SO_account",
        link: "http://api.example.com/Data/Version=1/keys/SO_Account
      },
      { name: "Facebook_account";
        link: "http://api.example.com/Data/Version=1/keys/Facebook_account"
      }
   ]
}
1
Kasper van den Berg