読み方｜API仕様書をどのように読み解く？
すべてのITエンジニアは、仕事中にAPIを取り扱う必要がある場合、API仕様書を読み解くことが必要なことになります。本文では、API仕様書を完全に読み解く方法を詳しく紹介します。
すべてのITエンジニアは、仕事中にAPIを取り扱う必要があると思います。APIを取り扱っている場合、API仕様書を読んで、APIの使い方を理解する必要があります。なので、IT領域のエンジニアにとって、API仕様書の読解能力は非常に必要な技能になります。それでは、どうやってAPI仕様書を効率的に読んで、APIの使い方を理解すればいいですか？本文では、それについて詳しく説明していきます。
API仕様書とは？
総じて言えば、API仕様書とは、APIの取扱説明書のことになります。API仕様書でAPIを利用する具体的な手順が記載されています。例えば、API仕様書は、APIのリクエストの送信に必要な通信方式やパラメータを記述し、どのようなレスポンスが返されるということも明確にしています。適切に設計されたAPIドキュメント（API仕様書）は、一般的には以下の要素を含みます。
- APIの概要（APIが何に使われるかを説明する）
- リクエストのプロトコルの定義（APIの使い方を説明する）
- エンドポイント（具体的なURLとパス）
- APIのメソッド
- リクエストのパラメーター
- レスポンスの例（APIの結果として返されるものを説明する）
- ステータスコード上記のようなAPI仕様書の要素とその構造に基づいて、次の部分では、具体的なAPIを例にして、API仕様書の具体的な読み方を皆さんに紹介しようと思います。
読み方：API仕様書を読み解く方法
本文では、非常に優れていたAPI管理ツールのApidog上のサンプルプロジェクトを例にして、API仕様書の中の各要素を読んで理解する方法を皆さんに紹介します。
APIの概要の説明（APIが何に使われるかを説明する）
APIの概要は、「このAPIは何のために開発するの？」ということを説明する部分です。開発者は、APIの概要を通じて、このAPIの機能と役割を了解するので、APIの概要の説明は、API仕様書の不可欠な部分になると言っても過言ではありません。
リクエストのプロトコルの定義（APIの使い方を説明する）
リクエストのプロトコルの本質は、インターネットの通信プロトコルであり、各サービス間のデータ転送とコミュニケーション方式を標準化するものです。APIでは、一般的なリクエストプロトコルはHTTP、HTTPS、FTPです。リクエストプロトコルは、各APIが送受信できる基礎になり、同じ仕様やルールに従う場合のみ、コミュニケーションが成り立ちます。
HTTP
HTTP (HyperText Transfer Protocol) は、Webサイトをブラウザーに表示するために使用されるプロトコルで、データはサーバーとクライアント間で暗号化されずに転送されます。HTTPは、Webサイトの表示やデータの送受信に使用されますが、通信内容が暗号化されないため、データの改ざんや盗聴のリスクがあります。
HTTPS
HTTPS (HyperText Transfer Protocol Secure) は、HTTPのセキュリティバージョンであり、暗号化された通信を提供します。HTTPSは、SSL（Secure Socket Layer）またはTLS（Transport Layer Security）プロトコルを使用して、Webサイトの通信内容を暗号化します。これにより、ユーザーが送信するデータが保護され、データの改ざんや盗聴のリスクを軽減できます。
FTP
FTP (File Transfer Protocol) は、インターネット上でファイルを転送するために使用されるプロトコルです。FTPは、ユーザーがWebサイトからファイルをダウンロードするために使用されることがあります。FTPは、ファイル転送に特化しており、HTTPやHTTPSのようなWebサイトの表示には使用されません。FTPは、通信内容が暗号化されず、パスワードなどの情報が平文で送信されるため、セキュリティ上のリスクがあります。しかし、FTPには暗号化機能があるため、暗号化を有効にすることでセキュリティを強化することができます。
エンドポイント（具体的なURLとパス）
コンビニに行って何かを買いに行く場合、そのコンビニの位置を事前に知っておく必要があります。その同様に、エンドポイントは、どこかでサービスを見つけるのかを伝えるための要素です。よく見られるエンドポイントはドメイン、またはIPアドレスになります。
APIのメソッド
どのような方式でAPIの機能を使用するのかを定義するものです。一般的によく使われるAPIメソッドは：GET（コンテンツを取得）、POST（コンテンツを新規追加）、PUT（既存コンテンツを変更）、DELETE（コンテンツを削除）です。
リクエストのパラメーター
APIの使い方は、実際に電卓の使い方に似ています。同じく何かのデータを入力すると、結果が出力されるという流れです。ここで電卓に入力するデータは、APIのリクエストのパラメータになります。例えば、電卓のAPIを使用して、１＋１の結果を計算したい場合、この１＋１はリクエストのパラメータになります。
一般的には、入力するエンドポイントのURLで、？以降のものはすべてパラメータになります。また、＆という記号で違うパラメータを区別します。
例えば、下記画像のように、「https://www.google.com/search?keyword=api使い方&userid=9988&source=organic」というエンドポイントをAPI管理ツールのApidogに入力する場合、?以降の「?keyword=api使い方&userid=9988&source=organic」が自動的にパラメータとして抽出されます。
レスポンスの例（APIの結果として返されるものを説明する）
APIドキュメントを参照してリクエストを送信する場合、受信の方がそのリクエストを成功に受信して正確なレスポンスを返すことができるのかを判断するには、どうしたらいいですか？ここでレスポンスの例を定義する必要があります。レスポンスの例を定義することは、利用者はAPIの使い方、パラメータのフォーマットをより深く理解することに役立ちます。
ステータスコード
ステータスコードはAPI利用者がResponseをいち早く判断するために利用されます。ステータスコードはAPIが正確に機能しない時によく使われ、電話の不在着信の自動返答のテンプレートのようなものです。
ステータスコードは3桁の数字で、最初の数字は応答カテゴリーを表し、後ろの2桁の数字はカスタムコードで、Responseの状態を具体的に表現できます。例えば、200はリクエストが成功したこと、404はリクエストされたページが存在しないことなどです。ステータスコードはAPI仕様書の重要な一部分として、開発者が自分のアプリをよりよくデバッグし、テストするのに役立ちます。
API仕様書を作成する最適なツール
Apidogは、APIの設計、開発、デバッグ、テストなどを一体化にした総合プラットフォームです。ApidogのUIが非常に直感的で使いやすいので、コーディングの知識がなくても、簡単にAPI仕様書を作成することができます。ApidogのAPI設計機能を利用することで、画面上の指示に従って各の項目を入力すると、非常に分かりやすく綺麗なAPI仕様書を生成することができます。そして、生成後の仕様書を強力な共有機能で、楽々にチームメンバーに共有することもできるので、非常に便利です！
