本記事は、Mohammad Faisal氏による「22 Best Practices to Take Your API Design Skills to the Next Level」（2021年4月15日公開）の和訳を、著者の許可を得て掲載しているものです。

API設計スキルを次のレベルに引き上げるベストプラクティス22選

REST API設計のための実践的アドバイス

Photo by Andrea Piacquadio from Pexels

はじめに

すべてが分かりにくく、ひどいAPIに不満を感じたことはありませんか？私はそうです。

マイクロサービスの世界では、バックエンドAPIの一貫した設計が不可欠です。

今日は、知っておくべきベストプラクティスについて、簡潔に説明します。さあ始めましょう！

用語

API設計は、リソース指向設計というものに従います。3つの重要な概念で構成されています。

リソース：データの一部（例：ユーザー）
コレクション：リソースのグループ（例：ユーザーリスト）
URL：リソースやコレクションの場所（例：/user）

1. URLにケバブケースを使う

例えば、注文リストを取得する場合です。

悪い

/systemOrders or /system_orders

良い

/system-orders

2. パラメータにキャメルケースを使う

例えば、特定のショップの商品を取得する場合です。

悪い

/system-orders/{order_id} or /system-orders/{OrderId}

良い

/system-orders/{orderId}

3. コレクションを指す複数形の名前

システムの全ユーザーを取得する場合です。

悪い

GET /user or GET /User

良い

GET /users

4. URLはコレクションで始まり、識別子で終わる

概念の単一性と一貫性を保つ場合です。

悪い

GET /shops/:shopId/category/:categoryId/price

リソースではなくプロパティを指しているため、よくありません。

良い

GET /shops/:shopId/ or GET /category/:categoryId

5. リソースURLに動詞を使わない

URLで意図を表すために動詞を使わないでください。代わりに、適切なHTTPメソッドを使って操作を記述しましょう。

悪い

POST /updateuser/{userId} or GET /getusers

良い

PUT /user/{userId}

6. 非リソースURLには動詞を使う

操作のみを返すエンドポイントの場合、動詞を使います。例えば、ユーザーにアラートを再送する場合です。

良い

POST /alerts/245743/resend

これはCRUD操作ではないことに注意してください。むしろ、システムで特定の仕事をする関数と考えられます。

7. JSONのプロパティにキャメルケースを使う

リクエスト本文やレスポンスがJSONのシステムを構築している場合、プロパティ名はキャメルケースである必要があります。

悪い

{
user_name: "Mohammad Faisal"
user_id: "1"
}

良い

{
userName: "Mohammad Faisal"
userId: "1"
}

8. モニタリング

RESTful HTTPサービスは、/health、/version、/metricsの各APIエンドポイントを実装する必要があります。これらは以下の情報を提供します。

/health

/healthへのリクエストに200 OKステータスコードで応答します。

/version

/versionへのリクエストにバージョン番号で応答します。

/metrics

このエンドポイントは、平均応答時間などのさまざまなmetricsを提供します。

/debugと/statusエンドポイントも強くおすすめします。

9. リソース名にテーブル名を使わない

リソース名にテーブル名を使わないでください。長期的には、この種の怠慢は有害です。

悪い

product_order

良い

product-orders

基本的なアーキテクチャの公開が目的ではないからです。

10. API設計ツールを使う

優れたドキュメントを作るためのAPI設計ツールがたくさんあります。

Swagger

優れた詳細ドキュメントによって、API利用者にとって素晴らしいユーザーエクスペリエンスが得られます。

11. バージョンに単純な序数を使う

APIに常にバージョン管理を使い、左に移動して範囲を広げます。バージョン番号はv1、v2などにします。

良い

http://api.domain.com/v1/shops/3/products

APIが外部エンティティに使われている場合、エンドポイントを変更するとその機能が使えなくなる可能性があるため、APIには常にバージョン管理を使ってください。

12. レスポンスにリソースの総数を含める

APIがオブジェクトのリストを返す場合、必ずリソースの総数をレスポンスに含めてください。totalプロパティを使います。

悪い

{
    users: [
        ...
    ]
}

良い

{
    users: [
        ...
    ],
    total: 34
}

13. limitパラメータとoffsetパラメータを受け入れる

GET操作では、常にlimitパラメータとoffsetパラメータを受け入れましょう。

良い

GET /shops?offset=5&limit=5

フロントエンドでのページネーションに必要だからです。

14. fieldsクエリパラメータを使う

返されるデータ量も考慮する必要があります。fieldsパラメータを追加して、APIから必要なフィールドのみを公開します。

例えば、ショップ名、住所、連絡先のみを返す場合です。

GET /shops?fields=id,name,address,contact

場合によっては、レスポンスサイズの縮小にも役立ちます。

15. URLに認証トークンを渡さない

これは非常に悪い習慣です。多くの場合、URLがログに記録され、認証トークンも不必要に記録されるからです。

悪い

GET /shops/123?token=some_kind_of_authenticaiton_token

良い

代わりに、ヘッダーで認証トークンを渡します。

Authorization: Bearer xxxxxx, Extra yyyyy

また、認証トークンは短命であるべきです。

16. コンテンツタイプを有効にする

サーバーは、コンテンツタイプを憶測してはいけません。例えば、application/x-www-form-urlencodedを受け入れた場合、攻撃者はフォームを作成し、単純なPOSTリクエストをトリガーできます。

そのため、常にコンテンツタイプを有効にし、デフォルトのものを使う場合は、content-type: application/jsonを使います。

17. CRUD機能にHTTPメソッドを使う

HTTP メソッドは、CRUD機能を説明する目的で使います。

GET：リソースの表現を取得する

POST：新しいリソースやサブリソースを作成する

PUT：既存のリソースを更新する

PATCH：既存のリソースを更新する、提供されたフィールドのみを更新し、他のフィールドはそのままにする

DELETE：既存のリソースを削除する

18. ネストされたリソースURLにリレーションを使う

実例です。

GET /shops/2/products：ショップ2の全商品リストを取得する
GET /shops/2/products/31：ショップ2の商品31の詳細を取得する
DELETE /shops/2/products/31：ショップ2の商品31を削除する
PUT /shops/2/products/31：商品31の情報を更新する、PUTはコレクションではなくリソースURLのみに使う
POST /shops：新しいショップを作成し、そのショップの詳細を返す、POSTはコレクションURLに使う

19. CORS

全公開APIに対してCORS（Cross-Origin Resource Sharing）ヘッダーをサポートします。

CORSが許可した「*」のオリジンのサポートと、有効なOAuthトークンを使った認証の実施を検討してください。

ユーザー資格情報とオリジン認証の組み合わせは避けてください。

20. セキュリティ

全エンドポイント、リソース、サービスにHTTPS（TLS暗号化）を適用します。

全コールバックURL、プッシュ通知エンドポイント、Webhookに、HTTPSを適用してリクエストします。

21. エラー

エラー、厳密にはサービスエラーが発生するのは、クライアントがサービスに対して、無効または不正なリクエストを行ったり、無効または不正なデータを渡したりして、サービスがそのリクエストを拒否した時です。

例えば、無効な認証情報、不正なパラメータ、不明なバージョンIDなどです。

1つ以上のサービスエラーによりクライアントリクエストを拒否する場合は、4xx HTTPエラーコードを返す
全属性を処理してから、単一の応答で複数の認証問題を返すことを検討する

22. ゴールデンルール

APIフォーマットの決定に迷った場合は、以下のゴールデンルールが正しい決定をする指針となります。

フラットはネストより良い
単純は複雑より良い
文字列は数字より良い
一貫性はカスタマイズより良い

おわりに

これで終了です。ここまで読んだ方に、拍手を送ります！この記事から何かを学んでいただけたら嬉しいです。良い一日を！

何かありましたら、ぜひLinkedInでご連絡ください。

Reactの16の問題を解決する45のNPMパッケージ
完璧なnpmパッケージの選び方を徹底解説
javascript.plainenglish.io

クリーンなReactプロジェクトの21のベストプラクティス
コード品質向上のための実践的アドバイス
betterprogramming.pub
qiita.com

リソース

翻訳協力

この記事は以下の方々のご協力により公開する事ができました。改めて感謝致します。

Original Author: Mohammad Faisal (Linkedin)
Original Article: 22 Best Practices to Take Your API Design Skills to the Next Level
Thank you for letting us share your knowledge!

選定担当: @gracen
翻訳担当: @gracen
監査担当: -
公開担当: @gracen

ご意見・ご感想をお待ちしております

今回の記事はいかがでしたか？
・こういう記事が読みたい
・こういうところが良かった
・こうした方が良いのではないか
などなど、率直なご意見を募集しております。
頂いたお声は、今後の記事の質向上に役立たせて頂きますので、お気軽に
コメント欄にてご投稿ください。Twitterでもご意見を受け付けております。
皆様のメッセージをお待ちしております。