概要

P49-Oauth飛ばす… 色々なサービスのAPI例を確認できるサイト: https://any-api.com/ WebAPI … HTTPプロトコルを利用して呼び出すAPI 【要確認】ネストがあるとレスポンス容量が増えてしまうので、無駄なネストを減らすようにレスポンスを設計する。

設計

レスポンスのデファクトスタンダードは「JSON」である。 エンベロープは不要である。ステータスコードやヘッダで情報は十分。

内部向けのAPIは汎用的である必要はない。 格言2014年「1画面の表示にAPIの呼び出しは1回であるべき。1登録のAPI呼び出しは1回であるべき。」

ステータスコード

一般的によく使われるコード一覧

番号	名称	説明
201	Created	POST 作成完了
204	No Content	DELETE PUT 完了
401	Unauthorized	認証エラー
403	Forbidden	認可エラー あまり使われない？
409	Conflict	GET以外すべて 既に存在している

エンドポイント

覚えやすくどんな機能なのかひとめで分かるURIであること。 短いエンドポイントであること。http://sample.jp/v1/search よく使われる単語を選択することがとても重要。users items 複数形の名詞を使うこと。特定のリソースを指定する場合は単数形でも問題ない。 単語を繋げる場合はハイフン。 自身のユーザIDが必要な連携の場合meを設定することがよくある。 ホスト名に「api」を入れるパターンが9割位上。http://api.github.com バージョン管理はURIの先頭に「v1」を設定するのが一般的である。もちろん他の記述も見かけるがこれが分かりやすい。

基本型

機能	エンドポイント	メソッド
ユーザ一覧取得	/v1/users	GET
ユーザ一新規登録	/v1/user	POST
特定ユーザの情報取得	/v1/user/:id	GET
ユーザ情報の更新	/v1/user/:id	PUT
ユーザ情報の削除	/v1/user/:id	DELETE
ユーザの友達一覧取得	/v1/users/:id/friends	GET
ユーザの友達追加	/v1/users/:id/friends	POST
自身の情報の取得	/v1/users/me

クエリパラメータ

検索の絞り込みはクエリパラメータで指定する。?name=taro

例

項目	パラメータ
limit	取得数
offset	取得位置（相対）

レスポンス

// 基本型
{
    "users": [
        {
            "id": 1,
            "name": "Taro",
        },
        {
            "id": 2,
            "name": "Hanako",
        },
    ]
}

エラーハンドリング

ステータスコードは必ず設定すること。200 404 エラー詳細は一般的にレスポンスボディで返却する。ヘッダで返却するのもよいが意外と少数派である。

// レスポンスボディで情報を返す基本型
{
  "error": {
    "code":215,
    "message": "Bad Authentication data",
    "info": "http://sample.com",
  }
}

セキュリティ

セキュアなWebAPIの作り方 Oracle公式 : https://speakerdeck.com/oracle4engineer/secure-web-api