誰でもわかるAPI:APIについて学ぶ

3 min read
API for dummies

アプリケーションプログラミングインターフェース(API)は、異なるソフトウェアコンポーネントが互いに通信できるようにするための標準およびプロトコルを定義します。これにより、アプリケーションは、独立したシステムからデータやアクションを要求できます。

APIはどこにでもあります。使用するデバイスやソフトウェアとのすべてのインタラクションは、事実上、APIにより支えられています。例えば、スマートフォンのアプリはAPIを使ってサーバーからデータを取得し、iOSとAndroidが提供する別個のAPIを使用してデータを画面に表示したり、プッシュ通知で送信したり、連絡先と共有したりします。

APIには非常に多くの形式があるため、それらがどのように組み合わされているかを理解しようとすると混乱するかもしれません。APIにはどのような種類があるのでしょうか?どのような場合にAPIとして認められるのでしょうか?独自のものを作るにはどうすればよいですか?この包括的なガイドで、これらすべての疑問に対する答えを学べます。

APIとは何か?

アプリケーションプログラミングインターフェースという用語は難解に思えるかもしれませんが、これは特定の概念を指す言葉です。最も単純に言えば、APIとは開発者がアプリケーションで動作するコードをプログラムできるようにするものです。これは、相互運用性を促進するインターフェイス、あるいは2つ以上のシステムが遵守しなければならない規則、手順、期待、標準を定めています。

この点を、例を挙げて探ってみましょう。新規ユーザーを登録するためのAPIを公開するIDプラットフォームについて考えます。外部アプリケーションは、APIを使用してオンデマンドでユーザーを作成できますが、これが機能するためには、データはプラットフォームが期待する形式でなければなりません。

このAPIは、次の要件を定めています。クライアントアプリケーションがexample.com/usersにHTTP POSTリクエストを行う必要があること、NameEmailPasswordデータフィールドを含める必要があること、および新しいユーザーのIDを含むJSONボディがレスポンスとして発行されることです。この情報を使用すると、開発者はAPIを使って新規ユーザーを正常に登録できます。

基本的にAPIとは、開発者が呼び出すことのできるプラットフォームコードと、その使い方を説明するドキュメントの組み合わせです。

APIが重要な理由

APIはシステム間のデータフローを可能にします。これにより、他のアプリケーションの上にソフトウェアを構築することができるため、より強力なソリューションを生み出すことができます。

APIは自動化にも欠かせません。異なるAPIの機能を1つのアプリケーションに統合することで、アクションやイベントの発生に合わせてデータをシステム間で移動できます。開発者は数行のコードを書くだけで、従来なら骨の折れる手作業によるプログラミングが必要だった複雑なプロセスを実装できるのです。

例えば、ウェブスクレイピングは複雑なタスクです。効果的なウェブスクレイパーを実装するには、開発者はウェブブラウザのインスタンスを制御し、ジオロケーションプロキシを設定し、CAPTCHAを回避する洗練されたロジックを作成する必要があります。APIを選択することで、これらの機能すべてに数回のネットワークリクエストでアクセスできます。その後、他のAPIを使用して、スクレイピングされたデータを操作および分析して、チャットプラットフォームのチームメンバーに結果を送信できます。

加えて、APIはビジネス資産でもあります。他のツールと簡単に統合できるようにすることで、プラットフォームは顧客にとってより魅力的になります。外部の開発者は、各パーツの総和を上回る独自のソリューションを自由に構築できます。

APIは、今日のハイパーコネクテッドなプロセスにとって極めて重要です。当たり前のように使われている数多くのテクノロジーは、複雑なAPIのウェブによって支えられています。例えば、オンラインショッピングには、通常、複数の独立したベンダーによってホストされている支払い回収、配送リクエスト、および電子メール配信APIが含まれます。

APIの種類

個々のAPIは、所属するサービスに合わせてさまざまな機能を提供します。たとえば、ID管理ソリューションは、検索エンジンスクレイピングプロバイダーとは大きく異なるAPI機能を提供します。

とはいえ、一見無関係に見えるAPIの技術的特徴は、しばしば非常に類似しています。ほとんどの一般的なAPIで使用される標準の数は一握りに過ぎず、それらがソフトウェア業界がシステムを統合する上で有効であると判断した技術を表現しています。

では、APIにどんな種類があるのか見てみましょう。

#REST

REST(Representational State Transfer)は、2000年に初めてRoy Fieldingによって理論化され、現在ではほとんどのウェブサービスで使用されています。

RESTは、システムのデータをHTTP URLにマッピングされたステートレスなリソースとして表現します。HTTPメソッド(GETPOSTPUTDELETE)は、リソースを取得し、それらに対してアクションを実行するために使用されます。

例えば、example.com/users/100へのGETリクエストは、ID 100のユーザーに関する以下の情報を返します。


{
    "Id": 100,
    "Name": "Example User",
    "Email": "[email protected]"
}

その後、同じURLにDELETEリクエストを発行すると、サービスによりオブジェクトが破棄されます。

RESTが人気なのは、実装が簡単で、HTTPの上に構築されており、現実世界のアプリケーションの多くがデータを扱う方法を効果的にモデル化しているからです。多くのシステムとのやりとりは、動詞(DELETE)と名詞(user)の組み合わせであることが多く、このアーキテクチャはRESTによって直接表現できます。

#SOAP

RESTとは異なり、SOAP(Simple Object Access Protocol)はデータ共有のための正式な仕様です。REST APIはJSON、XML、CSV、またはプラットフォーム固有の代替手段を提供することがあるのに対し、すべてのSOAP交換でXMLデータ形式が使用されます。単純なSOAP APIコールで、次のようなレスポンスを生成できます。

xml
<?xml version="1.0" ?>
<soap:Envelope
   	 xmlns:soap="https://www.w3.org/2003/05/soap-envelope/"
   	 soap:encodingStyle="https://www.w3.org/2003/05/soap-encoding">
   	 <soap:Body>
   		 <m:GetUserResponse>
   			 <m:Id>100</m:Id>
   			 <m:Name>Example User</m:Name>
   			 <m:Email>[email protected]</m:Email>
   		 </m:GetUserResponse>
   	 </soap:Body>
</soap:Envelope>

XMLを使用し、プロトコル固有の属性を含めることで、SOAPは典型的なREST APIよりも冗長になります。ただし、SOAPの標準化には利点があり、だからこそ多くの大企業や商用システムで採用されているのです。APIで利用可能な操作は、XMLスキーマによって明示的に定義されています。これらが各リクエストとレスポンスの構造とデータタイプを記述することで、クライアントとサーバーのミスマッチが起こるリスクを減らします。

#GraphQL

GraphQLは、操作可能なAPIを構築するための比較的新しい技術です。これは2012年にFacebookで開発され、2015年に公開されました。

GraphQLは、RESTやSOAP APIの抱える課題のいくつかを解決するために設計されています。これは、クライアントがAPIからデータを抽出する際に使用できる表現力豊かな言語を提供することで、複雑なクエリを簡略化します。GraphQLを使用すると、常にオブジェクト全体を扱う代わりに、必要な特定のデータフィールドだけを取り出すことができます。これにより、冗長なデータを無駄に転送するのを防ぐことができます。

以下は、ユーザーのメールアドレスを取得する簡単なGraphQLクエリーです。

{
    user {
   	 Email
    }
}

このクエリーは次のレスポンスを生成します。

json
{
    "user": {
   	 "Email": "[email protected]"
    }
}

GraphQLが人気を集めているのは、データの小さな部分が複数の異なるコンポーネントによって独立してフェッチされる、今日の高度に接続されたアプリケーションにより適した、より汎用性の高いオプションだからです。ただし、GraphQLの実装は比較的複雑であるため、言語固有のプログラミングツールを使って処理するのが最善です

#RPC

RPC(リモートプロシージャコール)は、シンプルな形式のAPIです。これは、あたかもローカルで利用可能であるかのようにリモート関数を呼び出す手法です。基本的なネットワークリクエストにより、APIサーバーはタスクを実行し、結果を提供します。クライアントがネットワーク通信の詳細を知ることはありません。

RPC APIは関数型プログラミングインターフェースに似ています。example.com/deleteUser?User=100のように、呼び出すURLに動詞と名詞の両方が含まれます。これは、特定の名詞に動詞を適用する(DELETE example.com/users/100)RESTとは対照的です。RESTはデータ構造をモデル化しようとするのに対し、RPCはより直接的にコードにマッピングします。

RPCは、クライアントにとってもサーバーにとっても使い方が簡単です。これは、さまざまなリクエストパラメータを受け付け、それらに応答してデータを送信するURLのコレクションです。ただし、標準化されていないため、開発者にとってこれらのAPIを探索するのは難しい傾向があります。ほとんどのREST APIのエンドポイントは、サービスのリソース名が分かれば予想できるのに対し、RPCに使用されるURLは各プラットフォームに固有のものになります。

RPCの改良は、gRPCのような最新のプロジェクトによって行われています。これは複数のプログラミング言語で動作するフレームワークで、構造化データをシリアル化するGoogleの高効率手法であるプロトコルバッファを使ってクライアントと通信するRPC APIサービスを素早く定義するために使用できます。

システムAPI

REST、SOAP、GraphQL、RPC APIは、システム間のネットワーク通信のコンテキストで使用されます。その他のAPIは、アプリケーションがデバイスの機能にアクセスするためのシステムインターフェースなど、さまざまな種類の統合用です。

これらのAPIは、Windows、Android、iOSなどのオペレーティングシステムにより提供されます。これらはプログラミングフレームワークやSDKによって公開されており、開発者は自分のコードから呼び出すことができます。システムAPIを使用すると、プログラマーは低レベルのコードを書くことなく、通知、ランチャーアイコン、メディア再生、デバイスセンサーアクセスなどの機能に簡単にアクセスできます。

プログラミング言語API

同様に、プログラミング言語や依存関係にも独自のAPIがあります。言語の標準ライブラリに含まれるモジュールは、APIを表しています。プロジェクトにインストールするサードパーティパッケージもAPIであり、作成されたコンポーネントは定義されたインターフェースを使って接続されます。

APIは、いつでも変更可能なシステムの内部動作と、インテグレータが依存する安定した外部インターフェースとを区別するものです。コードベースでpublicとマークされたメソッドや関数により作成されるAPIは、他のコードから利用可能です。

同期APIと非同期API


APIには同期型と非同期型があります。同期APIは要求された操作の結果を即座に返しますが、非同期APIはデータ交換が完了した後も実行を継続する可能性があります。

データ収集APIの場合、現在収集されているデータを要求することは、常に現在までに取得されたデータを返す同期タスクになります。新しいデータ収集スクレイピングのリクエストは、プロセスが完了するまでに長い時間がかかる可能性があるため、非同期の可能性があります。APIは、収集がスケジュールされたことをクライアントに通知した直後に通信を終了する方が効率的です。

詳しく見る:APIの仕組み


一般的なAPIタイプにはそれぞれ独自の文法があります。例えば、RESTは目的語と動詞で動作しますが、GraphQLはサーバー中心ではなくクライアント中心の、より汎用性の高いソリューションを提供します。この2つのオプションについて、もう少し詳しく見てみましょう。

# REST

RESTは、HTTPメソッドの動詞を使ってリソースに対してアクションを実行します。最も一般的なメソッドはGETPOSTPUTDELETE

GET /users/100は、ユーザー100のIDを返します。

POST /usersは、新しいユーザーを作成します。

PUT /users/100は、ユーザーをIDで更新します。

DELETE /users/100は、ユーザーをIDで削除します。

これは、基本的なREST構文を示しています。URLは、対話処理する目的語のIDと、そのインスタンスである複数形の名詞を提供します。クライアントの使用するHTTPメソッドにより、実行されるアクションが決まります。

アクションが完了するために追加のデータを必要とする場合、HTTPリクエストのペイロードとして供給されます。ます例えば、POST /usersでユーザーを作成する場合、ボディには割り当てるユーザー名とパスワードが含まれます。

APIは、各リクエストに対し、その結果を示すHTTPステータスコードで応答します。例えば、GET /users/100に対する404 Not Foundのレスポンスは、ユーザーID 100が存在しないことを示し、DELETE /users/100に対する202 Acceptedは、ユーザーが正常に削除されたことを意味します。

#GraphQL

一方、GraphQLはAPIに対するアプローチが異なります。これは、[“APIのためのクエリー言語”](https://graphql.org)として提供されており、より高度な機能をサポートしていることを示唆しています。RESTは不要なオブジェクトのプロパティを含めることで帯域幅を浪費することがよくありますが、GraphQLでは欲しいデータを正確に求めることができます。

GraphQLを使用するAPIはサービスとして作成され、クライアントが呼び出すことのできるエンドポイントを定義します。サービスは、エンティティ向けの型決めされたスキーマです。スキーマの各フィールドには特定のデータ型が割り当てられています。

type Team {
    id: ID
    name: String
}

type User {
    id: ID
    name: String
    email: String
    team: Team
}

クエリーを使用してスキーマからデータを取得できます。

{
    user(id: 100) {
   	 email,
   	 team {
   		 name
   	 }
    }
}

このクエリー例では、次のデータを返すことが可能です。

{
    "email": "[email protected]",
    "team": "Example Team"
}

クエリー内のフィールドは、リゾルバによりバッキングされます。クエリが実行されると、リゾルバは各フィールドの値を生成する責任を負います。前の例では、teamリゾルバは、オブジェクト全体を返す代わりに、要求されたユーザーに割り当てられたチームからnameプロパティを抽出します。

GraphQLはまた、ミューテーションを使ってデータを更新する一貫した方法も提供します。ミューテーションはクエリーに似ていますが、サーバー上で状態変化を引き起こします。ミューテーションは、サービス内の各フィールドの関数を定義することで実装されます。この関数は、フィールドに新しい値を保存する役割を担います。

通常、GraphQL APIは、GraphQLクライアントライブラリをプロジェクトに追加することで作成されます。これらのツールを使用すると、既存のORMモデルやその他のコードからGraphQLスキーマを簡単に生成できます。

APIを統合する方法

API統合とは、ソフトウェアシステム内でAPIを採用するプロセスを指します。APIはすぐに使える関数を提供していますが、プロジェクト内でそれらを使用するには、やはりいくつかのカスタムコードを記述する必要があります。

典型的なAPI統合には、以下のステップが含まれます。

1.利用可能なオプションを評価する:まず、ユースケースを解決するさまざまなAPIを評価し、製品に最適なものを特定する必要があります。これには、ドキュメントの品質はどうか、APIを利用している活発なコミュニティがあるか、メンテナがサポートリクエストやセキュリティ問題、バグ修正レポートにどの程度迅速に対応するか、などが含まれます。

2.サービスにサインアップし、APIキーをリクエストする:一部のAPIは一般に公開され、認証を必要としませんが、ほとんどのAPIは、使用量に関するいくつかの基本的しきい値を超えると、サインアップしてAPIキーを取得する必要があります。APIキーは機密性の高い値として扱い、安全に保管します。プロジェクトのコードにハードコードしないでください。このキーは、サービスに対してユーザーを認証し、レート制限と使用状況追跡の目的でアプリケーションを識別します。

3.プログラミング言語用のAPIクライアントライブラリを探す:プログラミング言語のHTTPライブラリを使って直接ネットワークリクエストを行うことで、APIを統合できます。ただし、多くのAPIベンダーは、より便利なプログラミング言語を提供するために、APIをラップアラウンドするクライアントライブラリやSDKも提供しています。クライアントライブラリが利用可能な場合は、その使用を選択することで実装がさらに簡素化され、基盤となるAPIの互換性を破る変更を防ぐことができます。

4.コードを書く:ライブラリを特定したら、いよいよAPIとやりとりするコードを記述します。取得したAPIキーで使用するライブラリを構成する必要があります。データセンターの地域や望ましい応答形式など、サービスに必要な構成パラメータをコード内で設定する必要があるかもしれません。

5.API統合をテストする:最後に、統合をテストして、期待通りに動作することを確認します。テストには、エラー処理ルーチン(APIが利用できない場合など)のチェックを含めてください。これにより、サービスがオフラインのときでもアプリケーションの回復力を確保できます。

また、APIを統合することによるセキュリティへの影響を考慮することも重要です。サードパーティのAPIを使用すれば主要な開発タスクを簡略化できますが、ユーザーデータを外部サービスに送信するときは慎重であってください。そのプラットフォームは、自社のプラットフォームと同じセキュリティ基準を満たすことができるでしょうか?APIの機能を簡単に複製できるのであれば、アプリケーション内に独自の実装を構築する方が安全な場合があります。

実際のAPI例

APIを使う準備はできていますか?ウェブAPIを素早く試したい場合は、curlwgetなど、すでにお使いのマシンにあるHTTPツールを使用できます。グラフィカルなインターフェースを好むのであれば、Postmanが適しています。

Fakerで偽データを取得する

Faker APIプロジェクトは、さまざまなテーマについてランダムに生成されたデータを返す、人気のあるAPIコレクションです。Faker APIは、実際のバックエンドが利用可能になる前にインターフェースに入力するために、製品開発中によく使用されます。

Faker APIはRESTの原則を採用しており、URLの末尾にある名詞で生成するデータの種類を定義します。

$ curl https://fakerapi.it/api/v1/books?_quantity=1
{
	"status": "OK",
	"code": 200,
	"total": 1,
	"data": [
    	{
        	"id": 1,
        	"title": "Duck and a pair of.",
        	"author": "Jessyca McKenzie",
        	"genre": "Sit",
        	"description": "ALL RETURNED FROM HIM TO YOU,\"' said Alice. 'I wonder how many miles I've fallen by this time, as it can be,' said the Cat. '--so long as I used--and I don't take this child away with me,' thought.",
        	"isbn": "9796054956226",
        	"image": "http://placeimg.com/480/640/any",
        	"published": "2010-09-14",
        	"publisher": "Quod Enim"
    	}
	]
}

Bright Dataで検索エンジンのリスティングをスクレイピングする

Bright Dataは、SERP APIプロキシAPIの包括的なスイートを提供しています。これは、以下で登録する必要がある商用プラットフォームです。

Bright Data SERP APIランディングページのスクリーンショット

使い始めるには、無料トライアルにサインアップし、ドキュメントに従ってアカウントにSERP APIを追加します。次に、APIの詳細オプションで非同期モードを有効にする必要があります。

プロキシのスクレイピングインフラ
プロキシのスクレイピングインフラ

APIを有効にした後、POSTリクエストを送信して検索エンジンの結果を収集できます。

$ curl -i "https://brightdata.com/api/serp/req?customer={CUSTOMER_ID}&zone={CUSTOMER_ZONE}" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer {API_TOKEN}" \
    -d '{"country":"us","query":{"q":"apis"}}'
...
x-response-id: s3wt2t...

アカウント設定でAPIトークンを生成し、コマンド内でそれを`{API_TOKEN}`と置き換えます。

Bright DataでAPIトークンを生成する

お使いのアカウントの他のプレースホルダー、{CUSTOMER_ID}{CUSTOMER_ZONE}のそれぞれの値は、SERP APIプレイグラウンドで見つけることができます。

このクエリ例では、このAPIを使用してapisの米国Google検索をスケジュールします。コマンドの出力に表示されているx-response-idレスポンスヘッダーの値をコピーします。この値を使用して、SERPの結果を生成後に取得できます。しばらく待ってから、次のリクエストを発行します。

$ curl "https://brightdata.com/api/serp/get_result?customer={CUSTOMER_ID}&zone={CUSTOMER_ZONE}&output=json&response_id={RESPONSE_ID}"

RESPONSE_IDを前回コピーした値に置き換えます。検索によって生成されたデータは、コンソールに表示されます。

これらのエンドポイントは、RPC APIの一例です。APIがRESTfulの場合、URLは、

POST /api/serp/requestおよびGET /api/serp/results/{RESPONSE_ID}のようになります。

まとめ

APIとは、異なるソフトウェアコンポーネント同士を確実に接続するために使用できる、明確に定義されたインターフェースのことです。ただし、APIの構成要素には、非常に多くの異なる形式、バリエーション、ユースケースがあるため、混乱を招きがちです。

一般に、APIとは、他のコードによって実装された関数にアクセスするために、コードが使用でき、また使用すべきメカニズムです。APIはリモートシステムの開発者によってサポートされており、使用方法が文書化されています。これにより、サービスとAPIを使用するクライアントアプリケーションとの間の契約が作成されます。クライアントが期待される形式でデータを送信すれば、予測可能な構造を持つレスポンスを得ることが保証されます。

APIは、システム内の特殊な機能の実装を簡略化します。難しい仕事は当該部門の専門家に任せ、ユーザーは自分のコードに彼らのプラットフォームをプラグインできます。Bright DataのSERP APIとプロキシAPIのスイートを使って、ウェブスクレイピングタスクを実行してみてください。