APIについての入門：ソフトウェア工学でAPIを理解・活用する初めての読本

FacebookやHashnode、dev.to、LinkedInなどのお気に入りのアプリにアカウントを持っていると思いますか？私も贵方の注意を引いていますが、素早く考え始めたでしょう。また、WakaNowのフライトアプリを通じて世界中の最安の料金を得るのが簡単だったこと、また足場のファンはリアルタイムのスコアをアクセスできるということを考えたこともあります。

これらすべては、自身としてのシステムと他のシステムとのコミュニケーションを通じてこれらのデータを取得するか、詳細を確認するための手段であるAPIを通じて行われています。

この記事では、APIの概念を説明し、APIsの種類とその动作方法について明確で适当な理解を深めることができます。

APIは「アプリケーションプログラムインターフェース」の略で、システムや技術が情報やデータを共有することで自分たちと通信するためのツールです。さらに説明すると、システムが共有を行うためのプロトコルや標準に従ってお互いに通信することができるレイヤーとしても表現できます。

APIsは重要である理由は、システムや技術がお互いに交流し、データや機能を共有し、強力で効率的なシステムを一緒に作ることができるからです。さらに、APIsは開発者に対して、特定の任务を行うためにアプリケーションを合わせる超能力を与えます。たとえば、ファッションブログはFlutterwave APIを統合し、客に対して設計またはセミナーの支払いを許可し、Googleアカウントを使用して、それに関連付けられたどのアプリケーションにもログインすることができます。

APIsは、第三者からデータを取得し、情報を交換するために使用されます。これにより、ソフトウェアエンジニアとして、疯狂なことができます。

このアナロジーを使い、大学で勉強することがあります。试験を受けることと、結果を基に好みの教育機関への申し込みを行うプロセスを追っていく必要があります。直接的に入学担当者に申し込みの手続きを行う必要はありません。代わりに、彼らのポータルを訪れ、詳細を入力し、証明書をアップロードします。入学を待っている間、後端で様々なことが行われていますが、その内容は知らないでもよいです。要求が満たされると、受け取ることができます。

このプロセス全体は以下のようなものです。学校の入学事務所と通信を取りたいけれど、直接 Admission Officeにアクセスできないので、API層を使用します。このシーンでは、学校のポータルをEndpointと呼んでいます。各Endpointにはそれぞれのプロトコルがあり、必要な結果を期待することができます。この例では、学校のポータルは、入学事務所の複雑な内部を遮蔽しています。

もし登録ポートャルがなかったとしてみてください。その場合、あなたは大学の入学事務局に行って詳細を提出する必要がありました。これは時間がかかり、誤りが出る可能性がありました。

インターネットを介して二つのソフトウェア应用プログラムを接続するには、クライアントとしての一つのプログラムは、他のアプリケーションのAPIに要求を送信します。クライアントは、アプリのデータベースからリソースを要求するか、サーバーでアクションを実行する要求をします。

クライアントの要求を受信し、検証する後、APIは意図したアクションを取り行い、クライアントに対して応答を返します。この応答には、要求の状態（完了または拒否）と、クライアントが要求したリソースが含まれます。

図1. APIの動作

約4種類の異なるAPIがあり、それらについて説明します。

公的APIの例をいくつか挙げます; Bitquery, Adoptapet, covalenthq。

個人用APIまたは内部APIは、開発者やその開発を行った個人だけがアクセスできるAPIです。所有者からの招待を受けた場でのみアクセスできます。

個人用APIの例には、

  1. Twilioのプログラム可能な音声API

  2. StripeのコネクトAPI

  3. Google Mapsの企业用の個人的なAPI

  4. SalesforceのメタデータAPI

  5. GitHubのGitHub Enterprise API

企業や組織によるアプリケーションプログラミングインターフェース（API）は、外部の開発者やパートナーが彼らのサービス、データ、またはプラットフォームと通信や交互において使うことを許可するものであり、パートナーAPIとして知られ、第三者APIや開発者APIとも呼ばれる。これらのAPIは、異なるシステム、プログラム、またはサービスを統合することを簡素化するために使用されることを意図している。

企業や組織は、製品やサービスの有用性を拡大し、外部の開発者や企業との協力を促進したいと望む場合に、通常パートナーAPIsを提供する。これらのAPIを通じて、パートナーは、企業のデータ、機能、または技術を利用して、プログラム、ツール、またはサービスを作成することができる。

パートナーAPIのいくつかの例を挙げます；

  1. パートナー用Twitter API

  2. Spotify for Developers API

  3. パートナー用Dropbox API

  4. eBay Developers Program API

  5. Amazon Product Advertising API

コンポジットAPIsは、複数の下位APIsやサービスの情報や機能を統合し、单一のインターフェースに集めるAPIsであり、またはアグリゲーションAPIs、マッシュアップAPIsとも呼ばれます。これらのAPIsは、開発者が单一のAPIを通じて異なるサービスにアクセスし、交流することで、統合プロセスを簡素化し、複数のデータ源を一つのビューにまとめることができます。

プログラマーが多くの源から連続的に情報を受信するか、複数の行動を実行する必要がある場合、コンポジットAPIは役立ちます。コンポジットAPIを使用することで、データのアクセスや、複数のサービスに対して個別のクエリを送信する代わりに、单一のリクエストを送信して、多くのサービスを横断してアクションを実行することができます。統合プロセスを最適化し、複雑さを減少させ、効率を向上させます。

以下は、複数の天気サービス提供者からの天気データを集積したコンポジットAPIの例です:

  1. WeatherAPI

  2. OpenWeatherMap API

  3. Weatherbit API

これら多くのサプライヤーからの天気データを集積し、開発者に统一した天気データインターフェースを提供するために、コンポジットAPIを作成することができます。これにより、開発者は单一のAPIリクエストだけで、多くの源からの天気情報を取得することができます。

Web APIは、私たちの日々の活動のほとんどがウェブに関係しているため、最も一般的に使用されています。Web APIは、異なるブラウザー之间でも同じように機能することができる標準であり、これは通信の両側を指します。Web APIは、一般的にはアプリケーションプログラミングインターフェース（APIs）と呼ばれています。これらは、ウェブサービスやアプリから提供されるインターフェースで、それらと他のソフトウェアプログラム之间的オンライン通信と相互作用を可能にします。開発者は、Web APIを通じて、特定の機能、サービス、またはデータにアクセスすることができます。

1. RESTful API

RESTful APIは、表征性状态変更アプリケーションプログラミングインターフェースの略称で、REST（表征性状态変更）アーキテクチャの設計原則に従って、ウェブ上でコンピュータ間の通信を行う標準の一族です。

REST APIの一部に包括する

  1. 要求 —–→ 応答

  2. 操作 – GET、POST、PATCH、UPDATE、DELETE

  3. エンドポイント – Url

  4. パラメーター/ボディ

  5. ヘッダー

図2 REST APIの Diagram

RESTの主要な原則は以下の通りです。

  1. クライアント-サーバーアーキテクチャ：RESTはクライアントとサーバーのコンポーネントを分離し、独立して進化させることができます。クライアントはサーバーにリクエストを送信し、サーバーはこれらのリクエストを処理し、レスポンスを送信します。

  2. 状態无关性：RESTは状態无关性を持っており、これはクライアントからサーバーに向けた各リクエストには理解し、処理するために必要なすべての情報を含める必要があることを意味します。サーバーはリクエスト間でクライアントのコンテキストを記憶しておらず、スケーラビリティの簡略化とキャッシングの改善を可能にします。

  3. ユニークインターフェース：RESTは標準的なHTTPメソッド like GET、POST、PUT、およびDELETEを使用して、统一されたセットのインターフェースと操作を促進します。RESTfulシステム内の各リソースは、URL（统一リソースアドレス）によって唯一識別されます。

  4. リソース基: RESTはすべてをリソースとして捉えます。データエンティティ、サービス、またはコレクションなどです。各リソースにはユニークな識別子があり、標準的なHTTPメソッドを使用してアクセスや操作できます。

  5. リソースの表現: RESTでは、JSON (JavaScript Object Notation)やXML (eXtensible Markup Language)などの特定の形式を使用してリソースを表現します。サーバーはリソースの表現をクライアントに返信し、これにはデータ、メタデータ、またはハイパメディアリンクが含まれることができます。

  6. ステートレスのインタラクション: クライアントからサーバーに送信される各要求は独立しており、サーバー上の前の要求または状態に依存しません。これにより、スケーラビリティが良くなります。なぜなら、サーバーはクライアントのセッション情報を維持する必要がないからです。

REST APIの利点

  1. 単純で標準化されている

  2. スケーラブルでステートレス

  3. 高性能でキャッシュ可能

2. SOAP API

SOAPはSimple Object Access Protocolの略で、SOAP Web Service Specificationに従っているWebサービスです。XMLを格式とし、定義されたスキーマとユーザー標準のプロトコルを使用している人気のメッセージングプロトコルです。これはWorld Wide Web Consortiumに定義されています。SOAPプロトコルは、HTTP、SMTP、TCP/IPなど幅広いインターネット通信プロトコルをカバーしています。

図3 SOAP API Diagram

SOAP APIの利点

  1. 言語、プラットフォーム、トランスポートは独立しています。

  2. 分散型企業環境で良く機能します。

  3. WS*標準による既に構築された拡張性を提供します。

  4. 組み込まれたエラー処理です。

  1. RPCです。

遠隔プロセデュラルコール（RPC）プロトコルは、複数のパラメーターを送信して結果を受信する手段です。これは、ローカルマシンに存在しない远隔関数呼び出しで、呼び出し元の場所からデプロイされる必要があります。非同期性として、応答を取得することで成功と判定される必要があります。これはクライアントとサーバーの間の直接なやり取りとなります。RPC APIは、操作またはプロシージャーの実行を引き起こす操作を行います。RPCはJSONとXMLの2つの異なる言語を使用することができます。

図4 RPCプロトコル

  1. GraphQL API

GraphQLは、APIに対するクエリ言語であり、クライアントが特定のデータを要求し、応答を必要な形に整形することができます。

GraphQL APIのいくつかの例

GitHub GraphQL API、Shopify GraphQL API、SpaceX GraphQL API、Yelp GraphQL API、Twitter GraphQL API（Twitter API v2）。

APIプロトコルの比較

REST

SOAP

RPC

GraphQL

XML、JSON、HTTPとプレーンテキストで作動します

設計上XMLとも関連しています

ユーザーがプロシージャー名を知る必要があります

HTTPとも作動します

データとも适しています

プロセス（アクション）とも适しています

特定のパラメーターと順序が必要です

控えめな安全性があります

高度な安全性があります

ドキュメントはハイパーメディアを通じて补完することができます

開発者にとって最も難しいです

详しいドキュメントが必要です

要求方法はGET、PUT、DELETE、PATCH、UPDATEです。

要求方法はPOSTです

要求方法はPOSTです

要求方法はPOSTです

A. エンドポイント

APIのエンドポイントは、通信チャンネルの1点または端点です。APIが他のシステムとやりとりする際に、この通信の接触点はエンドポイントと呼ばれます。字面で言えば、APIsがリソースを送信し、リソースが離れる場所がエンドポイントと呼ばれます。APIsにおいて、エンドポイントは、サーバー上のリソースの場所を提供するUniform Resource Locator（URL)であることが一般的です。

エンドポイントの例は以下の通りです

Twitter API エンドポイントの例

Twitter APIは、ツイート、ダイレクトメッセージ、ユーザーなどのデータを公開しています。

例えば、特定のツイートの内容を取得したいときには、ツイートの検索エンドポイントを使用することができます。これは、api.twitter.com/2/tweets{id}のURLに対しています(ここで{id}はツイートのユニークな識別子です)。

B. リクエストとレスポンス

APIリクエストは、クライアントからサーバーに向かって送られるメッセージです。APIリクエストは、データにアクセスするか修正する、あるいは特定のアクションを実行するためにAPIに向けた要求です。APIレスポンスは、APIリクエストに対する返信として返されるデータや情報です。

たとえば、ユーザーが以下のハイパーリンクをクリックすると、

<a href=’http://localhost:2400/categories/01/flavours ’>

flavour categoryにあるすべてのflavourを表示

</a>

となります。HTTPリクエストメッセージは以下のように送信されます。

GET /categories/01/flavours HTTP/1.1

Host: localhost:2400

User-Agent: Chrome/5.0 [compatible, Windows 10]

API request

1. Copy codeGET https://api.com/categories/flavours

API response

1. Copy codeHTTP/1.1 200 OK

2. Content-Type: application/json

3.

4. {

5. "id": 01,

6. "flavours": "Chocolate"

7. }

We can see from this request that the Endpoint is URL – /categories/01/flavours.

The Request method is GET, the HTTP Specification is 1.1, the domain is localhost, the port is 2400, Flavours is the resource, and the user-agent provides the browser and operating system.

C. HTTP Methods (GET, POST, PUT, DELETE)

APIs that utilize the HTTP protocol use HTTP request methods (also known as “HTTP verbs”) for transmitting client requests to servers. The most commonly used HTTP request methods are GET, POST, PUT, and DELETE.

  1. GET is used by a client to fetch data from a server,

  2. PUTは既存のデータを置き換えたり、存在しない場合に新しいデータを作成します。

  3. POSTは主に新しいリソースを作成するために使用されます。

  4. PATCHを使用してリソースからデータの一部を更新するために使用し、

  5. DELETEはクライアントによって指定されたサーバー上のデータやリソースを削除します。

D. API セキュリティ – 認証と認可

この2つの用語は似ているかもしれませんが、2つの異なる機能を持っています。認証はユーザーや身份の確認に関連し、認可はユーザーが持つアクセスや行動に対する許可に関連します。これらは API セキュリティの核心であり、認証と認可のために人気のある方法は OAuth 2.0 です。

認可の異なる形

認可の方法はいくつかあります。以下はおそらく遭遇することのできるAPI認可の様々なタイプです:

E. APIキーとトークン

APIキーは、クライアントアプリの識別と認可を提供するテキストの文字列です。つまり、APIサーバーに対してコールを行うアプリケーションを識別し、コールを行うアプリケーションがAPIサーバーへのアクセスを認可されたかどうかを判断するために使用されます。すべての活動を追跡し、不正な行為をブロックするために使用されます。

APIキー認証は、HTTP基本的認証の主要な問題である共有ログイン情報の欠如を解決するために作られました。これは2つの目的に使用できます。第1のステップは、バックエンドAPIに対してコールを行うクライアントアプリを识別することです。第2のステップは、呼び出しアプリケーションがAPIに呼び出す権限があるかどうかを決定するクライアントアプリの認可です。

APIキーは、webアプリケーション上で管理されるAPIキープロバイダから取得されます。

APIキーをどこに保存するか

APIキーをコードやファイルに埋め込むのは避けてください。GitHubにプッシュすると公になってしまう可能性があります。代わりに、APIキーを環境変数に保存してください。

APIキーの例は以下のようになります。

key: a9nIbdnaoks97028Jlf.ains9NIKQMEO

APIにアクセスするための安全な証明書であるアクセストークンは、認証と認可を行います。トークンは、APIにアクセスを許可されるトークン所持者に固有の証明書です。

以下はJSON Web Token(JWT)の例です:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

これは、ヘッダー、ペイロード、署名を三点で区切ったJWTです。ヘッダーは、署名に使用されるアルゴリズムなどのトークンに関する情報を通常含みます。例えば:

{

"alg": "HS256",

"typ": "JWT"

}

ペイロードは、实体（ユーザー、クライアントなど）に関する声明を含み、的主体、発行者、有効期限、カスタムデータなどの情報を含むことができます。たとえば:

{

"sub": "1234567890",

"name": "John Doe",

"iat": 1516239022

}

署名は、エンコードされたヘッダー、ペイロード、そして秘密鍵を取り出し、HMAC-SHA256などの暗号的なアルゴリズムを適用します。署名は、トークンの完全性和正当性を保証します。

このJWTを使用する場合、クライアントはAPI要求の認可ヘッダーにこれを含めます。例えばこのように:

認可: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

APIサーバーは、それによってトークンの真实性を確認し、有効期限をチェックし、有効な情報を含むペイロードを使用して認可や他の目的に使用することができます。

ここで提供された例のトークンは、説明のためにのみ使用し、生産環境で使用するべきではありません。

トークンと鍵は認証と認可にどちらも使われますが、以下のように異なります。

API鍵は通常、APIにアクセスする際にクライアントやアプリケーションの识別と認証に使用されます。彼らは主に長い、乱数によって生成された文字列として証明書として機能します。トークンは、認証手続きが成功した後に認可されたクライアントやユーザーに与えられ、認証の証明として機能します。

ライフスパン: API提供者によって意図的に破棄されるか、回転されるまでは、API鍵は一般的に長い期間を持ちます。トークンは、一般的に短いライフスパンを持ち、有効期限日を持っています。認証技術に応じて、クライアントは古いトークンが期限切れになった後、再認証またはリフレッシュトークンを使用して新しいトークンを取得する必要があります。

安全性：トークンはAPIキーと比較してより良い安全性の機能を提供します。トークンは制限されたスコープや権限を持つことができ、詳細なアクセスコントロールを実現します。また、トークンは暗号化、署名、または追加のCLAIMSを含むことができ、完整性和正しさを提供します。これにより安全的な認証を行い、機密情報の保護が向上します。

A. 天気API

天気API（Application Programming Interfaceの略）は、実時間で天気データと予報を提供するサービスです。

例として

. WeatherAPI.com, Forecast, Meteostatがあります。

B. ソーシャルメディアAPI

ソーシャルネットワークAPIは、これらのプラットフォームが他のソフトウェアプロバイダーやアプリと統合することを可能にします。

例として

C. 支払いゲートウェイ API

ソフトウェア開発者がアプリやウェブサイトに支払いゲートウェイサービスを組み込むための技術的インターフェースを支払いゲートウェイ APIと呼びます。

例えば

Stripe APIは、高く評価されているサービスで、販売者に在线で決済を受け入れることができます。Noodlio Pay、Square API、PayPal、Adyen、Paybook、KeyPay、BIPSの請求書（Coinifyを通じて）。

D. マッピングと地図情報API

地図情報APIは、何も保管しませんが、問い合わせられている装置から既存のデータを集めることができます。IPアドレス、GPS、Wi-Fi、Bluetooth、RFID、GSM/CDMA ID、および人間の入力から、異なる源から位置情報を集めることができます。

地理定位APIMapbox APIOpenStreetMap APIMapQuest APIHERE API

IV. 結論 と 学び

この文章では、APIのことが何であり、どのように機能し、実際の例があり、APISecurity、HTTP方法、APIの重要性について説明されました。APIがソフトウェアエンジニアによって、作成されているものにアプリケーションを統合し、それに改善することができることが明らかになりました。調査と書き込みの過程で、APIのセキュリティが大きな問題であることを発見しました。APIがハックされると、それに接続しているすべてのアプリケーションに影響を与えますので、API Securityについてさらに調査することにします。

最終的に、これに関連した別の記事を発表します。これは、APIの探求、APIとのコード内の作業、APIの最良の慣例、APIの設計と開発に関するものです。

A. いくつかのキーワード

API – アプリケーションユーザーインターフェース

RPC – リモートプロシーダルコール

HTTP – ハイパーテキスト転送プロトコル

B. 学習の次の手順

最終的に、私はこれについて別の記事を発表することにしました。これは、APIの探求、APIとのコード内の作業、APIの最善の慣習、APIの設計と開発に関するものになります。

Source:
https://nechey.hashnode.dev/introduction-to-apis-a-beginners-guide-to-understanding-and-utilising-apis-in-software-engineering