Web APIは、Webサービスで利用されているAPIを指しています。現在、アプリケーションやサービスの機能拡張にWeb APIがよく使われています。それでは、もしWeb APIを作りたい場合は、どうしたらいいですか？本文では、非常に詳しいガイドを皆さんに紹介します。
Web APIとは
Web APIとはその名前通りに、APIの一種になりますね。実際には、現在の業界では、Web APIに関して、厳格な定義がありません。Web APIは、HTTPというプロトコルを利用するAPIを指すこともありますし、Webサーバー、Webブラウザで利用されているAPIのみを指すこともあります。
REST APIを始め、現在Web APIはさまざまな業界で広く利用されています。
REST API
Web APIといえば、最も多くの場合はREST APIを指しています。HTTPプロトコルを使用するAPIの中で、現在REST APIは一番汎用されているAPIになります。それでは、REST APIとはなんですか？どのような特徴がありますか？次の内容を読み続けてください。
REST（Representational State Transfer）APIとは、Webアプリケーションの機能を外部のクライアントアプリケーションから利用するためのAPIの一種です。REST APIは、HTTPプロトコルを使用して通信を行い、一般的にJSONまたはXML形式でデータをやりとりします。REST APIでは、リソース（データ）を一意の識別子（URI）で指定し、HTTPメソッド（GET、POST、PUT、DELETEなど）を使用してリソースを操作します。クライアントアプリケーションはHTTPリクエストを送信し、サーバーからのHTTPレスポンスを受け取ります。これにより、Webアプリケーションの機能を外部から利用することができます。
SOAP API
SOAP（Simple Object Access Protocol）は、ウェブサービス間での情報交換を目的とした通信プロトコルです。SOAPはXML（eXtensible Markup Language）ベースのプロトコルであり、クライアントとサーバー間でメッセージをやり取りするためのルールや形式を提供します。また、SOAP APIは、異なるプラットフォームやプログラミング言語間での相互運用性を提供するために広く使用され、セキュリティやトランザクション管理などの機能もサポートできるので、信頼性の高いウェブサービス通信を実現することもできます。
XML-RPC
XML-RPC（Extensible Markup Language Remote Procedure Call）は、リモートプロシージャコール（RPC）プロトコルの一種です。XML-RPCでは、データをXML形式でエンコードするため、さまざまなプログラミング言語やプラットフォームで利用することができます。メソッドの呼び出しやデータの受け渡しにおいて、独自の通信プロトコルを実装する必要がなくなります。そのため、異なるシステム間での相互運用性を高めるのに役立ちます。
JSON-RPC
JSON-RPC（JavaScript Object Notation Remote Procedure Call）は、JSON形式を使用してリモートプロシージャコール（RPC）を行うためのプロトコルです。JSON-RPCは、JSONデータ形式が広くサポートされているため、さまざまなプログラミング言語やプラットフォームで利用することができます。また、シンプルな構造と軽量なデータサイズが特徴であり、利用しやすさと効率性を両立しています。
Web APIの現状
現在、Web APIはかなり普及されています。多くの有名な企業は、Web APIを多数公開しています。例えば：
- Google社は、Google Map、翻訳などのAPIを公開しています。
- InstagramやTwitterもそれぞれのAPIを公開しており、API経由で投稿を添削したり、管理したりすることができます。
- Notion API経由で、ワークスペースを管理したり、コンテンツを添削したりすることもできます。
- OpenAI APIを利用して、ChatGPTを自分のサービスにも統合できます。
そこで、アプリを開発するときに、必ずしも全ての機能をも自分で開発するわけではなく、これらのサードパーティのAPIを利用することで、これらのサービスを自分のアプリに連携して、自分のアプリの機能拡張を図ることができます。
shimizu chioka
Web APIの作り方：ステップずつでご紹介
それでは、Web APIを作りたい場合は、どうしたらいいですか？大まかに次のようなステップが必要となります。
プロジェクトの企画
APIを作る前に、まずは考えるべきなのは、APIでどのようなことを実現したいかということになりますね。これは、業務に深く関わることです。だから、APIの作りの前提は、プロジェクトの企画になります。次は、仮想のプロジェクトを踏まえて、APIの実用を皆さんに紹介します。
仮想プロジェクト - 「ポイントでタクシーを呼ぶ」
仮に配車サービス会社のためにAPIを設計します。この配車サービス会社は銀行Aに連携して、銀行Aのお客様は、クレジットカードのポイントを消化して、直接にタクシーを呼べるサービスを提供しようとしています。お客様に付き、3回のみ利用できます。このような機能を実現するために、APIを利用する必要があります。
上記の機能に基づいて、この配車サービスを利用する流れは次のようになります：
まずは銀行でユーザー名を持ってクレジットカードのポイントの残高を検索する必要があります。そして、当該ユーザーがサービスを利用できる回数を検索します。利用できる回数はまだ残っている場合、配車サービスで車を選択して、相応のポイントを消化します。
このプロジェクトの場合は、APIの利用状況は次のように：
- ユーザー名の取得 - 銀行のAPI
- ポイントの残高の取得 - 銀行のAPI
- 残りの利用回数の取得 - 新規開発が必要
- 車の種類と所要ポイントを取得 - 配車サービスのAPI
上記のプロジェクトのように、現在のアプリ開発中に、自分でAPIを開発する必要もありますし、他社が公開しているサードパーティのAPIを利用することもよくあります。
サードパーティAPIの利用方法
サードパーティのAPIを利用するために、常に、公式のAPIドキュメントを参照する必要があります。APIを提供している会社は、大体そのAPIの使い方を詳しく解説するドキュメントをも提供しています。これらのドキュメントでは、APIのエンドポイント、必須のパラメータ、レスポンスのサンプル、認証方法などが記載されていますので、それを参照して、簡単にサードパーティのAPIを簡単に利用できるようになります。
自分でAPIを作る方法
上記で紹介したプロジェクトのように、サービスに含まれている一部のAPIを自分で作る必要があります。この部分では、Web APIの作り方を皆さんに紹介します。Web APIを自分で作る場合は、まずはAPIを設計する必要があります。どこからAPIの作りを始めるかがわからない場合は、Apidogという完璧なAPI管理ツールを使用して、APIの作りを始めることがおすすめです。このツールの直感的なUIで、コードなしでもAPIを簡単に設計したり、開発したりすることができます。
それでは、依然として、上記のプロジェクトを例して紹介します。現在、「残りのサービス利用回数の取得」といった目的のAPIを作成したい場合は、APIの作り方を次のようになります：
ステップ⒈ APIリソースの指定
Apidogで新しいAPIの作成画面の一番上に、APIリソースを指定するボックスがあります。ここでAPIのエンドポイントとパスを入力します。
ステップ⒉HTTPメソッドの選択
APIのリソースを指定した後、HTTPメソッドを設定する必要があります。どちらのWeb APIもHTTPプロトコルを使用していますので、目的別で、HTTPメソッドを選択する必要があります。HTTPメソッドといえば、常に下記のものがあります。
- GET（コンテンツを取得）
- POST（コンテンツを新規追加）
- PUT（既存コンテンツを変更）
- DELETE（コンテンツを削除）
「残りのサービス利用回数の取得」APIの場合の設定：
情報の取得を目的としているので、HTTPメソッドを「GET」にします。
ステップ⒊APIの詳細説明を追加
ここでAPIの詳細説明を追加します。例えば、このAPIの役割、使用方法及び注意事項など、APIの取扱説明書のようなものを追加すると、利用者がより正しくこのAPIを使用できます。また、必須なRequestのパラメータも設定する必要があります。
「残りのサービス利用回数の取得」APIの場合の設定：
例えば、ユーザー名を使って利用回数を検索する場合は、「ユーザー名」は必須のパラメータになります。Requestパラメータで「パラメータ名」を「name」か「user_name」にして、タイプで「string（文字列）」にする必要があります。
ステップ⒋レスポンスの定義
そして、リクエストが成功に送信した時（HTTPステータスが200になるのは一般）のレスポンス例を追加します。このレスポンス例を追加すると、APIの利用者がリクエストの送信によって取得されたレスポンスをレスポンスの定義に比較して、自動的に正確なレスポンスを取得できるかを検証してくれます。
「残りのサービス利用回数の取得」APIの場合の設定：
例えば、ユーザー名をエンドポイントに送信すると、サーバーから返させたいデータの構造を指定することができます。もしユーザー名、残りの回数、有効期限と言った情報が必要となる場合は、レスポンスのデータ構造を次のように設定しましょう。
- name: string
- use_times:integer
- expiration:string
ステップ⒌スターテスコードの指定（RESTのみ）
一般的には、APIのリクエストを成功に送信した場合、HTTPステータスが200になるのは一般的です。それ以外のHTTPステータスはエラーになると認識されます。ただし、各Web APIの規範では、REST APIの仕様でHTTPステータスコードの設定を要件にしています。他のAPIの仕様では、HTTPステータスコードの定義を必要な要件としていません。
200以外のHTTPステータスコードは、APIのエラーコードになります。エラーコードは問題の原因を明確に示し、開発者がより早く診断し、問題を解決できる解決策とアドバイスを提供するべきです。API仕様書でよく設計されたエラーコードがあることは、APIの使いやすさと信頼性を高め、開発者は故障排除に要する時間を減らすことができます。
このようにして、新規APIを簡単に設計することができます。バックエンドとフロントエンド開発者はこの設計書に基づいて、作業を進めることができます。
サーバースタブとクライアントコードの生成
APIクライアントコードとサーバースタブは、APIを利用するアプリケーションの開発で使われる2つのコンポーネントです。
APIクライアントコードは、APIを呼び出すためのクライアント側のコードです。例えば、Web APIを利用する場合、HTTPリクエストを送信するコードがこれにあたります。ライブラリやフレームワークを利用してAPIを呼び出す場合も、そのラッパーコードがクライアントコードになります。
一方、サーバースタブは、サーバー側のAPIの仮実装コードです。本番のAPIサーバーがまだない段階で、テスト目的などでクライアントの開発を並行して進めるために用意されます。レスポンスのダミーデータを返すなど、本番と同じインターフェースでAPIの動作を模したコードが記述されます。
この2つを組み合わせることで、クライアントとサーバーの開発をある程度並行して進めることができ、開発効率が向上します。クライアント側はサーバースタブを利用してAPI呼び出しをテストでき、サーバー側はクライアントとの相互運用が事前に確認できます。
Apidogでコードを簡単に生成
上記で紹介したAPI管理ツールのApidogは、APIの定義に基づいて、さまざまなプログラミング言語/フレームワーク（TypeScript、Java、PHP、Go、Swift、ObjectiveC、Kotlin、Dart、C++、C#、Rustなど）のコード（Model、Controller、単体テストコードなど）とAPI Requestコードを自動的に生成できます。現在、Apidogは130 個の言語とフレームワークのコードの自動生成をサポートしています。
ステップ⒈APIのページで、「コード生成」ボタンにガーソルを置くと、「クライアントコードを生成」か「サーバースタブとクライアントSDKを生成」を選択します。
ステップ⒉生成したいプログラミング言語/フレームワークを選択して、コードを生成します。
ご案内：サーバースタブとクライアントSDKを生成するには、「JAVA環境」と「Apidogのコードジェレーたプラグイン」をインストールする必要があります。これらのツールがインストールされていない場合、コード生成ページで、画面上の指示に従って、インストールしてください。
