😄

APIについてざっくりまとめ

に公開
API
tech

APIについてざっくりまとめ

APIとは

ソフトウェアコンポーネントの外部インターフェース(機能)を外部から呼び出す仕様のこと。

APIエコノミー

APIを公開することで自サービスがより発展・成長することができる。InstagramやXなど主要サービスがAPIを公開することで関連サービスができ発展してきた。

デメリットとして、時間当たり何回までのようなレート制限などをかけておかないと自サービスのリソースを圧迫して最悪サービスダウンということになってしまう。

他サービスにはない独自性のある機能をAPIとして公開するようにする。単純な四則演算機能などは公開する意味がなくなる。

HTTPメソッド

HTTPでのアクセス時に指定する

これほしい～、これほかしといて～みたいな行動を表している

メソッド名 説明
GET リソースの取得
POST リソースの新規登録
PUT 既存リソースの更新
DELETE リソースの削除
PATCH リソースの一部変更
HEAD リソースのメタ情報の取得

エンドポイント

APIのアクセスするためのURL

エンドポイントは覚えやすく、URLを見たらどのような機能をもつか一目でわかるのが良い
エンドポイント設計のポイント

  • 短くて入力しやすい
  • 良く知られた英単語等を使用
  • 小文字(一般的にこちらが使用されているので)
  • 改造しやすい
    • /items/:idの:id部分を変更すると別のアイテムの情報が取得できるようなURIと本に記してある

以下のようなのエンドポイントが一般的

目的 エンドポイント メソッド
ユーザー一覧取得 http://api.example.com/v1/users GET
ユーザーの新規登録 http://api.example.com/v1/users POST
特定のユーザーの情報の取得 http://api.example.com/v1/users/:id GET
ユーザーの情報の更新 http://api.example.com/v1/users/:id PUT/PATCH
ユーザーの情報の削除 http://api.example.com/v1/users/:id DELETE

クエリーパラメータ

URLの末尾に?xxx=yyyの形式で付与される追加情報のこと。複数パラメータを指定した場合、&で連結することができる。

一般的なクエリーパラメータ

パラメータ名 説明 一般的な値 使用例
page ページネーション用のページ番号 数値 ?page=1
limit 1ページあたりの表示件数 数値 ?limit=10
sort ソートの基準となるフィールド 文字列 ?sort=created_at
order ソート順 asc/desc ?order=desc
q 検索キーワード 文字列 ?q=smartphone
filter フィルタリング条件 文字列 ?filter=category:electronics
fields 返却するフィールドの指定 カンマ区切りの文字列 ?fields=id,name,price
offset スキップするレコード数 数値 ?offset=20
lang 言語指定 言語コード ?lang=ja

ステータスコード

HTTPリクエストに対する処理結果を3桁の数値で表現したもの

100番台 情報
コード 説明
100 Continue - リクエストの継続
101 Switching Protocols - プロトコル切り替え
200番台 成功
コード 説明
200 OK - リクエスト成功
201 Created - リソース作成成功
204 No Content - 成功したが返却コンテンツなし
300番台 リダイレクト
コード 説明
301 Moved Permanently - 恒久的な移動
302 Found - 一時的な移動
304 Not Modified - キャッシュを使用
400番台 クライアントサイドに起因するエラー
コード 説明
400 Bad Request - 不正なリクエスト
401 Unauthorized - 認証が必要
403 Forbidden - アクセス権限なし
404 Not Found - リソースが存在しない
429 Too Many Requests - リクエスト制限超過
500番台 サーバサイドに起因するエラー
コード 説明
500 Internal Server Error - サーバー内部エラー
502 Bad Gateway - ゲートウェイエラー
503 Service Unavailable - サービス利用不可
504 Gateway Timeout - ゲートウェイタイムアウト

参考

間違っていることがあればコメントに書いていただけると幸いです。
よろしくお願いいたします。

GitHubで編集を提案

Discussion