API仕様書とは？その書き方は？｜Apidog
API仕様書でAPIを利用する具体的な手順を定義するドキュメントです。分かりやすいAPI仕様書があると、API利用者のユーザーエクスペリエンスが大幅に向上されます。本文では、API仕様書を詳しく紹介した上、その書き方も詳しく説明します。
API仕様書とは？
APIはApplication Programming Interfaceの略として、ソフトやアプリが事前設定されたルールとプロトコルを通じて、異なるシステム間でデータを通信したり、交換したりできるようにする仕組みです。API仕様書とは、APIの取扱説明書のことになります。API仕様書でAPIを利用する具体的な手順が記載されています。例えば、API仕様書は、APIのリクエストの送信に必要な通信方式やパラメータを記述し、どのようなレスポンスが返されるということも明確にしています。
API仕様書の書き方とは？
API及びAPI仕様書はどのようなことを知った上、API仕様書の書き方を皆さんに紹介していきます。開発者が読んですぐ分かるAPI仕様書には、次のような要素が含まれていることが必要です。
- APIのメソッドとパスを設定
- APIの詳細を詳しく説明
- APIケースを設定
- APIのエラーコードを設定
- バージョンのコントロール機能を利用
上記は、API仕様書のコアとなる要素です。次は、この五つのステップを詳しく説明していきますので、誰でも次の詳細ガイドを参照して、簡単に分かりやすいAPI仕様書を作成することができます。
API仕様書を作成する最適なツール
Apidogは、APIの設計、開発、デバッグ、テストなどを一体化にした総合プラットフォームです。ApidogのUIが非常に直感的で使いやすいので、コーディングの知識がなくても、簡単にAPI仕様書を作成することができます。ApidogのAPI設計機能を利用することで、画面上の指示に従って各の項目を入力すると、非常に分かりやすく綺麗なAPI仕様書を生成することができます。
そして、生成後の仕様書を強力な共有機能で、楽々にチームメンバーに共有することもできるので、非常に便利です！
API仕様書のサンプル
それでは、Apidogを利用して自動生成したAPI仕様書はどのようになりますか？次は、Apidogが生成してくれたAPI仕様書のサンプルになります。
ApidogでAPI仕様書を分かりやすく作成する
Apidogを使用すると、自らAPI仕様書を作成する必要がなく、必要となるパラメータなどを入力するだけで、非常に綺麗で読みやすい仕様書を生成することができます。それでは、Apidogを使用して、次のステップを参照して、完璧なAPI仕様書を作成しましょう。
オンラインオプション：API仕様書をオンラインで生成
また、Apidogはブラウザアプリをも提供しているので、デスクトップアプリをダウンロードしてインストールすることなく、Apidogのアカウントに無料登録すると、オンラインで仕様書を生成することもできます。
アカウント登録が必要となる理由：ユーザーがクロスプラットフォームで作業データを利用するために、AWS経由でデータを同期したりすることがあります。アカウントに登録すると、他のデバイスでデータにアクセスすることもできますし、他のチームメンバーにデータを快適に共有することもできます。
データのセキュリティ確保：Apidogはユーザーのデータ、及びプライバシーのセキュリティを固く保護しています。ユーザーデータはすべて安定したAWSサーバーに保管しており、Apidogでもユーザーデータにアクセスすることができません。Apidogは、お客様の情報の機密性・完全性・可用性の3つをバランスよく管理することを保証します。
ステップ⒈Apidogのホームページで「無料登録」ボタンをクリックします。
ステップ⒉登録用ページで、Apidogアカウントに無料で登録します。
ステップ⒊登録が終わると、ブラウザが自動的にオンラインアプリのページにリダイレクトします。
ブラウザアプリはデスクトップアプリの機能は完全に同じになっています。デスクトップアプリで利用できる機能は、すべてブラウザアプリで利用可能です。パソコンに新しいソフトをインストールしたくない場合、ブラウザアプリをご利用ください。
ステップ⒋任意のプロジェクトをクリックすると、APIにアクセスすることができます。ここでAPIを設計したり、仕様書を生成したり、APIをテストしたりすることもできます。
Apidogのブラウザアプリは、デスクトップアプリのUIと機能も完全一致になっているので、次の操作ガイドを参照して、仕様書を詳しく設定して、生成することができます。
1. APIのメソッドとエンドポイントの設定
API仕様書を書き始める前にAPIの設計が必要となります。例えば、APIが提供できる機能、使用シーン、使い方を頭に明確にし、このAPIが技術上でも、業務上でも、合理的で実現可能であることを確認します。
APIのエンドポイント（パス）は具体的なウェブページではなく、ユーザーがサービスを見つけられる場所です。例えば、ユーザーがここで商品名を入力して、素早く商品を探せます。
パスを設定した上、APIのメソッドを設定します。通用なAPIメソッドは：
GET（コンテンツを取得）
POST（コンテンツを新規追加）
PUT（既存コンテンツを変更）
DELETE（コンテンツを削除）です。
2. APIの詳細を説明
APIのパスを設定した上、APIの利用者にAPIに関するより多くの情報を伝える必要があります。これらの情報には、APIの名前、機能説明、Requestのパラメータ、ResponseのパラメータやResponse例などが含まれています。
その中で、RequestとResponseのパラメータを設定する場合、各パラメータのデータタイプ、必須項目ではないか、パラメータの説明などの情報を記入することもできます。
こで記入する情報が多けば多いほど、API利用者のユーザーエクスペリエンスが高くなります。
3. APIケースを設定
APIケースの設定は、API仕様書の作成に対して非常に重要なステップです。APIケースは、開発者が当該APIの使い方を理解し、よりよくデバッグするのを助けることができます。ケースの作成中にAPIの各パラメータの意味と役割を明確に説明し、呼び出しの成功例と失敗例を明確に定義する必要があります。
4. APIのエラーコードを設定
APIのエラーコードは、APIの特徴と機能に基づいて設定される必要があります。エラーコードは問題の原因を明確に示し、開発者がより早く診断し、問題を解決できる解決策とアドバイスを提供するべきです。API仕様書でよく設計されたエラーコードがあることは、APIの使いやすさと信頼性を高め、開発者は故障排除に要する時間を減らすことができます。以下は参考になるAPIエラーコードタイプです。
クライアントエラー：クライアントエラーは通常、クライアントが送信したリクエストに問題があることを意味します。例えば、パラメータの欠如、フォーマットエラー、権限不足などです。一般的なクライアントエラーコードには、400 Bad Request、401 Unauthorized、403 Forbidden、404 Not Foundなどがあります。
サーバーエラー：サーバーエラーは通常、APIサーバーに問題があることを意味します。例えば、サーバー内部エラー、データベースの接続エラー、タイムアウトなどです。一般的なサーバーエラーコードには、500 Internal Server Error、502 Bad Gateway、503 Service Unavailableなどが含まれます。
業務エラー：業務エラーは通常、APIがクライアントリクエストを完了できないことを意味します。要求データが業務規則に合わなかったり、APIが要求を処理できないからです。一般的な業務エラーコードには422 Unprocessable Entity、429 Too Many Requests、451 Unavailable For Legal Reasonsなどがあります。
認証とセキュリティエラー：認証とセキュリティエラーは通常、APIがクライアントの身分を検証する必要があるが、認証できないか、認証が失敗することを意味する。一般的な認証とセキュリティエラーコードには、401 Unauthorized、403 Forbidden、419 Authentication Timeout、498 Invalid Tokenなどがあります。
制限と割当量エラー：制限と割当量エラーは通常、APIが特定の制限や割当量を超えたことを意味します。例えば、要求速度が制限を超えたり、割当量を超えたりします。一般的な制限と割当エラーコードには、429 Too Many Requests、503 Service Unavailable、509 Bandwidth Limit Exceededなどがあります。
5. バージョンコントロール機能の適用
API機能の開発に伴って、APIの情報を修正したり、変更したりする可能性があります。例えば、パラメータを追加したり、削除したり、変更したり、返すレスポンスのフォーマットを変更したりすることがよくあります。API仕様書にバージョンのコントロール機能がない場合、これら新しい変更は開発者に迷惑をかけ、彼らの開発効率に悪影響を及ぼす可能性があります。
そこでバージョンのコントロール機能を導入する必要があります。そうすると、異なるバージョンのAPIの変更点を表示することができるので、開発者は需要に応じて異なるバージョンを選択できますし、各バージョンの違いと変更をいち早く把握することもできます。
6. API仕様書の生成と共有
上記の操作ガイドを参照して、APIを定義すると、Apidogの共有機能を使って、非常にわかりやすいAPI仕様書を生成したり、他人に共有したりする事ができます。
左側メニューから「共有」をクリックして、「新しい共有」を選択すると、次のような共有設定が表示されます。ここで、共有するAPIを選択して、必要に応じてセキュリティ設定や言語の設定を終えて、「保存」をクリックします。
そして、新しい共有項目が表示されます。「開く」をクリックすると、API仕様書がブラウザに表示されます。
