APIデザイン

リファレンス
まず第一に、私はthis articleですべてを参照したいです.すべての詳細については、それをお読みください.我々が一緒に働いていたならば、私がハイライトする3つのものがあります.

実体
ほとんどすべてのルートは実体か実体のコレクションを表すべきです.これは、クライアントが使用するためのページ化と適切なフィルタ能力を意味します.クライアントが実体を更新するのを要求するなら、実体は応答でなければなりません.上記の参照はよくこのトピックをカバーします.

バルク操作
バルク操作は上の記事ではカバーされません.私の好みは次のとおりです.

POST /route
...headers

[{ids: [1, 3], status: 0}, {ids: [2], status: 1}]

これはクライアントがデータを状態にマージできるように変更されたエンティティを返す必要があります.

エラー
最後の話題は、私が強調したいのはエラーです.クライアント側の問題に対して4 xx HTTPステータスを使用し、サーバー側の問題については5 xxを使用します.ほとんどのJSクライアントライブラリは自動的にエラーとして4 xxと5 xx HTTPステータスコードを解決します.だから私の意見では、文字通り正しいHTTPステータスコードを使用して難しい要件ではありません.レスポンスシグネチャは次のようになります.

{
  "message" : "Something bad happened :(",
  "description" : "More details about the error here"
}

{
  "message" : "Validation Failed",
  "errors" : [
    {
      "field" : "first_name",
      "message" : "First name cannot have fancy characters"
    },
    {
       "field" : "password",
       "message" : "Password cannot be blank"
    }
  ]
}

ほとんどの場合、クライアントはインターフェイスに直接メッセージフィールドを置くことができるはずです.これは、エンドユーザに対して人間が読めるように理解しやすく理解できることを意味します.メッセージは< 200 >文字でなければなりません.

エキストラ

JSONキーは、スペース

を決して持ってはいけません

リクエストがAccept: application/jsonヘッダーを送るならば、バックエンドは丁重に親切に応じなければなりません.

すごい!今、我々は一緒に働くことができます!