全国道路施設点検データベース登録用API基本仕様書国土交通省—目次一1.本概要書の目的.

1.本概要書の目的
登録用API基本仕様書は、「全国道路施設データベース」において、各道路施設データベースに対し、オンラインにて道路構造物に関する諸元や点検データ等を登録するためのAPIに関する基本仕様書です。登録用API基本仕様書は、以下の３点の資料で構成しています。 ・登録API基本仕様書（本書） ・APIリファレンスサンプル「基本仕様書」は、上記APIの基本的な記述仕様を示すものとします。 (2019年3月28日 APIテクニカルガイドブック((内閣官房情報通信技術(IT)総合戦略室))に準拠) [ APIリファレンスサンプル]は、APIによる呼出しや実行結果の詳細仕様例のサンプルを示すものとします。尚、「APIリファレンスサンプル」の概要を4.リファレンスサンプルの概要に示します。尚、登録用APIのセキュリティ対策については、取り扱う情報の機密性を確保するためにAPIキー方式を採用しています。

2. 登録用API基本仕様書の定義仕様項目
3. 登録用APIの定義
3.1.  API接続方式
3.1.1.通信プロトコル
セキュアなHTTPプロトコルであるHTTPSによって通信を行う。 APIを設置するサーバはTLS(SSL)対応を必須とする。TLSのバージョンは1.2以降とする。
3.1.2.  REST対応
本APIのデータ参照様式は、REST(記述方式)に則った仕様を基本とする。
3.1.3. エンドポイント（接続先URL)
接続先のURLは以下の仕様とするhttps://{API設置サーバのドメイン}/xROAD/api/{バージョンコード}/{リソース名}?{検索条件}リソース名とは参照するデータの種類を表し、リソース名の後ろに検索条件を記述するものとする。リソース名や検索条件の内容については後述する。
3.1.4. バージョンコード
バージョンコードは頭文字v +バージョン数字とし、エンドポイントに含めて記述される。例えばバージョン1なら[ v1 ]と記述する。
3.1.5.日本語の文字コード
本APIを利用した通信上で、日本語を扱う場合の文字コードはUTF-8とする。
3.2. 施設種類ごとのデータ内容概要
3.2.1. 施設の種類ごとのIDについて
本APIによる施設データの参照は、施設の種類ごとにサーバが異なるため、URLを分別する。以下にURL内にて、施設の種類を区別するためのIDを示す。

3.3.リクエスト
3.3.1. 施設データの登録API
RESTの仕様に則って、POSTメソッドを用いる。登録する施設データはJSON形式のファイルを用いる。
アップロードする施設データファイルの仕様
•ファイル形式は、JSON形式にとする。 (RFC8259) ● 文字コードはUTF-8とする。 ●項目名の省略、独自の項目名の利用は禁止とする。 ●特殊記号、機種依存文字の利用は禁止とする。 ● 施設ID+点検年度で一意のデータとする。 •施設アップロードファイルの項目名については、別紙「公開用API基礎項目パラメータ名一覧」を参照。ただし、今後新たに追加されるデータ項目のパラメータ名は、「3. 7 」の留意事項に従って命名し、上記パラメータ名の扱いは、本API基本仕様書のAPIの記述ルールに準じる。
3.3.2. 処理状況監視API
RESTの仕様に則って、GETメソッドを用いる。
3.3.3. 付属ファイル登録API
RESTの仕様に則って、POSTメソッドを用いる。
3.4.レスポンス
3.4.1.  JSON形式のデータ
JSON形式の文字列として、以下のデータを返す。 • metadata APIの内容やリクエスト情報など● resultsetエラーの有無や内容など• result GETメソッドの場合は取得したデータを、それ以外の場合は処理結果を返す。上記の要素を下表に再掲する。

レスポンス例（正常)
← "metadata": { "title": "施設データの登録", "detail": "施設データの登録", "parameter": { "type": 1 } }, "resultset": { "is_error": false }}, "result": { (処理結果) } }
レスポンス例（（エラー）
{{ "metadata": { "title": "施設データの登録", "detail": "施設データの登録", "parameter": { "type": 1 } }}, "resultset": { "is_error": true, "error_title":  "fileが指定されていません" "error_detail": "fileが指定されていません" → }
3.4.2. エラーレスポンス
処理中に致命的なエラーが発生した場合、適切なHTTPレスポンスコードとエラー内容をJSON形式で返す。

レスポンス例
{{ "code": 400, "message": "検索範囲が日本国内を超えています" }
3.5.1. デ一タ登録APIの処理フロー
施設データの登録処理における、処理フローを以下に示す。
•処理ID
登録処理中の状況を監視するために、一時的に発行されるID。システムが発行するユニークな値とする。
3.5.2. データ登録API一覧

データ登録APIの一覧を以下に示す。尚、各APIにて指定する具体的なパラメータは3.6に示す。
3.6. 各APIにおいて指定するパラメータ
(1) 施設データ登録API
指定した施設データファイル（*.json）をアップロードし、取込処理を開始する。取込処理開始後は、処理完了を待たずにレスポンスとして処理IDを返す。パス: {施設種類ID}s/importメソッド: POST
データの送信にはRFC7578に則って「multipart/form-data」形式を利用する。
使用例(ドメインは仮称)施設データの登録POST https://www.example.go.jp/xROAD/api/v1/bridges/import
HTTPヘッダ
Content-Type: multipart/form-data; boundary=----BoundaryO5quBRiT4G7Vm3R7
リクエストボディ
------BoundaryO5quBRiT4G7Vm3R7 Content-Disposition: form-data; name="type" 1 ------BoundaryO5quBRiT4G7Vm3R7 Content-Disposition: form-data; name="file"; filename="ファイル名" Content-Type: text/plain (ファイルの内容) ------BoundaryO5quBRiT4G7Vm3R7--
(2) 処理状況監視API
指定処理IDの施設データファイルの取込処理状況を取得する。パス:  {施設種類ID}s/import/status/{処理ID}メソッド: GET
使用例(ドメインは仮称)

(3) 付属ファイルの登録API
指定した施設ID・点検年度の施設データに、付属ファイルをアップロードする。パス: {施設種類ID}s/upload/{施設ID}/{年度}メソッド: POST
データの送信にはRFC7578に則った「multipart/form-data」形式を利用する。
使用例(ドメインは仮称)施設ID「35.2134,139.112」、年度「2020」の施設データに付属ファイルの登録POST https://www.example.go.jp/xROAD/api/v1/bridges/upload/35.2134,139.112/2020 HTTPヘッタContent-Type: multipart/form-data; boundary=----BoundaryO5quBRiT4G7Vm3R7リクエストボディ------ BoundaryO5quBRiT4G7Vm3R7 Content-Disposition: form-data; name="total" 10 ------ BoundaryO5quBRiT4G7Vm3R7 Content-Disposition: form-data; name="count" 7 ------ BoundaryO5quBRiT4G7Vm3R7 Content-Disposition: form-data; name="processid" 7654321 ------ BoundaryO5quBRiT4G7Vm3R7 Content-Disposition: form-data; name="file"; filename="ファイル名" Content-Type: text/plain (ファイルの内容) ------BoundaryO5quBRiT4G7Vm3R7--
3.7. パラメータの定義における留意事項
点検項目の定義をもとにして、APIのパラメータを設定するにあたり、できるだけ表記のゆれをなくして使いやすくするために、以下の基準でパラメータの定義を行うものとする。
3.7.1.パラメータ構造
・項目のグループごとにまとめて入れ子にし、ツリー状の構造とする・JSONで表現できるデータ構造とする・パラメータ名を表記する場合は、入れ子の親から子へ順に「.」(ドット)で繋いで表記とする。
3.7.2. パラメータ名
・半角英数字で表記し、単語の接続はスネークケースとする・項目名を□－マ字で表記する。ただし元がカタカナの場合は英語表記とする例)定義ファイル→ teigi_file ・項目名が冗長になる場合は、項目名として使える適度な長さに短縮する
3.7.3.選択肢
・複数の中から一つを選択する項目は、選択肢の内容を直接書き込むのではなく、コード表を作成してコーﾄを入力する。例）高速自動車国道・都道府県道・一般国道→ 1 :高速自動車国道・2:都道府県道・3:一般国道• [ ○△□ ]などの記号や「有り•無し」などで表現されていた部分もコード表記に統一する。例)有り・無し→ 1・0
3.7.4.複数年データ
・2018,2019….といった年度毎に1列割り当てられているデータは、配列として表現する。
3.7.5.日付表記の統一
・年データは西暦とする。フォーマットはYYYY例) 2021 ・年月フォーマットはYYYYMM例) 202109 ・年月日フォーマットはYYYYMMDD例) 20210901
3.8.利用制限
本APIを利用する場合は、それぞれの利用が承認された利用者にのみ利用を許諾する。
3.9.利用申請
本APIを利用するにあたり、規定の利用申請により、APIの利用手続きを行うものとする。
3.10. 認証機能
APIキー方式による認証機能を具備したAPIの実装とする。
3.10.1.  APIキー方式
APIを利用するアプリごとにAPIキーを発行し、APIアクセス時にそのAPIキーをHTTPヘッダに記述することによって、発行対象のアプリからのアクセスであることを認証する。発行対象以外のアプリからのアクセスを防ぐため、発行時に登録したドメイン名やIPアドレスからのアクセス以外は拒否する。 ●APIキー記述へッダAPI-key ●APIキーフオーマット半角英数字40文字
3.11.利用規約
別途の利用規約を参照
4.用語集