APIについて

はじめに

知識不足を感じたAPI部分について、再度学んでいきます！

API

（Application Programming Interface）
ソフトウェアインターフェースの一種である。

そもそもインターフェースとは？
コンピュータ用語でいうと、「何か」と「何か」を繋ぐものという意味をもっている。
橋渡しのような役割！

UIでたとえると・・・
コンピュータとそれを使用する人間側を結びつける役割を指している（パソコンと人間の仲介役）

• CUI（例えば、WindowsのコマンドプロンプトやLinux、MacOSのターミナルなど）
• GUI（例えば、WindowsやMacOSのデスクトップ環境、スマートフォンのアプリケーションなど）
• タッチパネル

APIとは・・・
『ソフトウェアインターフェース』とは、ソフトウェア同士の間で、データのやりとりをする際の形式を定めたもの。
APIは何かと何かが、「アプリケーション」と「プログラムを繋ぐもの」という意味！

APIはアプリケーションなどの一部を外部に向けて公開することにより
第三者が開発したソフトウェアと機能を共有したりすることが可能になります。

APIでできること

データの共有

APIを介して、ソフトウェアは他のソフトウェアとデータをやり取りできます。

機能の使用

APIを通じて、あるソフトウェアは他のソフトウェアの機能を使用できます。
例）ウェブサイトが地図表示のためにGoogle Maps APIを使用する、など。

サービスの統合

APIを通じて、異なるサービスを一つのアプリケーションで統合できます。
例）天気予報APIと地図APIを組み合わせて、特定の場所の天気情報を地図上に表示するアプリケーションを作成することができます。

APIのメリット

ソフトウェア開発の効率化によるコスト削減

新たなアプリケーション開発に際してコードを再利用することができるので、開発者は既存の機能をゼロから作り直す必要がなくなり、開発時間とリソースを大幅に節約できます。

セキュリティの向上

大手SNSページや会員登録じ、Google/Facebook/Twitterなどのアカウントを連携することでユーザー登録できるケースがある。
自社でセキュリティレベルの高い会員登録システムを入れるよりも、すでにあるセキュリティレベルの会員システムを導入する方がユーザーも安心！ユーザーも新たにユーザー登録をしなくても良い！

最新情報を簡単に取得できる

APIを使えば、こちら側から最新情報を毎回更新しなくても、取得・利用することができる！
例えば、自分のサイトでAmazonの商品を売っている場合、Amazonの販売価格が変わった場合でも、API連携で情報を取得してきている場合は、その変更は自動で反映される！

APIのデメリット

依存性

APIを使用すると、そのAPIを提供するサービスの変更や中断に影響を受ける可能性があります。例えば、APIが更新された場合、既存のアプリケーションが互換性を失い、修正が必要になることがあります。

セキュリティリスク

APIはデータを共有するための通路であるため、不適切に管理された場合、
悪意のある第三者によるデータ漏洩のリスクが存在します。

パフォーマンス

APIを介してデータを取得する場合、ネットワークの遅延やAPIサーバーの遅延により
パフォーマンスが影響を受ける可能性があります。

APIを利用して他のシステムと連携する一般的なフロー

以下の例では、Web API（具体的には、RESTful API）を使用したケースを考えてみました。

Web APIとは、HTTPプロトコルを通じてアクセス可能なAPIのこと。
RESTful APIはWeb APIの一種で、RESTという設計原則に従ったAPIを指す。

1. APIドキュメンテーションの確認
2. APIキーの取得
3. リクエストの作成
4. リクエストの送信
5. レスポンスの解析
6. データの使用・テスト

ただし、RESTful APIには一部の限界もあります。
例えば、リアルタイムの通信にはWebSocketなどの技術を使用する必要がありますし、
複雑なトランザクションを処理する場合にはGraphQLなどの技術が適しているかもしれません。
☝️
ここはまた後日勉強したい！

APIドキュメンテーションの確認

まず最初に、どのようなAPIが提供されていて、どのようにそれを利用するのか理解するために、APIのドキュメンテーションを確認します。

ドキュメンテーションには、使用できるエンドポイント、それぞれのエンドポイントが何を行うのか、リクエストとレスポンスの形式、必要な認証の情報などが含まれている！はず。

APIではどのような形でデータが受け取られるか。

• APIの設計によりますが、最も一般的な形式はJSON（JavaScript Object Notation）です。
  軽量で人間にも機械にも読みやすい形式であり、多くのプログラミング言語がサポートしています。

{
    "users": [
        {
            "id": 1,
            "name": "John Doe",
            "email": "[e-mail]"
        },
        {
            "id": 2,
            "name": "Jane Doe",
            "email": "[e-mail]"
        }
    ]
}

• 上記の例では、"users"キーの配下に複数のユーザーの情報（ID、名前、Eメール）が
  リストとして格納されています。

• XML（eXtensible Markup Language）という形式を提供しているAPIもあります。
  これはJSONよりも古い形式で、特に企業の内部システム間通信や、特定の業界（金融業界など）でよく使用されます。

<users>
    <user>
        <id>1</id>
        <name>John Doe</name>
        <email>[e-mail]</email>
    </user>
    <user>
        <id>2</id>
        <name>Jane Doe</name>
        <email>[e-mail]</email>
    </user>
</users>

• これらの形式（JSONやXML）は、データを階層的かつ構造的に表現するため、
  複雑なデータ構造も効率よく表現できます。

どの形式を使用するかはAPIのドキュメンテーションを確認することでわかります。
また、いくつかのAPIでは、リクエストのヘッダーによってレスポンスの形式（JSONかXMLか）を指定することが可能です🤔

エンドポイントとは

エンドポイントとは、APIにおける特定のURL（通信の終点）のことを指します！

このエンドポイントを介して、クライアントはAPIからデータをリクエストしたり、APIにデータを送信したりします。

エンドポイントは通常、リソースや特定の操作に対応しています。
例えば、ユーザー情報に関するAPIでは、以下のようなエンドポイントがあるかもしれません。

• GET /users：すべてのユーザーの情報を取得する
• GET /users/{id}：特定のIDを持つユーザーの情報を取得する
• POST /users：新しいユーザーを作成する
• PUT /users/{id}：特定のIDを持つユーザーの情報を更新する
• DELETE /users/{id}：特定のIDを持つユーザーを削除する

/usersや/users/{id}がエンドポイントになります。
APIのエンドポイントとその機能は、APIのドキュメンテーションに詳しく記載されています。

エンドポイントの設計には様々な考え方がありますが、
RESTful APIと呼ばれる設計スタイルでは、上記のようにリソースを中心に設計します。

これにより、直感的なエンドポイントの設計と一貫性のあるインターフェースが可能になります。

リクエストとレスポンスの形式、認証情報

リクエストの形式

HTTPリクエストは通常、以下の要素から構成されます!

• HTTPメソッド： 操作の種類を示します（GET、POST、PUT、DELETEなど）。

• URL： APIエンドポイントを指定します。

• ヘッダー： 追加情報（例えば、認証情報、コンテンツタイプなど）を含みます。

• ボディ： POSTやPUTリクエストの場合に送信するデータを含みます。

POST /api/v1/users HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer your-token
{
    "name": "John Doe",
    "email": "[e-mail]"
}

レスポンスの形式

HTTPレスポンスは通常、以下の要素から構成されます!

• ステータスコード： レスポンスの状態を示します（200、201、404、500など）。

• ヘッダー： 追加情報（例えば、コンテンツタイプなど）を含みます。

• ボディ： 応答データを含みます。

HTTP/1.1 201 Created
Content-Type: application/json
{
    "id": 123,
    "name": "John Doe",
    "email": "[e-mail]"
}

認証情報

APIを利用するためには、多くの場合、認証情報が必要となります!

この認証情報は、APIが提供者により提供されるトークン（例えば、OAuthトークンやAPIキー）をリクエストヘッダーに含める形で提供されます。これにより、APIはリクエストが認証されたものであることを確認できます。

上記のリクエスト例では、"Authorization: Bearer your-token"というヘッダーが認証情報として含まれています。この"your-token"部分には、実際にはAPIから提供されたトークンが入ります。

具体的なリクエストやレスポンスの形式、認証方法は、使用するAPIのドキュメンテーションにより異なります。それぞれのAPIのドキュメンテーションを確認し、適切に利用することが重要です!

APIキーの取得

APIを使用するためには、通常、APIキーが必要です。
APIキーは、リクエストが認証済みであることを証明し、API利用者を特定するためのものです。
APIキーは、APIを提供するシステムのダッシュボードや設定画面などから取得します。

リクエストの作成

APIエンドポイントに対するHTTPリクエストを作成します。
リクエストには、使用するHTTPメソッド（GET、POST、PUT、DELETEなど）、
エンドポイントのURL、必要に応じてリクエストボディ（POSTやPUTの場合）、そしてAPIキーが含まれます。

リクエストの送信

作成したリクエストをAPIエンドポイントに対して送信します。
これには、HTTPクライアントライブラリやコマンドラインツール（curlなど）、
あるいは開発者向けのツール（Postmanなど）を使用します。

レスポンスの解析

APIエンドポイントからのレスポンスを受け取り、その内容を解析します。
レスポンスは通常、JSONまたはXML形式で、成功またはエラーの情報、
リクエストに対するデータなどが含まれます。

データの使用

最後に、レスポンスデータを自身のアプリケーションで必要な形で使用します。
適切なリクエストが送信され、期待通りのレスポンスが得られていることを確認します。

デプロイと監視

開発が終わったら本番環境にデプロイします。
その後もエラーの監視や性能のモニタリングを行い、問題があれば修正します。

APIを叩くって？

APIを使用して、特定のサービスやシステムに対して情報の取得や操作を行うことを意味します。

一般的には、Web APIを通じて外部サービスからデータを取得したり、そのサービスを操作したりする行為を指すことが多いです。

具体的な例を挙げると、以下のようなシナリオが考えられます。

• 天気情報の取得: ある天気予報サービスが提供しているAPIを叩くことで、指定した地域の天気情報を取得する。

• SNSの投稿: SNSサービスのAPIを叩くことで、プログラム上から自動的に投稿を行う。

• データベースの更新: システム内部のAPIを叩いて、データベースの情報を更新する。

「叩く」という言葉は、非公式な表現であり、この表現は、APIのエンドポイントに対してHTTPリクエストを送る、という動作を比喩的に示しています。

APIを叩くときの一般的な手順

• エンドポイントの特定: どのURLにリクエストを送るのかを特定します。
• HTTPメソッドの選択: GET（データの取得）、POST（データの送信）、PUT（データの更新）、DELETE（データの削除）など、適切なHTTPメソッドを選択します。
• リクエストの送信: エンドポイントに対してHTTPリクエストを送ります。
• レスポンスの受取: APIからのレスポンス（通常はJSON形式など）を受け取り、その内容を解析・利用します。

API連携時の注意点

認証とセキュリティ

APIキーはセンシティブな情報であり、第三者に漏洩しないよう適切な管理が必要です！
また、APIを通じて送受信されるデータもまた機密性を保つべき情報であることが多いため、HTTPSなどの安全な接続を通じて転送されるべきです。

レートリミット

多くのAPIは、一定時間内に許可されるリクエストの数（レートリミット）を制限しています。
この制限を超えると一時的にAPIの利用が制限されることがあります。
そのため、アプリケーションの設計時にはこの点を考慮し、必要に応じて適切なリクエスト制御のロジックを実装することが必要です。

APIの変更

APIは提供者により予告なく変更されることがあります。
バージョンアップや仕様変更により、一度動作していたコードが突然動かなくなることもあります。APIを定期的にチェックし、提供者からの通知を適時受け取るようにすることが重要です。

エラーハンドリング

APIの呼び出しはネットワーク接続や外部システムに依存するため、さまざまな理由で失敗する可能性があります。そのため、エラーハンドリングを適切に行い、例えばタイムアウトやサーバーエラーが発生した場合の対処方法を実装しておく必要があります。

パフォーマンス

大量のAPIリクエストを行うと、ネットワークの遅延がアプリケーションのパフォーマンスに影響を与える可能性があります。可能な限りAPIの呼び出しを効率的に行うために、バッチ処理、キャッシング、非同期処理などのテクニックを利用することを検討すると良い。

APIの種類

大きく分けて以下のような種類がある！

Web API	HTTPを通じてアクセスされるAPI。通常は、クライアントとサーバー間でデータのやりとりを行うために使用されます。多くのWeb APIはRESTやGraphQLなどの規則に従って設計されています。
ライブラリー・フレームワークのAPI	プログラミング言語が提供するライブラリーやフレームワークは、開発者が特定の機能を利用するためのAPI。例えば、Javaの標準ライブラリやPythonのNumPyライブラリ、フロントエンドフレームワークのReactなど。
Operating System API	ソフトウェアがハードウェアリソースやOS自体の機能（ファイルシステムやネットワーク接続など）にアクセスするために使用される。例えば、MicrosoftのWindows APIやAppleのCocoaなど。
Database API	データの読み書きを行うためのAPI。SQLクエリを発行するためのAPIやNoSQLデータベースのためのAPIなどがある。
Hardware API	ソフトウェアが特定のハードウェア機能にアクセスするために使用される。例えば、プリンター、カメラ、GPUなどのハードウェアデバイスの制御に使用。
WebサービスAPI	SOAP、REST、XML-RPC、JSON-RPCなどのプロトコルを使用して、ネットワークを介して他のソフトウェアと通信するためのAPI。

これらのAPIは互いに排他的なものではなく、
多くの場合、一つのアプリケーションやシステムは複数の種類のAPIを組み合わせて使用します！

PFに機能追加してみる

実際に連動してみました！

https://cloud.google.com/?hl=ja

環境変数わすれずに！

<script src="http://maps.google.com/maps/api/js?key=<%= ENV['GOOGLE_MAP_API_KEY'] %>&language=ja"></script>