成功したAPIを作成する5つのステップ

それがソフトウェア開発の性質です。 開発者は、エンドユーザーを念頭に置いてソフトウェアを作成します。 とても簡単に思えますが、それらのユーザーは仲間の開発者でもある場合があります。 彼らは物事を分解する必要はありません。 彼らは単純ささえ必要としません。 彼らが望むのはアクセスだけです-あなたのソフトウェアを彼らのものと統合する方法です。 ここで、API（アプリケーションプログラミングインターフェイス）が登場します。

宿題をする

ソフトウェア開発に関して言えば、誰も車輪を再発明することを望みません。 この時点で、ほとんどすべての大規模なWeb企業がソフトウェア製品用のAPIを持っています。 これらのAPIを研究し、それらのAPIを作成する際のさまざまな設計上の決定事項を取り上げてみてください。

さまざまなテクノロジーがありますが、表示されるAPIのほとんどは、RESTfulインターフェースまたはSOAPを使用する予定です。 使用するAPIインターフェースがわからない場合は、HTTPプロトコルを使用したRESTfulアプローチをお勧めします。 これはSOAPよりも単純で、現在はより人気があり、Webベースのソフトウェア製品を使用する場合に使いやすくなります。

一貫性を保つ

開発者が最も高く評価するものの1つは、一貫性です。 これには、とりわけ、アドレス指定可能性、入力引数、出力形式、エラー処理が含まれます。

RESTfulアプローチを使用する場合、さまざまなURI命名スキームがあります。 それぞれにサポーターがいるので、1つだけを選んで固執してください。 入力および出力構造についても同じことが言えます。 ほとんどのAPIは、XMLおよびJSONを入力および出力形式として使用することをサポートしています。 両方をサポートすることをお勧めしますが、デフォルトの形式を選択します。

入力の場合、入力要件には一貫した名前を付け、作成しているAPI呼び出しのコンテキストで意味を持たせる必要があります。 出力については、共通のデータ構造レイアウトを使用していることを確認してください。 1つのAPI呼び出しの出力を XMLタグ、他の呼び出しでそれを行うことを検討してください。

クライアントに送り返す出力データにある種のステータスフラグを含めることは一般的な方法です。 RESTful APIアプローチを使用する場合、これはHTTPステータスコードを使用して実行する必要があります。 たとえば、既存のデータオブジェクトでPUTリクエストを処理したばかりの場合、レスポンスに含めるHTTPステータスコードは、リクエストの結果によって異なります。

コールのステータスを示す任意のフラグの代わりに、標準の「200 OK」ステータスコードを使用してリクエストが成功したことを示すことができますが、「400 Bad Request」ステータスコードを使用してリクエストがあったことを示すことができます奇形。 さまざまな状況で使用できるHTTPステータスコードはかなりあります。

OAuthを使用する

ほとんどのソフトウェア製品は、そのユーザーの保護されたリソースにアクセスするために、何らかのユーザー認証を必要とします。 APIに関しては、クライアントにユーザー資格情報を収集してサーバーに送信させるのは悪い習慣です。 これがOAuthの出番です。

OAuthには、サードパーティのユーザー名/パスワード認証よりも多くの利点があります。 とりわけ、クライアントはユーザーの資格情報にアクセスできません。 ユーザーはログイン時にサーバーにリダイレクトされます。ユーザーがサイトにログインした後、ユーザーはクライアントにリダイレクトされ、クライアントは保護されたリソースへの今後のリクエストで使用するアクセストークンを受け取ります。

OAuthを使用するもう1つの重要な利点は、ユーザーがいつでもクライアントアクセスをキャンセルできることです。 ユーザーが、何らかの理由でクライアントが保護されたリソースにアクセスできるようにしたくないと判断した場合、ユーザーは作成したインターフェイスに移動し、クライアントのアクセスをキャンセルします。

早めに開始

APIを成功させるためにできる最も重要なことの1つは、早期に開始することです。 データベースにエントリを作成するためにその関数を作成する場合、先に進み、余分な時間をかけてAPIインターフェイスを記述します。

適切なドキュメントを書く

優れたドキュメントがないことほど、APIを速く殺すものはありません。 一部の開発者は、文書化が不十分なAPIを使用して、それがどのように機能するかを把握できますが、ほとんどの人はそうしたくないでしょう。

使用可能なすべてのAPI呼び出しを文書化し、それらが動作するデータのタイプ別にAPI呼び出しを分類する必要があります。 API呼び出し自体のエンドポイントを文書化するとともに、必要な入力引数とオプションの入力引数、および出力データ構造を体系的に定義する必要があります。 入力引数は、デフォルト値がある場合はデフォルト値をリストし、数値や文字列などの予想されるデータ形式も示す必要があります。 最後に、すべてのAPI呼び出しには、エラー条件とステータスコードのリストが必要です。

ドキュメントを完成させるには、各API呼び出しの一般的な入力および出力シナリオの1つまたは2つの例を必ず含めてください。

API開発：シンプルに保つ

APIの開発は複雑な作業のように思えるかもしれませんが、API自体のアイデアは新しい概念ではなく、ここで触れた各トピックに関する大量のドキュメントが用意されています。 それらを見つけることができる場所で良い方法を使用し、一貫した、十分に文書化されたインターフェースを提供するようにしてください。