想定読者
- 非エンジニアの事業開発、営業企画、DX担当、PdM、CS、マーケティング担当
- API連携案件でエンジニアと会話する必要がある人
- SaaS、業務システム、AIエージェント、Excel自動化、見積自動化に関わる人
- 再エネ・電力・補助金・太陽光/蓄電池シミュレーションのような複雑な業務APIを理解したい人
記事の目的
API仕様書を「暗号のような技術文書」ではなく、業務の入力・処理・出力・責任範囲を定義した契約書として読めるようにすることです。
OpenAPI Specificationは、HTTP APIの機能を人間とコンピュータの双方が理解できるように記述するための標準仕様です。ソースコードや通信の中身を直接見なくても、APIの機能を理解できるようにすることが目的です。(OpenAPI Initiative Publications)
API仕様書は、エンジニアだけのものではない
API仕様書を初めて見ると、多くの非エンジニアはこう思います。
「何が書いてあるのか、まったく分からない」
でも、これは能力の問題ではありません。読み方を教わっていないだけです。
API仕様書は、エンジニアだけが読む設計図ではありません。営業、企画、PdM、DX担当、CS、経営企画にとっても、かなり強力な実務文書です。なぜならAPI仕様書には、次のような情報が詰まっているからです。
- 何を入力すればよいか
- どんな処理を頼めるか
- 何が返ってくるか
- 認証はどうするか
- どんなエラーが起きるか
- 業務上、どこまで自動化できるか
- AIエージェントや外部システムから呼び出せるか
つまりAPI仕様書とは、かなり乱暴に言えば、「この業務を機械に任せるときの注文票」です。
エネがえるAPIの仕様書もOpenAPI形式で整理されており、ログイン、補助金情報照会、電気料金プラン取得、電気料金計算、電気使用量計算、太陽光発電量計算、設備導入シミュレーションなどのAPIが定義されています。2026年3月2日には設備導入シミュレーションと太陽光発電量計算APIが追加されたことも記載されています。
エネがえる共通 公開用 API https://www-apidoc.enegaeru.com/sys/
ここで大事なのは、API仕様書を「全部理解しよう」としないことです。
見る場所は、最初は7つで十分です。
非エンジニアがAPI仕様書で見るべき7つの場所
API仕様書を読むとき、最初に見るべき場所はこの7つです。
| 見る場所 | 技術的な名前 | 非エンジニア向けの意味 |
|---|---|---|
| 1 | Server | どこに依頼するか |
| 2 | Endpoint | 何の業務を依頼するか |
| 3 | Method | 取得・作成・更新・削除のどれか |
| 4 | Parameters | URLや検索条件で渡す情報 |
| 5 | Request body | 依頼時にまとめて渡す入力データ |
| 6 | Response | APIから返ってくる結果 |
| 7 | Error | 失敗したときの理由 |
この7つが読めるだけで、API仕様書はかなり怖くなくなります。
1. Server：どこに依頼するか
API仕様書の最初の方には、servers や base URL のような情報があります。
これは、業務で言えば「依頼先の窓口」です。
たとえばエネがえるAPIでは、本番環境のサーバーとして https://api.enegaeru.com が示されています。
非エンジニアがここで確認すべきことは、次の3つです。
| 確認項目 | なぜ重要か |
|---|---|
| 本番環境か、検証環境か | テストのつもりで本番処理を走らせないため |
| 社外からアクセスできるか | 自社システムやパートナーから呼び出せるかに関わる |
| URLが固定か | 将来の連携・保守・契約に関わる |
ここでの読み方はシンプルです。
Serverは、APIに仕事を頼む住所。
それだけ覚えれば十分です。
2. Endpoint：何の業務を依頼するか
API仕様書で一番大事なのがEndpointです。
Endpointは、たとえばこういう形で書かれます。
/sys/login
/sys/subsidy
/sys/subsidy/{id}
/sys/epcorps
/sys/epplans
/sys/epchargecalc
/sys/usepowercalc
/sys/pvpowercalc
/sys/equipsimulation
これは、業務で言えば「依頼メニュー」です。
エネがえるAPIの仕様では、たとえば以下のように整理できます。
エネがえる共通 公開用 API https://www-apidoc.enegaeru.com/sys/
| Endpoint | 業務上の意味 |
|---|---|
/sys/login |
ログインしてアクセストークンを取得する |
/sys/subsidy |
補助金情報の一覧を取得する |
/sys/subsidy/{id} |
特定の補助金の詳細を取得する |
/sys/epcorps |
電気事業者一覧を取得する |
/sys/epplans |
電気料金プラン一覧を取得する |
/sys/epchargecalc |
電気料金を計算する |
/sys/usepowercalc |
月別電気使用量から日別・時間別使用量を推計する |
/sys/pvpowercalc |
太陽光発電量を計算する |
/sys/equipsimulation |
太陽光・蓄電池などの設備導入シミュレーションを行う |
ここで非エンジニアが見るべきなのは、英単語の意味ではありません。
見るべきは、そのAPIが業務フローのどこを置き換えるかです。
たとえば、補助金情報を人が自治体サイトから調べてExcelに転記しているなら、/sys/subsidy は「補助金調査の一部」を置き換える可能性があります。
電気料金計算を人が料金表を見ながらExcelで行っているなら、/sys/epchargecalc は「料金計算の正本化」に使える可能性があります。
太陽光・蓄電池の導入効果を案件ごとに手計算しているなら、/sys/equipsimulation は「設備導入後の電力フロー試算」をAPI化する候補になります。
API仕様書を読むコツは、技術用語を暗記することではありません。
Endpointを、業務動詞に翻訳することです。
3. Method：取得・作成・更新・削除のどれか
API仕様書には、GET、POST、PUT、DELETE のようなHTTPメソッドが出てきます。
MDN Web Docsでは、GETは指定したリソースの表現を取得するメソッド、POSTは指定したリソースにデータを送信し、サーバー上の状態変更や副作用を伴うことが多いメソッドと説明されています。(MDNウェブドキュメント)
非エンジニア向けには、こう覚えると十分です。
| Method | ざっくり意味 | 業務での感覚 |
|---|---|---|
| GET | 取得する | 情報を見に行く |
| POST | 送信して処理する | 申請する・計算を依頼する |
| PUT | 更新・置換する | 既存情報を差し替える |
| DELETE | 削除する | 登録済み情報を消す |
たとえばエネがえるAPIでは、補助金一覧の取得はGET、電気料金計算や太陽光発電量計算、設備導入シミュレーションはPOSTです。
これは直感的です。
補助金一覧は「情報を取りに行く」のでGET。
電気料金計算や設備導入シミュレーションは「条件を渡して計算してもらう」のでPOST。
この感覚が分かると、API仕様書の読み方がかなり変わります。
ミニコラム：GETとPOSTは「見る」と「お願いする」
非エンジニア向けに一段かみ砕くと、GETとPOSTの違いはこうです。
GETは、図書館で本を探す行為です。
POSTは、窓口に申請書を出す行為です。
図書館で本を見るだけなら、基本的には状態は変わりません。
でも申請書を出せば、審査が走ったり、登録されたり、計算結果が作られたりします。
API仕様書では、この違いがMethodに表れます。
4. Parameters：検索条件として渡す情報
Parametersは、APIに渡す条件です。
たとえば補助金検索APIでは、都道府県コード、市区町村名、対象設備コード、補助対象区分、取得件数、次ページ取得用トークンなどのパラメータが定義されています。prefecture_cd、city、facility_cd、target_class は同時指定でき、複合条件で絞り込み可能です。
非エンジニアは、Parametersをこう読めばよいです。
Parameters = 検索・絞り込み・指定に使う条件
たとえば補助金検索なら、こんな会話に変換できます。
東京都の
江東区で
太陽光発電と蓄電池が対象で
個人向けまたは共通の補助金を
200件まで取得したい
これをAPI仕様書の言葉にすると、次のようになります。
prefecture_cd=13
city=江東区
facility_cd=01,02
target_class=個人
limit=200
ここで重要なのは、API仕様書が単なる技術文書ではなく、業務条件の一覧表になっていることです。
補助金検索において「都道府県」「市区町村」「対象設備」「個人/事業者区分」が条件として必要だと分かれば、営業ヒアリング項目も決まります。
API仕様書を読むと、入力フォーム、営業ヒアリングシート、Excel列定義、AIエージェントの質問項目まで作れるのです。
5. Request body：処理に必要な入力データ
POST APIでは、Request bodyが重要です。
Request bodyは、APIに渡す入力データの本体です。
たとえば電気料金計算APIでは、料金プランID、基本料金コード、契約容量、日ごとの買電量、ピーク買電量、燃料費調整単価、再エネ賦課金単価、詳細出力の有無などを渡します。
これは、非エンジニアにとって非常に重要です。
なぜならRequest bodyを見ると、その計算に必要な前提条件が分かるからです。
たとえば、電気料金計算をAPI化したいなら、次のような情報が必要になります。
| 入力項目 | 業務上の意味 |
|---|---|
epplan_id |
どの電気料金プランで計算するか |
base_cd |
どの基本料金区分を使うか |
capacity |
契約容量 |
purchase |
日別・時間別の買電量 |
peak_purchase |
年間ピーク値 |
fuels |
カスタム燃調費 |
renewable |
カスタム再エネ賦課金 |
detail |
内訳を返すかどうか |
これを読んだ非エンジニアは、次の判断ができます。
- このAPIを使うには、日別・時間別の使用量データが必要そうだ
- 月別使用量だけでは足りないケースがある
- 契約容量や料金プランIDの管理が重要になる
- 燃調費や再エネ賦課金を固定値にするか、API側の最新値を使うかを決める必要がある
つまりRequest bodyは、技術者向けの入力仕様であると同時に、業務設計者向けの必要データ一覧でもあります。
6. Response：何が返ってくるか
Responseは、APIから返ってくる結果です。
ここも非エンジニアが必ず見るべき場所です。
なぜなら、Responseを見ると、レポート・画面・Excel・提案書に何を出せるかが分かるからです。
たとえば電気料金計算APIのレスポンス例には、年間電気料金総額、月別電気料金、基本料金、従量料金、燃料費調整額、再エネ賦課金などの内訳が含まれます。
| Response項目 | 使い道 |
|---|---|
yearCharge |
年間電気料金の表示 |
monthlyCharges |
月別料金グラフ |
detail.yearCharge.base |
年間基本料金の内訳 |
detail.yearCharge.usage |
年間従量料金の内訳 |
detail.yearCharge.adjust |
燃料費調整額の説明 |
detail.yearCharge.levy |
再エネ賦課金の説明 |
ここでのポイントは、Responseは「返ってくるデータ」であると同時に、顧客に説明できる粒度でもあることです。
年額だけ返ってくるAPIなら、説明は粗くなります。
月別・内訳まで返ってくるAPIなら、提案書やCS対応に使いやすくなります。
API仕様書を見るときは、必ずこう問いましょう。
このAPIの結果は、顧客に説明できる粒度で返ってくるか？
この問いは、エンジニアだけではなく、営業責任者、CS、PdMにも重要です。
7. Error：失敗したときに何が分かるか
API連携で見落とされがちなのがErrorです。
しかし実務では、Errorこそ重要です。
API仕様書には、HTTPステータスコードとして 400、401、403、404、500、504 などが出てきます。エネがえるAPI共通エラーでは、400はリクエスト内容に起因するエラー、403は認証エラー、500はAPI内部処理エラー、504はタイムアウトとして整理されています。
非エンジニア向けには、こう読めば十分です。
| ステータス | ざっくり意味 | 現場での見方 |
|---|---|---|
| 400 | 入力が悪い | 入力条件・形式・必須項目を確認 |
| 401 / 403 | 認証・権限が悪い | ログイン、トークン、APIキー、権限を確認 |
| 404 | 対象がない | ID間違い、データ未存在を確認 |
| 500 | API内部エラー | 利用者側だけでは直せない可能性 |
| 504 | タイムアウト | データ量、再実行、処理時間を確認 |
API Securityの観点では、OWASP API Security Top 10のようにAPI特有のセキュリティリスクも整理されています。特に認証・認可・過剰なデータ露出・リソース消費などは、APIを業務システムに組み込む際に無視できません。(OWASP Foundation)
エラー仕様を見ると、運用設計ができます。
- 400なら入力画面でどんな注意書きを出すか
- 403なら再ログインを促すか、管理者へ問い合わせるか
- 500ならどこまでユーザーに表示するか
- 504なら再実行ボタンを出すか、処理分割するか
API仕様書のError欄は、単なる失敗コードではありません。
ユーザーが詰まったときの救急箱です。
API仕様書は「業務の契約書」として読む
ここまでをまとめると、API仕様書は次のように読めます。
| 技術用語 | 非エンジニア向け翻訳 |
|---|---|
| Server | 依頼先 |
| Endpoint | 依頼メニュー |
| Method | 依頼の種類 |
| Parameters | 検索条件 |
| Request body | 申込書・計算条件 |
| Response | 結果票 |
| Error | 失敗時の説明書 |
| Authentication | 本人確認・通行証 |
| Schema | 入力・出力の型紙 |
この翻訳ができると、エンジニアとの会話が一気に変わります。
「このAPI、使えますか？」ではなく、
「このAPIは、補助金検索の都道府県・市区町村・設備種別・対象区分まで絞り込めますか？」
「料金計算のResponseに、基本料金・従量料金・燃調費・再エネ賦課金の内訳は返りますか？」
「エラー時に、入力ミスなのか認証エラーなのか判別できますか？」
「AIエージェントから呼び出す場合、正本計算はAPI側に寄せられますか？」
と聞けるようになります。
これは、かなり大きな差です。
API仕様書を読むときの全体像
非エンジニアは、最初からコードを書く必要はありません。
まずは、API仕様書を見て、次の4つを確認できれば十分です。
- 何ができるか
- 何を渡す必要があるか
- 何が返ってくるか
- 失敗したときに何が分かるか
この4つが分かれば、API仕様書は読めています。
自前実装 vs 業務特化API活用
API仕様書を読む目的は、技術理解だけではありません。
業務を自前で作るべきか、業務特化APIを使うべきかを判断する材料にもなります。
| 観点 | 自前実装 | 業務特化API活用 |
|---|---|---|
| 初期開発 | 自由度は高いが重い | 早く始めやすい |
| 業務DB | 自社で整備・更新が必要 | API提供側のDBを使える場合がある |
| 計算ロジック | 全部自社で作る | 特化領域は外部APIに寄せられる |
| 監査性 | 設計次第 | API仕様・ログ設計次第 |
| AI連携 | 自前で整備が必要 | API化されていれば呼び出しやすい |
| 保守 | 継続コストが高い | 外部依存はあるが軽くできる |
| 差別化 | 独自ロジックを持てる | 業務設計・UI・営業運用に集中できる |
太陽光・蓄電池・EV・V2H・PPAの経済効果試算のように、電力料金、補助金、設備仕様、発電量、使用量、蓄電池制御などが絡む業務では、全部を自前で作るとかなり重くなります。
この領域では、エネがえるAPIのような業務特化APIを使うことで、料金プラン取得、補助金情報取得、電気料金計算、太陽光発電量計算、設備導入シミュレーションなどの一部を外部APIに任せる設計が現実的になります。
エネがえる共通 公開用 API https://www-apidoc.enegaeru.com/sys/
ただし、外部APIを使えば何でも解決するわけではありません。
重要なのは、自社が持つべき業務知識と、APIに任せるべき正本処理を分けることです。
AI時代の業務システム三層構造
AIエージェントが業務に入るほど、API仕様書の重要性は上がります。
なぜならAIは文章生成や要約、候補提示には強い一方で、金額計算、契約条件、投資回収、補助金適用可否のような正本処理を曖昧に扱うべきではないからです。
ここで使えるのが、次の三層構造です。
| 層 | 役割 | 例 |
|---|---|---|
| UI層 | 人間が入力・確認する | 画面、Excel、フォーム |
| AI層 | 下書き・要約・候補提示を行う | ヒアリング整理、提案文生成 |
| API層 | 正本計算・正本データ・監査可能な処理を担う | 料金計算、補助金検索、設備導入シミュレーション |
AIが強くなるほど、APIは地味になります。
しかし地味だからこそ重要です。
AIが顧客ヒアリングを整理し、提案文を作る。
でも、電気料金計算や投資回収の前提はAPIが担保する。
結果はDBに保存し、誰が、いつ、どの条件で計算したかをログに残す。
これが、AI時代の業務システムの現実解です。
NISTのデジタルアイデンティティガイドラインでは、認証保証レベルや認証器のライフサイクルに関する推奨が整理されています。API連携でも、認証情報やトークンをどう扱うかは、単なる実装論ではなく運用・監査の論点になります。(NIST Pages)
AIに任せる領域、APIに任せる領域
| 領域 | AI向き | API/DB向き |
|---|---|---|
| 顧客ヒアリングの要約 | ◎ | △ |
| 提案書のたたき台 | ◎ | ○ |
| FAQ回答の下書き | ◎ | ○ |
| 補助金候補の説明文作成 | ○ | ◎ |
| 補助金データ検索 | △ | ◎ |
| 電気料金計算 | △ | ◎ |
| 太陽光発電量計算 | △ | ◎ |
| 蓄電池シミュレーション | △ | ◎ |
| 投資回収の確定説明 | △ | ◎ |
| 監査ログ保存 | △ | ◎ |
反直感かもしれませんが、AI時代に価値が上がるのは、派手なチャットUIだけではありません。
むしろ価値が上がるのは、AIが安全に呼び出せる業務APIです。
UIは真似されます。
プロンプトも真似されます。
でも、長年更新された業務DB、例外処理、計算ロジック、監査性は簡単には真似できません。
API仕様書を読めると、商談が変わる
API仕様書を読める非エンジニアは、商談で強くなります。
なぜなら、相手の「できます」に対して、具体的に確認できるからです。
たとえばAPI連携の商談で、次のような質問ができます。
| 確認したいこと | 質問例 |
|---|---|
| 認証 | APIキーとアクセストークンの両方が必要ですか？ |
| 権限 | ユーザー権限や契約プランで使えるAPIが変わりますか？ |
| 入力 | 必須項目は何ですか？未入力ならどうなりますか？ |
| 出力 | レポートに使える内訳まで返りますか？ |
| エラー | 入力エラーと認証エラーは区別できますか？ |
| 更新 | 料金単価や補助金データはどの頻度で更新されますか？ |
| ログ | 誰がどの条件で計算したか保存できますか？ |
| AI連携 | AIエージェントから呼び出す前提で使えますか？ |
この質問ができるだけで、会話の解像度が変わります。
「API連携できますか？」という質問は、少し粗い。
本当に聞くべきなのは、
どの業務を、どの入力で、どの責任範囲までAPI化できますか？
です。
エネがえるAPI仕様を例に、非エンジニアが読む順番
エネがえる共通 公開用 API https://www-apidoc.enegaeru.com/sys/
ここでは、エネがえるAPI仕様を例に、非エンジニアが読む順番を整理します。
Step 1. まずログインを見る
/sys/login では、ユーザーID、パスワード、強制ログイン指定、ログインするサービス種別をRequest bodyに渡し、成功時にはアクセストークンやユーザー情報、利用可能プランが返ります。API呼び出し時は、返ってきたアクセストークンをAuthorizationヘッダーにセットする仕様です。
非エンジニアが見るべき点はこれです。
- API利用にはログインが必要
- アクセストークンを使う
- 利用可能なプロダクトプランが返る
- 権限レベルやグループ情報がある
- 強制ログイン指定があるため、同一ユーザー利用時の運用に注意が必要
ここから分かる業務論点は、認証情報の管理です。
営業担当者ごとにIDを使うのか。
システム連携用の専用アカウントを使うのか。
権限は誰が管理するのか。
トークンの期限や再ログインはどう扱うのか。
仕様書を読むだけで、運用設計の論点が出てきます。
Step 2. 補助金APIを見る
/sys/subsidy は補助金一覧、/sys/subsidy/{id} は補助金詳細を取得するAPIです。補助金一覧では、都道府県コード、市区町村、対象設備コード、補助対象区分を使って絞り込みできます。補助金データは月1回程度で更新予定とされています。
非エンジニアが見るべき点はこれです。
- 一覧と詳細が分かれている
- 一覧は軽量なレスポンス
- 詳細は個別IDで取得する
- 個人・事業・共通の区分がある
- 対象設備コードが定義されている
- 更新頻度の目安がある
これは、補助金検索UIや営業支援ツールを作るときに重要です。
一覧画面では軽い情報を出し、詳細画面でURL、期間、対象、金額、概要、問い合わせ先などを表示する。
これはAPI仕様から自然に導けるUI設計です。
Step 3. 電気料金APIを見る
電気料金関連では、電気事業者取得、電気料金プラン取得、料金プラン詳細取得、電気料金計算のAPIが定義されています。料金プラン詳細では燃調費・再エネ賦課金単価を含む詳細情報を取得でき、電気料金計算では料金プランと買電量により年間・月別の電気料金や内訳を計算できます。
非エンジニアが見るべき点はこれです。
- 電気事業者 → 料金プラン → 料金プラン詳細 → 料金計算という順序がある
- 契約種別が低圧電灯、低圧電力、高圧、特別高圧に分かれる
- 市場連動型プランは計算方法が異なる
- 買電量データの粒度が重要
- 燃調費や再エネ賦課金の扱いを確認する必要がある
ここを読むと、料金計算APIを使うには、単に「電気代を出したい」では不十分だと分かります。
必要なのは、料金プランID、基本料金区分、契約容量、買電量、必要に応じてピーク値や燃調費・再エネ賦課金の指定です。
Step 4. シミュレーションAPIを見る
電気使用量計算、太陽光発電量計算、設備導入シミュレーションは、再エネ提案の中核に近いAPIです。
/sys/usepowercalc は月別電気使用量、ロードカーブパターン、適用条件から電気使用量を推計します。/sys/pvpowercalc は設置地点と太陽光パネル情報から発電量を計算します。/sys/equipsimulation は電気使用量、太陽光発電量、PCS、蓄電池設定などに基づき、設備導入後の電力フローをシミュレーションします。
非エンジニアが見るべき点はこれです。
- 月別使用量だけではなく、時間別の使用量推計が重要
- 太陽光発電量は地点、方位、傾斜、容量、温度係数などに依存する
- 蓄電池シミュレーションは充電・放電時間帯、ピーク制御、変換効率などを扱う
- 出力には買電量、自家消費、蓄電、売電、過積載ロス、蓄電池残量などが含まれる
このResponseを見ると、提案書に何を出せるかが見えます。
たとえば、自家消費量、余剰売電量、蓄電池残量、買電削減量をグラフにできる。
過積載ロスや過積載充電量も説明できる。
ピークカットの効果も可視化できる。
仕様書は、提案書の設計図でもあるのです。
API仕様書を読める人が作れるもの
API仕様書を読めるようになると、非エンジニアでも次のような成果物を作れます。
| 成果物 | API仕様書から拾う情報 |
|---|---|
| 営業ヒアリングシート | Request bodyの必須項目 |
| Excel入力テンプレート | パラメータと型 |
| 画面ワイヤーフレーム | Endpointの処理順 |
| 提案書項目 | Responseの出力項目 |
| FAQ | Errorと例外条件 |
| AIエージェントの質問設計 | API呼び出しに必要な入力 |
| 要件定義書 | APIの責任範囲 |
| テストケース | 正常系・異常系のレスポンス |
これがかなり重要です。
API仕様書を読む目的は、エンジニアの仕事を奪うことではありません。
エンジニアが作る前に、業務要件の解像度を上げることです。
実装例：非エンジニアでも読める疑似コード
実装コードを完璧に書ける必要はありません。
でも、処理の流れを読めると会話が変わります。
以下は、補助金APIを呼び出すイメージです。
// 疑似コード：補助金一覧を取得する流れ
// 実際のAPIキーやトークンは .env など安全な場所に保存する
const API_BASE_URL = "https://api.enegaeru.com";
const API_KEY = process.env.ENEGAERU_API_KEY;
const ACCESS_TOKEN = process.env.ENEGAERU_ACCESS_TOKEN;
async function searchSubsidies() {
const params = new URLSearchParams({
prefecture_cd: "13", // 東京都
city: "江東区", // 市区町村
target_class: "個人", // 個人向け
limit: "200"
});
params.append("facility_cd", "01"); // 太陽光発電
params.append("facility_cd", "02"); // 蓄電システム
const response = await fetch(`${API_BASE_URL}/sys/subsidy?${params.toString()}`, {
method: "GET",
headers: {
"accept": "application/json",
"x-api-key": API_KEY,
"Authorization": ACCESS_TOKEN
}
});
if (!response.ok) {
// 400なら入力条件、403なら認証、500ならAPI内部エラーなどを確認する
throw new Error(`API error: ${response.status}`);
}
const data = await response.json();
return data.items.map((item) => ({
id: item.id,
title: item.title,
prefecture: item.prefecture,
city: item.city,
facility: item.facility,
targetClass: item.target_class
}));
}
非エンジニアが読むべきなのは、細かい構文ではありません。
見るべきはこの流れです。
- APIのURLを決める
- 検索条件を作る
- APIキーとアクセストークンを付ける
- GETで呼び出す
- 成功ならJSONを読む
- 失敗ならステータスコードを見る
- 必要な項目だけ整形する
この流れが分かれば、API連携の会話に参加できます。
API仕様書を見るときのチェックリスト
基本理解
- どの業務を扱うAPIか説明できる
- Endpointを業務動詞に翻訳できる
- GETとPOSTの違いを説明できる
- 必須入力と任意入力を区別できる
- Responseから画面・帳票に使う項目を選べる
業務設計
- API利用に必要なデータを営業ヒアリング項目に落とせる
- Excel列定義に変換できる
- エラー時の運用を想定できる
- どこまでAPIに任せ、どこを自社で持つか整理できる
- AIエージェントに任せる領域とAPIに任せる領域を分けられる
セキュリティ・運用
- APIキーやアクセストークンの扱いを確認している
- ユーザー権限や契約プランによる制限を確認している
- ログ保存の必要性を確認している
- タイムアウトや再実行の扱いを確認している
- 本番環境と検証環境を分けて考えている
よくある失敗パターン
失敗1：Endpointだけ見て「使えそう」と判断する
Endpoint名だけ見て判断すると危険です。
大事なのは、入力と出力です。
たとえば「料金計算API」があっても、必要な入力データが自社に存在しなければ、すぐには使えません。
失敗2：Responseの粒度を確認しない
年額だけ返ってくるのか。
月別が返ってくるのか。
内訳まで返ってくるのか。
ここを確認しないと、提案書や画面を作る段階で詰まります。
失敗3：エラー仕様を後回しにする
API連携は、正常時より異常時に差が出ます。
入力ミスなのか、認証エラーなのか、対象データなしなのか、タイムアウトなのか。
これが分からないと、CSや営業が困ります。
失敗4：AIに正本計算まで任せる
AIは便利ですが、正本計算や金額確定を曖昧な文章生成に任せるのは危険です。
計算・料金・補助金・投資回収のような領域は、API・DB・ログで担保するべきです。
失敗5：API仕様書をエンジニアだけに閉じる
API仕様書をエンジニアだけの文書にすると、業務側の期待値と実装がズレます。
非エンジニアも、少なくともEndpoint、入力、出力、エラー、認証だけは見るべきです。
実務導入ステップ
Phase 1：API仕様書を業務翻訳する
最初にやるべきことは、Endpoint一覧を業務動詞に翻訳することです。
/sys/subsidy → 補助金を検索する
/sys/epchargecalc → 電気料金を計算する
/sys/pvpowercalc → 太陽光発電量を計算する
/sys/equipsimulation → 設備導入後の電力フローを試算する
Phase 2：入力項目をヒアリング項目に変換する
Request bodyやParametersを見て、営業ヒアリング項目に変換します。
たとえば太陽光発電量計算なら、地点、設置形態、方位角、傾斜角、容量、温度係数、PCS情報などが入力候補になります。
Phase 3：Responseを帳票項目に変換する
返ってくる項目を見て、提案書、画面、Excel、PDFの出力項目を決めます。
Phase 4：エラー時の運用を決める
400、403、500、504などのエラーごとに、ユーザーへの表示、社内連絡、再実行、ログ保存を決めます。
Phase 5：AIとAPIの役割を分ける
AIはヒアリング整理、提案文作成、FAQ回答補助。
APIは正本計算、正本データ取得、監査可能な処理。
この分担が、AI時代の実務ではかなり効きます。
まとめ：API仕様書は「読める人」から「使える人」へ
API仕様書を読む力は、非エンジニアにとっても強力な武器になります。
読むべき場所は、最初は7つで十分です。
- Server
- Endpoint
- Method
- Parameters
- Request body
- Response
- Error
この7つを業務の言葉に翻訳できれば、API仕様書は怖くありません。
そしてAPI仕様書が読めると、次のことができます。
- エンジニアとの会話が具体化する
- 営業ヒアリング項目を設計できる
- Excelテンプレートを作れる
- AIエージェントの入力設計ができる
- API連携の要件定義に参加できる
- 自前実装と業務特化API活用の判断ができる
- 顧客に説明できる粒度でシステムを設計できる
エネがえるAPIのような業務特化APIは、単に「便利な外部API」ではありません。再エネ・電力料金・補助金・太陽光・蓄電池・EV/V2H・PPAのように、業務DBと計算ロジックが絡む領域で、正本処理を外部化し、AIや自社システムから安全に呼び出すための基盤になり得ます。
エネがえる共通 公開用 API https://www-apidoc.enegaeru.com/sys/
最後に、API仕様書を読むときの最強の問いを置いておきます。
このAPIは、どの業務判断を、どの入力で、どの粒度まで、監査可能にしてくれるのか？
この問いが持てた時点で、あなたはもうAPI仕様書を「読まされる人」ではありません。
業務を設計する側の人です。
参考文献・出典URL
- OpenAPI Specification v3.0.0：OpenAPIはHTTP APIの標準的・言語非依存のインターフェース記述で、人間とコンピュータがサービスの機能を理解できるようにする仕様。(OpenAPI Initiative Publications)
- MDN Web Docs「HTTP リクエストメソッド」：GET、POST、PUT、DELETEなどHTTPメソッドの意味の確認に使用。(MDNウェブドキュメント)
- OWASP Foundation：APIセキュリティやWebアプリケーションセキュリティの基礎的参照先。(OWASP Foundation)
- NIST SP 800-63B Digital Identity Guidelines：認証、認証器、認証保証レベルの考え方の参照。(NIST Pages)
- エネがえる共通 公開用 API仕様：エネがえるAPIのEndpoint、Request/Response、認証、補助金、電気料金、太陽光発電量、設備導入シミュレーションの具体例として参照。
- 今回の記事生成方針は、ユーザー提供の技術ブログ自動生成プロンプトに含まれる「読者の実務課題解決」「再現可能な手順」「エネがえるAPIの自然導線」方針に沿って構成。
エネがえるAPI
太陽光・蓄電池・EV/V2H・PPAの経済効果試算、電気料金計算、補助金情報取得のように、業務DBと計算ロジックが絡む領域では、すべてを自前実装するより、エネがえるAPIのような業務特化APIを組み合わせることで、開発範囲と運用負荷を絞れる場合があります。
エネがえる共通 公開用 API https://www-apidoc.enegaeru.com/sys/