私は開発者であり、私のキャリアのほとんどの間、さまざまなサービスのAPIを構築してきました。この記事のガイドラインは、チームとして独自のサービスを設計するとき、またはサードパーティのAPIを使用するときの最も一般的な問題に基づいて編集されています。
恐ろしいAPIプロバイダーに出くわした可能性があります。彼らと一緒に働くことは、原則として、感情と誤解の増加に関連しています。これらの問題のほとんどは、以下のヒントを使用してアプリケーションインターフェイスを設計することで回避できます。
1.URLで動詞を使用しないでください*
* -これがCRUD操作の1つである場合。
CRUDリクエストメソッドは、リソースを使用したアクションを担当します：POST-作成（作成）、GET-取得（読み取り）、PUT / PATH-更新（更新）、DELETE-削除（ご存知）。悪い：
POST /users/{userId}/delete -
POST /bookings/{bookingId}/update -
はい：
DELETE /users/{userId}
PUT /bookings/{bookingId}
2.URLで動詞を使用します
悪い：
POST /users/{userId}/books/{bookId}/create -
はい：
POST /users/{userId}/books/{bookId}/attach
POST /users/{userId}/notifications/send -
3.新しいエンティティを強調表示します
上記に、ユーザーに本を追加する例があります。おそらく、アプリケーションのロジックがお気に入りのリストを暗示している場合、ルートは次のようになります。
POST /wishlist/{userId}/{bookId}
4.1つのリソースIDを使用します*
*-データ構造で許可されている場合。
これは、たとえば、
予約->旅行者（予約->旅行者）のように1対多のレコードがある場合、リクエストで旅行者IDを渡すだけで十分であることを意味します。
悪い：
#
GET /bookings/{bookingId}/travellers/{travellerId}
はい：
GET /bookings/travellers/{travellerId}
また、APIでデータ階層に固執する/bookings/travellers/
よりも優れていることにも注意して/travellers
ください。
5.
:
GET /user/{userId} -
POST /ticket/{ticketId}/book -
:
GET /users/{userId}
POST /tickets/{ticketId}/book
6. HTTP-
- . . :
400 Bad Request - , , .
401 Unauthorized - .
403 Forbidden - , .
404 Not Found - .
409 Conflict - , .
500 Internal Server Error - .
503 Service Unavailable - .
7.
. , - (quizzes passed_quizzes). , .
: /quizzes
/quizzes/passed
. quizzes
- (), passed
- ().
:
GET /passed-quizzes -
GET /booked-tickets -
POST /gold-users -
:
GET /tickets/booked
POST /users/gold
8.
API - . , , .
:
GET /book/{bookId}
{
"name": "Harry Potter and the Philosopher's Stone",
"genre": "fantasy",
"status": 0, #
"error": false,
...
}
:
GET /book/{bookId}
{
"status": 0,
"message": "ok",
"data": {...}
}
3 . status
, message
- , , . , , . 409 status
message
.
9. json camelCase
9.1クエリパラメータで
悪い：
GET /users/{user-id}
GET /users/{user_id}
GET /users/{userid}
はい：
GET /users/{userId}
POST /ticket/{ticketId}/gold
9.2応答または受信した要求の本文
Bad：
{
"ID": "fb6ad842-bd8d-47dd-b7e1-68891d8abeec",
"Name": "soccer3000",
"provider_id": 1455,
"Created_At": "25.05.2020"
}
はい：
{
"id": "fb6ad842-bd8d-47dd-b7e1-68891d8abeec",
"Name": "soccer3000",
"providerId": 1455,
"createdAt": "25.05.2020"
}
10.Content-Typeを使用する
悪い：
GET /tickets.json
GET /tickets.xml
はい：
GET /tickets
//
ontent-Type: application/json
//
ontent-Type: application/xml
結論
上記の推奨事項は、APIを改善する方法のすべてのリストではありません。さらに調査するために、REST API仕様とhttpステータスコードのリストを解析することをお勧めします（それらがいくつあり、どのような状況をカバーしているかに驚かれることでしょう）。
また、コメントでは、重要と思われるRESTAPIを構築するための独自の推奨事項を作成することをお勧めします。