🏛️
Let's write an API specification.
JSONPlaceholder Users API
API使用書なるものを書く場面が開発現場であると思うのですが、私はやったことがないので、ネットの情報を参考に無料のAPI使用書を使って作成してみました。
概要
このAPIはJSONPlaceholderのユーザー情報に関するAPIです。ユーザーの一覧取得、個別ユーザーの取得が可能です。
共通仕様
エンドポイント:
レスポンス: JSON形式
ユーザー情報取得
ユーザーの一覧を取得します。
GET /users
全ユーザーの情報を取得します。
レスポンス
HTTPステータスコード: 200
レスポンスボディ:
[
{
"id": 1,
"name": "Leanne Graham",
"username": "Bret",
"email": "Sincere@april.biz",
"address": {
"street": "Kulas Light",
"suite": "Apt. 556",
"city": "Gwenborough",
"zipcode": "92998-3874",
"geo": {
"lat": "-37.3159",
"lng": "81.1496"
}
},
"phone": "1-770-736-8031 x56442",
"website": "hildegard.org",
"company": {
"name": "Romaguera-Crona",
"catchPhrase": "Multi-layered client-server neural-net",
"bs": "harness real-time e-markets"
}
},
{
"id": 2,
"name": "Ervin Howell",
"username": "Antonette",
"email": "Shanna@melissa.tv",
"address": {
"street": "Victor Plains",
"suite": "Suite 879",
"city": "Wisokyburgh",
"zipcode": "90566-7771",
"geo": {
"lat": "-43.9509",
"lng": "-34.4618"
}
},
"phone": "010-692-6593 x09125",
"website": "anastasia.net",
"company": {
"name": "Deckow-Crist",
"catchPhrase": "Proactive didactic contingency",
"bs": "synergize scalable supply-chains"
}
}
]
GET /users/{id}
指定したIDのユーザー情報を取得します。
パスパラメータ
id: 取得するユーザーのID
レスポンス
HTTPステータスコード: 200
レスポンスボディ:
{
"id": 1,
"name": "Leanne Graham",
"username": "Bret",
"email": "Sincere@april.biz",
"address": {
"street": "Kulas Light",
"suite": "Apt. 556",
"city": "Gwenborough",
"zipcode": "92998-3874",
"geo": {
"lat": "-37.3159",
"lng": "81.1496"
}
},
"phone": "1-770-736-8031 x56442",
"website": "hildegard.org",
"company": {
"name": "Romaguera-Crona",
"catchPhrase": "Multi-layered client-server neural-net",
"bs": "harness real-time e-markets"
}
}
HTTPステータスコード: 404
レスポンスボディ:
{
"error": "User not found"
}
まとめ
今回は、API仕様書なるものの書き方を学習してみました。今回やったことだと、エンドポイントがどこか？、HTTP GETメソッドを使う。リクエストのレスポンスのJSONのデータの構造の解説、ステータスコードが２００が返ってくるという解説をしております。
今回参考にしたサイト:
OpenAPIなるものでは、APIの設計書を作れるとか?
こっちは、YAMLなので人間読むものではないと思ってます😇
Discussion