Web APIとは? 〜ワイメールをもっと便利に使うために〜

本日もメール配信システム「ワイメール」の公式コラムをご覧いただきありがとうございます。

ワイメールではお客様からのご要望にお応えし、先日公開したVersion 2.26において、一部の機能についてWeb APIの提供を開始いたしました。

APIの利用には比較的専門的なWebの知識が必要となるため、社内SEの方などがご対応いただくケースがほとんどかと思いますが、一般の方にもAPIの機能をある程度ご理解いただけるよう、APIの基本的な流れについて、簡単に解説いたします。

Web APIって何だろう?

Web API(Application Programming Interface)は、コンピュータプログラム同士が情報をやり取りする手段の一つです。簡単に言えば、異なるプログラム同士がコミュニケーションをとるための取っ掛かりとなるものです。

異なるプログラム同士がコミュニケーションをとる必要性は、様々な状況で発生します。例えば、Webアプリケーションが天気情報を表示する場合、その情報を提供しているサービス(API)とWebアプリケーションが連携する必要があります。

APIはどのように動いている?

APIは、情報をリクエスト(要求)するサーバ、データを提供するサーバ、その情報を必要とするクライアントから構成されます。クライアントは、APIにリクエストを送り、サーバはそのリクエストに対して応答(レスポンス)を返します。

出典:Programing Life Style(2024),「WEB API」って何?WEBサービス開発に役立つ「WEB API」を使えるようになろう!, https://www.pgls-kl.com/article/article_48.html

APIエンドポイントとは?

APIを使うにあたりよく耳にするのが、エンドポイントという言葉です。エンドポイントとは、APIが提供する特定の機能やデータにアクセスするためのアドレスのようなものです。

例えば、天気情報APIのエンドポイントは「/weather」などとなります。またワイメールのAPIでは、指定した読者情報を得るエンドポイントは「/api/rest/v1/get-user」となります。

これを使って、クライアントは特定の情報を要求します。

GETやPOSTって何?

APIとやり取りする際に使用されるのが、HTTPメソッドと呼ばれるものです。代表的なものには、GET(データの取得)、POST(データの送信)、PUT(データの更新)、DELETE(データの削除)などがあります。これらのメソッドを使い分けることで、APIは適切な処理を行います。

リクエストとレスポンス

APIのやり取りは、リクエスト(要求)とレスポンス(応答)のサイクルで成り立っています。クライアントがAPIに対してリクエストを送り、それに対してサーバが適切なデータや処理結果をレスポンスとして返します。これによって、情報のやり取りが行われます。

どうやってAPIを使うの?

APIを利用するためには、まずそのAPIのリファレンス(仕様書)を確認する必要があります。

リファレンスには、APIのエンドポイント、サポートされているHTTPメソッド、必要となる認証情報などが記載されています。これを基に、顧客(ワイメールご利用のお客様)や開発者はAPIを利用することができます。

ワイメールでは以下においてAPIリファレンスを公開しておりますので、APIご利用前には必ずお読みいただけますようお願いいたします。

ヘルプ:APIリファレンスはありますか?

なお当リファレンスは、ある程度Webアプリケーション開発の知識・経験がある方を前提として書かれております。用語の意味やAPI開発の手順などに関するお問合せにはご回答いたしかねる場合がございますので、あらかじめご了承ください。

APIの認証

APIを利用する際には、特定のクライアントのみリクエストを送れるように、セキュリティのための認証が行われます。これには、トークンやAPIキーを用いて認証が行われます。

ワイメールでは、APIの利用にあたり、管理者権限でコントロールパネルにログインし、認証のためのクレデンシャル(API Key ID, API Secret Key のペア)を作成する必要があります。詳しくは上記のリファレンス、またはコントロールパネルのマニュアルをご参照ください。

リクエストの送信とレスポンスの受け取り

レファレンスの情報に基づいてリクエストデータを組み立て、エンドポイントにリクエストを送信します。認証情報が通り、リクエストデータに不備が無ければ、サーバから何らかのレスポンスが返却されます。

データ整形と利用

APIのレスポンスで得られるデータは、ほとんどの場合、JSONやXMLなど、特定のマークアップ言語で構成されています。(ワイメールではJSON形式を採用しています。)

このレスポンスデータを、任意のJSON用パーサーモジュール(JSON形式のデータを連想配列などに格納するモジュール)などで変数化することで、プログラムの任意の場所で利用することができます。

最後に

APIは、異なるプログラム同士が協力して機能するための重要な仕組みです。本コラムで触れた基本的な概念を理解することで、日常的なWebサービスやアプリケーションがどのように情報をやり取りしているのか、少し身近な感じがするかもしれませんね。

今後は、ワイメールのAPIのより実用的な活用方法などについて、適宜書いていければと思います。引き続きワイメールをよろしくお願い申し上げます。

免責事項

当コラムの内容は、コラム執筆時点での内容です。今後のバージョンアップ等により、仕様やインターフェイスが変更になる場合がございます。