現場で使えるAPI設計
API設計
GoogleのAPI設計ガイドをベースにAPI設計を行っています。
今回はその中でも特に「標準メソッド」について触れます。
標準メソッド
「List」,「Get」,「Create」,「Update」,「Delete」の5つから成る標準メソッドを用いてAPI設計方針を定めています。
＊標準メソッドに該当しないAPIはカスタムメソッドを参考にしています。
メリット
- 各エンドポイントの使用の予測が容易になり、学習コストが低下する
- 新たなAPIの作成や既存のAPIのメンテナンスのコストの低下する
- 一貫性が保たれているため、バグの削減に貢献する
以下は記事に関する標準メソッドのAPIの例です。
| 標準メソッド | HTTPメソッド | エンドポイント | 例 |
|---|---|---|---|
| List | GET | /articles | GET /articles |
| Get | GET | /articles/{id} | GET /articles/1234 |
| Create | POST | /articles | POST /articles |
| Update | PUT | /articles/{id} | PUT /articles/1234 |
| Delete | DELETE | /articles/{id} | DELETE /articles/1234 |
それぞれのメソッドについて簡単に説明します。
List
このメソッドは、特定のコレクションに関する情報をリスト形式で取得します。
コレクション名とパラメーターをもとにリソースの一覧を取得し、レスポンスとして返します。
Get
このメソッドは、特定のリソースに関する詳細な情報を取得するために使用されます。
リソース名とパラメーターをもとに指定されたリソースの詳細な情報を取得し、レスポンスとして返します。
Create
このメソッドは、新たなリソースを作成するために使用されます。
親リソース名、新たに作成するリソースの情報をもとに新しいリソースが親リソースの下に作成され、新たに作成されたリソースの情報がレスポンスとして返されます。
Update
このメソッドは、既存のリソースの情報を更新するために使用されます。
更新するリソースの情報をもとに指定されたリソースが更新され、その更新されたリソースの情報がレスポンスとして返されます。
Delete
このメソッドは、特定のリソースを削除するために使用されます。
削除するリソース名をもとに指定されたリソースの削除が行われ、空のレスポンスが返されます。
標準フィールド
フロントエンドとバックエンドなどの複数サービスの開発を円滑に進めるため、類似するコンセプトの標準メッセージフィールドの統一を行います。
メリット
メッセージの類似コンセプトを統一することで、以下のような利点が期待できます。
- 一貫性のある命名規則により、バグの削減
- リクエスト、レスポンスのメッセージ把握の学習コストの低下
- フロントエンドとバックエンドなどの複数サービス開発の開発者体験の向上
| フィールド名 | 説明 | 例 |
|---|---|---|
| id | リソースの一意のID。 | 12345 |
| name | リソースの一意の識別子。 | "Qiita" |
| description | リソースの一意の説明文 | "この記事はQiitaによって公開されています。" |
| createAt | リソースが作成された日時。 | "2023-10-21T19:20:30.45Z" |
| updateAt | リソースが最後に更新された日時。 | "2023-10-22T19:20:30.45Z" |
| deletedFlg | リソースが削除されているかのフラグ | true |
現場で感じた良かった点・改善した点
コーディング規約を運用していく上で、実際に感じたことを紹介したいと思います。
良かったこと
一つ目は、リソース指向の設計を反映しているためAPIの全体を把握しやすいことです。
API Group単位のリソースのキャッチアップのみで全体を把握することが可能です。
改善したこと
上記で紹介した標準メソッドは、複数のリソース依存のAPI設計に対応していないため、新たにコーディング規約を設計する必要がありました。
プロダクトが大きくなるにつれ、他のリソースと依存関係のある機能の需要が高まってくるかと思います。複数リソースにまたがるAPI設計が複雑化してしまうことがあります。
タグに紐づいた記事リストを取得するAPIが具体的な例です。
「タグ」と「記事」の二つのリソースに跨り、「タグ」のスラッグに紐づいた記事一覧を取得する機能です。
- api/v2/tags/${slugName}/articles
弊社では、URL構造として親リソースに「関連を示すリソース」（この場合は「タグ」）を示し、子リソースが「取得対象のリソース」（この場合は「記事」）を示すように設計しています。
特定のタグに関連する記事を取得することをURL上で直感的に理解できるようにリソースの関係性の明確化をしています。
上記は一例となりますが、複数リソースに跨るケースのAPI設計を弊社で定義する必要があります。
まとめ
API設計には様々なベストプラクティスが存在しており、エンジニアによって良い設計の基準も変わってきます。
そのため弊社ではコーディング規約を設けることでソフトウェアの品質を保つだけでなく、新しくジョインするエンジニアの学習コストの低下やバグの削減などに大きく貢献しています。
実際に自分がジョインした時も、コーディング規約があることでAPIの実装把握やAPI設計に悩むことなく実装できたのでその恩恵をものすごく感じています。
今後も良いソフトウェア品質を保つために、良いベストプラクティスがあればどんどん取り入れて行きたいと思います！