Web API: The Good Partsからの学び

エンドポイントの設計

覚えやすく、どんな機能を持つのURIなのか一目でわかる

Point

• 短く入力しやすい
• 人間が読んで理解できる
  • 無闇に文字を省略しない（ただしISO639など公に認知されているものは除く）
  • 英単語を使用する
  • 単語を繋げる必要がある場合はハイフンを利用する
• 大文字小文字が混在していない
• 改造しやすい(hackableな)
• サーバ側のアーキテクチャが反映されていない
• ルールが統一されている

URIとHTTPメソッドの関係

HTTPメソッドは「動詞」のようなもので、何をするか（例：取得、更新、削除）を示し、URIは「名詞」のようなもので、どのリソースに対して操作を行うかを指定します。つまり、URIが「どこに」という質問に答え、HTTPメソッドが「何を」という質問に答える。

HTTPメソッドの種類

URIのパスとクエリパラメータの使い分け基準

• パスの使用
  • リソースの識別: リソースを階層的に表現し、一意に識別する場合に使用。
  • 例: /users/12345（特定のユーザー）
• クエリパラメータの使用
  • 条件付けやフィルタリング: 検索条件や特定の属性でリソースをフィルタリングする場合に使用。
  • 例: /search?q=キーワード（キーワードで検索）、/users?status=active（ステータスでユーザーをフィルタリング）。

APIレスポンスデータ設計

基本方針

• APIコールの最小化: 必要なデータを取得するためのAPIコールを最少に保つ。
• データ量の削減: レスポンスデータの量を可能な限り減らす。

サポートするデータフォーマット

• SON
  • 現在の主流。基本的にJSONフォーマットのサポートを推奨。
• XML
  • 使用者は少数だが、特定の用途では依然として有用。

レスポンスデータのフィールド名設計指針

• 一般的な用語の使用: APIフィールド名には、一般的で理解しやすい単語を使用する。
• 単語数の最小化: フィールド名はなるべく少ない単語数で表現する。
• 単語の連結規則の統一: 複数の単語を連結する場合、API全体を通して同じ連結方法を採用する。
  • snake_caseまたはcamelCaseを利用することが多い
• 省略語の使用を避ける: 不自然な省略は避け、フィールド名を明確に保つ。
• 単数形と複数形の正確な使用: データの内容に応じて単数形や複数形を正しく使用する。

日付フォーマット

一般的なAPI利用においては、RFC 3339 形式を推奨。 特定の言語に依存した表記(Wed,May)を含まない。また日本語のように年月日の順で表示されているためわかりやすい。

HTTPレスポンスステータスコード

HTTPステータスコードのカテゴリー

• 100系 (Informational): クライアントのリクエストを受け取ったことを示し、プロセスが継続している状態。
• 200系 (Successful): クライアントのリクエストが正常に処理され、目的の操作が成功したことを示す。
• 300系 (Redirection): 完了のために追加のアクションが必要であることを示し、リクエストされたリソースが別の場所に移動したことを通知する。
• 400系 (Client Error): クライアントのリクエストにエラーがあることを示し、リクエストが正しく処理できなかったことを意味する。
• 500系 (Server Error): サーバ側に問題があることを示し、リクエストがサーバによって処理できなかったことを意味する。

よく見るStatusコード（一覧）

エラーレスポンス設計

有名どころのエラーレスポンスBody

Google API

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "invalidParameter",
    "message": "Invalid string value: 'asdf'. Allowed values: [mostpopular]",
    "locationType": "parameter",
    "location": "chart"
   }
  ],
  "code": 400,
  "message": "Invalid string value: 'asdf'. Allowed values: [mostpopular]"
 }
}

Microsoft Graph API

{
  "error": {
    "code": "badRequest",
    "message": "Uploaded fragment overlaps with existing data.",
    "innerError": {
      "code": "invalidRange",
      "request-id": "request-id",
      "date": "date-time"
    }
  }
}

Facebook API

{
  "error": {
    "message": "Message describing the error", 
    "type": "OAuthException", 
    "code": 190,
    "error_subcode": 460,
    "error_user_title": "A title",
    "error_user_msg": "A message",
    "fbtrace_id": "EJplcsCHuLu"
  }
}

RFC 9457

RFC 9457でHTTP APIで発生する問題の詳細を表現するための標準形式を定義しています。

{
    "type":"https://problems-registry.smartbear.com/missing-body-property",
    "status":400,
    "title":"Missing body property",
    "detail":"The request is missing an expected body property.",
    "code":"400-09",
    "instance":"/logs/regisrations/d24b2953-ce05-488e-bf31-67de50d3d085",
    "errors":[
       {
          "detail":"The body property {name} is required",
          "pointer":"/name"
       }
    ]
 }

New problem type definitions MUST document:

1. a type URI (typically, with the “http” or “https” scheme)
2. a title that appropriately describes it (think short)
3. the HTTP status code for it to be used with

参考

• swagger Problem Details (RFC 9457): Doing API Errors Well
• .NETでRFC 9457準拠のクラスProblemDetails Class
• RFC 9457

API Version Management

目的

APIのversion管理を導入する主な目的は、新しいversionのAPIがリリースされても、古いversionを使用しているクライアントが引き続き機能するようにすることです。これにより、安定性と互換性を保ちつつ、新機能の導入やセキュリティの改善が可能となります。

推奨されるURI構造

version管理をURIに反映させる一般的な方法は、以下のような形式です：

https://{FQDN}/v{version-number}/users

• v{version-number}: version番号を明示するために v を前置します。これにより、どのversionのAPIを呼び出しているかが一目で明確になります。
• {version-number}: 通常はメジャーversionの整数を使用します。セマンティックバージョニングを採用することもありますが、URLでの利用にはメジャーversionが最も適しています。

クエリパラメータによるversion指定 クエリパラメータを使用してAPIのversionを指定する方法もありますが、次の理由で私は推奨されません：

• 省略時の挙動: クエリパラメータが省略された場合、自動的に最新のversionのAPIが呼び出されるため、仕様が変更された際にクライアントアプリケーションが予期せず壊れるリスクがあります。
• 冗長性: クエリが冗長的に見え、URLの構造が複雑になるため、管理が煩雑になりがちです。

バージョンを変更する方針

APIのバージョンを更新する主な理由は、後方互換性を保持できなくなったときです。

たとえば:

• APIのエンドポイントの入力パラメータや返却値の変更: 既存のAPIエンドポイントに新しい入力パラメータを追加する場合や、返却するデータ形式を変更する場合、これらの変更が既存のクライアントに影響を与える可能性があるため、新バージョンをリリースします。
• 機能の削除: 使われなくなった機能や非効率なエンドポイントをAPIから削除する場合、後方互換性が失われるため、バージョンを上げる必要があります。

セキュリティ

APIを設計する際には、以下のセキュリティ対策を講じることが重要です。

• HTTPSを使用しよう: すべての通信をHTTPSを通じて行うことで、データの傍受や改ざんを防ぎます。

• XSS（クロスサイトスクリプティング）対策:
  • レスポンスでの対策: Content-Type: application/jsonと明示することで、ブラウザがレスポンスをJSONとして解釈し、スクリプトとして実行されるリスクを減らします。
  • 入力の検証とエスケープ: ユーザーからの入力を適切に検証し、HTMLエスケープ処理を行うことで、悪意のあるスクリプトが埋め込まれることを防ぎます。
• XSRF（クロスサイトリクエストフォージェリ）対策:
  • XSRFトークンの使用: フォームやAJAXリクエストに対して、サーバーから提供される一時的なトークンを使用し、リクエストが正当なものであるかを検証します。

公開されているAPIをまとめたサイト

• RapidAPI