Web APIの設計と開発：開発者のための基本ガイドライン

ソフトウェアアプリケーションは私たちの生活をいくつかの方法で簡単く、より良くしています。私たちはほとんど日に使用しており、いく人々はアプリケーションを他の人との交流よりももっと频繁に使用すると自覚しています。

しかし、アプリケーションがお互いにどのようにやりとりするのか？実は、APIs（アプリケーションプログラミングインターフェース）を通じて行います。この記事で、APIsが何であるのかを学ぶことができます。私たちはWeb APIsとその設計、開発に特に注目します。

Web APIとは何か？

Web APIは、インターネット上で使用する為に設計されたタイプのAPIです。つまり、ウェブベースのソフトウェアアプリケーション、システム、サービスはWeb APIを使用して、インターネット上で情報をやりとりします。通常、JSONやXMLなどの形式でリクエストを送信し、レスポンスを受信します。

Web APIは、以下の理由で現代のソフトウェア開発に重要な役割を果たしています。

互換性：APIsは技術に依存せず、さまざまなソフトウェアシステム間で通信を許可し、技術スタックに関係なく互いに通信できるようにします。これにより、開発者はアプリケーションを簡単に統合することができます。
スケール性：Web APIはモジュール型の開発をサポートしています。これにより、アプリケーションの異なるコンポーネントが独立して構築、デバッグ、スケールすることができます。これはシステムのスケール性を大幅に改善します。
柔軟性と拡張性: 標準的な做法と明确规定されたルールに従って、Web APIはアプリケーションの機能を拡張することを助けます。また、開発者が動的なアプリケーションを作成することができるほど柔軟性があります。

Web APIの開発方法

Web APIは要求に基づいて様々な方法で開発できます。以下は一般的に従っている方法のいくつかです。

REST – リpresentational State Transfer (REST) APIはHTTPプロトコルを使用して操作を行います。これはステートレスな操作を行い、各要求には受信者が処理して応答するために必要なすべての情報を含める必要があります。
SOAP – シンプル・オブジェクト・アクセス・プロトコルは構造化された方法で情報のやり取りにXMLを使用します。
GraphQLは、APIのクエリングと操作に使用される。
gRPCは、HTTP/2を使用して情報を伝達するリモートプロシードコールフレームワーク。

今後の章で、APIの設計と開発を探索し、REST APIを焦点にして議論する。

要件と目標の理解

どのソフトウェア開発プロセスにおいても、開始前に要件と意図される使用状況を理解することは重要です。これにより、プロジェクトに必要なコスト、時間、その他のリソースを計画と推測することができます。

RESTful APIの開発にも同様に適用されます。アプリケーションが状態无关の方法で情報を交換するか、関与するエンティティがリソースとして表現できるか、サービスが異なるデータ形式で作動することができるかを決定する必要があります。

リソースとエンドポイントの定義

REST APIはリソースに中心を置くものです。これらは、システム内のデータやオブジェクトを表征するエンティティです。各リソースは、リソース識別子と呼ばれるユニークなURIで識別されます。これらのリソースは、クライアントからの要求を受け取り、処理するための特定のURLであるエンドポイントを介してアクセスおよび操作されます。

ベストプracticeは、リソースのエンドポイントに名詞を使用することを推奨し、リソースに対する操作を示す動詞を使用するのではないことです。

https://api.example.com/products

このエンドポイントはリソース（この場合、products）に対する名詞を使用する最佳实践に従っています。複数形のproductsを使用していることに注意してください。複数のオブジェクトを操作している場合、複数形を使用することが推奨されます。

しかし、以下のエンドポイントhttps://api.example.com/add-productは、動詞を使用してリソースに対するアクションを描述しているため、推奨されません。このアプローチはより複雑な操作にとって厄介事になる可能性があります。

標準的なエンドポイント命名規則のもう一つの重要な要素は、階層的な構造の使用です。これによりリソース間の関係を明確に表現できます。

例えば、https://api.example.com/categories/{categoryId}/products/{productId}です。
ここで、categoryとproductリソースの間の明確な階層性を維持するエンドポイントを定義しています。

HTTPメソッドとステータスコードの使用

REST APIでは、HTTPをクライアントとサーバー間の通信に使用します。HTTPには標準のメソッドがあり、これらはリソースに対する操作を行うために主要に使用されます。以下はこれらのメソッドとその用途のリストです：

GET – リソースの詳細を取得します。これらの詳細はサーバーからの応答メッセージボディに返されます。
POST – 新しいリソースを作成します。作成するリソースの詳細はリクエストメッセージ本文に送信されます。
PUT – 利用可能であればリソースを作成または更新します。作成または更新するリソースの詳細はリクエストメッセージ本文に送信されます。
DELETE – リソースを削除します。
PATCH – リソースの一部を更新します。リソースに適用する変更はリクエストメッセージ本文に送信されます。

REST APIの開発において、リソースに対するCRUD（作成、読み取り、更新、削除）操作を適切にHTTPメソッドを使用して行う推奨方法は、これらのHTTP状態コードを使用しています。また、APIがクライアントに対して適切なHTTPステータスコードを応答メッセージ本文に返信することもしなければならないです。

ステータスコードはリクエストの最終結果を反映します。以下は使用できる一般的なHTTPステータスコードのいくつかです。

200 OK
201 Created
204 No Content
400 Bad Request
401 未授权
403 禁止
404 未找到
500 服务器内部错误
503 服务不可用
504 网关超时

API 端点正在处理请求时，请使用合适的 HTTP 状态码准确表示结果。您还可以实现自定义 HTTP 状态码以描述特定于应用程序的行为。

版本策略

随着时间的推移，您开发的 API 将不断发展并发生变化。这就是版本策略变得重要的地方。您必须确保已经使用您的 API 的客户端不会受到您所做的更改的影响。

维护不同版本将使您的 API 向后兼容，并允许客户端根据其需求使用首选的 API 版本。这篇文章摘自 Postman 网站上的一个有益的博客文章，解释了何时为您的 API 版本化是理想的：

APIを変更するたびに、APIの使用者が自分のコードベースを修正する必要が生じる変更を行った場合に、APIのバージョン管理を行うべきです。このような変更は「破壊的変更」として知られ、APIの入出力データ構造、成功とエラーのフィードバック、そして安全机制に影響を与える可能性があります。

APIのバージョン管理は様々な方法で行えます。以下はいくつかの手法です。

URI バージョン管理: URLパスにバージョン番号を含めます。たとえば、https://api.example.com/v1/productsのようにです。
クエリパラメーターバージョン管理: URLにクエリパラメーターとしてバージョン番号を指定します。たとえば、https://api.example.com/products?version=1のようにです。
ヘッダーバージョン管理: HTTP要求のヘッダーにバージョン番号を含めます。たとえば、X-API-Version: 1のようなカスタムヘッダーを使用します。
コンテント調整: リクエストのAcceptヘッダーでバージョンを指定します。通常、メディアタイプを使用します。たとえば、Accept: application/vnd.example.v1+json。
埋め込まれたバージョン管理: レスポンスのメディアタイプ内でバージョン番号を埋め込みます。たとえば、application/vnd.example.product-v1+json。

セキュリティに関する考慮

APIを開発する際に考慮する重要な侧面は、セキュリティです。以下は、覚えておくべき键となる点です。

HTTPSを実装して、クライアントとサーバー間の情報を暗号化します。
認証と認可を実装して、リソースに操作を行うには適切な権限を持つユーザーだけが可能にします。一般的な方法には、ベーシック認証、ベアーやトークン認証、JWT、およびOAuth 2.0があります。また、ロールベースのアクセスコントロールを実装して、リソースのアクセス管理を行います。
入力値の検証とサニタイジングを実装し、SQL注入やクロスサイトスクリプティング(XSS)などの脆弱性攻撃を防ぐこと.
特定の時間範囲内において、クライアントがサーバーに向けて行う要求の数を制限し、 throttling を実装します。これにより、サーバーへの過剰な負荷を防止することができます。

ドキュメント

API開発の中で、重要であるがよく見落とされる一部となる要素があります。APIについてのドキュメントを記述することは、ユーザーがAPIの機能や機能を理解することが crucial です。

ドキュメントは、よく理解できるように十分な内容を含んでおり、標準的な慣習に従っていること。要求と応答の本文の例、使用されるHTTPステータスコードなどを含めます。RESTful APIを記述するために、Open API スペックィフィケーションに従ってください。

ソート、絞り込み、および分割戦略

APIの開発には、返却するレコードが多すぎると性能問題が発生する可能性があります。大きな量のデータを取得した後でソートまたはフィルタリングすることは效率が悪いです。

これらの問題を解決するために、レコードのソートとフィルタリングを有効にし、パージングを実装して、取得するレコード数を分割し、簡単なナビゲーションや処理をするためにリミットを設定することが推奨されます。

使用状況の監視、ログ記録、および健康状况

APIの要求と返信を記録することは、デバッグを助けるのに役立つので良いアイデアです。APIの使用状況を監視することで、アプリケーションの全体のパフォーマンスと行動を理解することができます。定期的な健康状况の確認を行うことで、問題があれば必要な行動を取ることができます。これらの手順はAPIをより強固で信頼性のあるものにすることに役立てます。

結論

APIは、特にWeb APIは、ソフトウェアアプリケーションがインターネット上で通信するために不可欠です。

この記事では、Web APIとは何であり、为何重要か、そして開発の異なるアプローチについて説明し、REST APIに焦点を当てました。また、リソースとエンドポイントの定義、標準的なHTTPメソッドとステータスコードの使用、バージョニング戦略、安全性の考慮、文書化など、主要なトピックについても学びました。

この記事に興味を持った場合は、freeCodeCamp上の他の記事をご確認いただけます。また、LinkedInで私と連絡を取れます。