Coppell Technologies データ仕様の現状と課題
5. 公表されている標準仕様案
|
|
|
2022年5月5日 |
| スーパーシティ／スマートシティの相互運用性の確保等に関する検討会の成果として、「２０２０年度データ連携基盤技術報告書」である「スーパーシティのデータ連携基盤に関する調査業務」(2021/03)が公開され、その5.3節に標準仕様案が掲載されています。以下、紹介します。なるべく原文のまま掲載していますが、原文ではもっとちゃんとした説明がありますので、本書ははインデックスとしてご利用になり、詳しくは原文をご覧ください。 |
| 分類 |
記載内容 |
データ仕様との関係 |
| 通信プロトコル |
(必須) API と API 利用者（サービス）を接続する通信路を暗号化する
(推奨) API と API 利用者（サービス）を接続するプロトコルを HTTPS とする
(推奨) クライアントアプリから非SSLのURLアクセスがあるケースでは対応するHTTPSのURLにリダイレクトせず、HTTPアクセスしたことへのエラーを返却するよう実装する |
関係しない |
| 呼出しI/F |
(必須) API の インターフェース を OpenAPI 仕様に準拠した設計とする
(必須) OpenAPI 仕様のファイル名は openapi.json もしくは openapi.yaml ファイルとする
(推奨) API の インターフェース は、 Pragmatic REST に基づく設計とする。 |
関係しない |
| データモデル |
(推奨) API が取り扱うデータモデルとして、業界標準の形式を採用する
(推奨) API が取り扱うリクエスト レスポンスボディフォーマットを JSON 形式とする
(推奨) 属性値のフォーマットを、国際標準やデファクトスタンダード等に従って設定する |
業界標準として何を採用するのか検討が必要 |
| URLリソース名 |
(必須) データモデルと属性名として、半角英数字、ハイフン、及びアンダースコアのみを使用する。
(推奨) APIで取り扱うデータモデル名と属性名として、標準的なアメリカ英語の名詞を使用する。
(推奨) APIで取り扱うデータモデル名と属性名として、スネークケースを使用する。
(推奨) URL 中のリソース名を複数形で記載する。
(推奨) プログラミング言語でよく利用されるキーワードとの競合を避けた名前を使用する。
(推奨) 一般的によく知られる名称については略語を使用する。
(推奨) 属性名には前置詞を使わない短くシンプルな名前を使用し、形容詞を名詞の前に記載する。
(必須) 属性値が数値となる場合は、属性名に単位を含める。
(必須) 範囲を表す属性名は、属性名の先頭を「start」又は「end」とする。
(必須) 属性値が配列で表現される場合、その属性名を複数形とする。
(必須) 商品数などを表す属性名には「 count 」を含める。 |
データモデル(Entity type)と属性名(Attribute name)の規定が関係する。尚、NGSI V2の規格では、もっと多様な文字を使える仕様となっている。
データモデル名と属性名はスネークケースとなっているが、NGSI V2ではキャメルケースとなっている。
リソース名は複数形となっているが、一般的には複数かもしれない場合は複数形とする事になっている。
形容詞を名詞の前に置くとなっているが、実績としては逆になっている。例えばdateCreatedなど。
属性名に単位を含めるとなっているが、通常は、データはメートル法に統一し、表示時に変換する。
範囲を表す属性は、startとendを付けるとなっているが、一般的に他の表現が多い。例えばopenとcloseなど。
数を表すときにcountを付けるというのは、既存のデータモデルと乖離がある |
| リクエストURL |
(必須) URL を RFC 3986 に準拠し、 RFC 6570 に示される URI Template 記法で表現できる形式とする。
(必須) API のバージョン（v1、v2等）をURLに含める。
(推奨) API のバージョンを上げた場合に下位互換性を保つ設計とする。
(推奨) 地域が用意する全てのAPI でドメイン名を統一する。
(必須) URL に API を表す「api 」を含める。
(推奨) サブドメイン名にAPI 提供を表す「api」を含める。
(必須) API の検証利用目的のための環境を用意する。
(推奨) API の検証利用目的のためのサブドメイン名を「 api sandbox 」とする。
(必須) 地域の開発者ポータルのURL には「developer」を含める。
(推奨) 地域の開発者ポータルのサブドメイン名を「developer 」とする。
(必須) 取り扱うデータ種が異なる場合はURL を分割する。
(必須) 計算や翻訳などの処理を実行する API の URL を名詞ではなく動詞とする。
(必須) データ種の階層構造を表現するURL パスを設計する。
(必須) データ種のID にはデータベースのシーケンス番号を指定しない。
(必須) データ種のID には URL で使用可能 な ASCII 文字を使用する。
(推奨) UUID などデータ種と関連しない値を ID として使用する。
(必須) URL 末尾のスラッシュ有無で API の動作を変更しない。
(必須) URL には機密情報を含まない設計とする。 |
データ仕様と関係しない |
| クエリパラメータ |
(必須) クエリパラメータを指定しなくても API を利用できる設計とする。
(推奨) クエリパラメータ名は、Web API で標準的に利用されるものを採用する。
(必須) クエリパラメータ名は半角英数字 で始め、 全て 小文字で記載する。
(必須) 1 つの クエリ パラメータに複数の値を指定する際には、 カンマ 「 」を用いる。
(必須) 複数の値を指定するクエリパラメータ 名を複数形、それ以外を単数形で記載する。
(推奨) GETリクエストにおいて、返却データが10件以上になる場合、「limit」もしくは「since」 until」パラメータを指定し、返却件数を制限する。
(推奨) レスポンスデータ項目として10 件以上の項目を含む場合、「fields」パ ラメータを指定し、要求する項目の み返却する。
(推奨) リクエストデータに外字を含まない。 |
データ仕様と関係しない |
| リクエストメソッド |
(必須) API のデータ操作内容により、 HTTP メソッドを使い分ける。 |
データ仕様と関係しない |
| リクエストヘッダ |
(推奨) 必要に応じて標準的なリクエストヘッダを設定する。 |
データ仕様と関係しない |
| リクエストボディ |
(推奨) リクエストボディを設定する場合は、JSON 形式を採用する。
(推奨) テキストデータの文字コードはUTF 8 を使用する。 |
NGSI V2と矛盾しない |
| ステータスコード |
(必須) GET リクエストが成功した場合、通常は 200 OK を返す。
(必須) GET リクエストで 0 個のリソースを取得した場合は 200 OK を 返す 。
(必須) GET リクエストでリソースの取得が できなかった 場合は 404 Not Found を 返す
(必須) POST リクエスト が新しいリソース の作成に成功した 場合、 201 Created
(必須) PUT リクエスト が既存リソ ース の 更新 に成功 した場合、 200 OK 又 は 204 No Content を返す。
(必須) PATCH リクエストが 既存リソース の 更新 に成功 した場合、 200 OK 又 は 2 04 No Content を返す 。
(必須) DELETE リクエストが対象 リソースの削除に成功した場合、 204 No Content を返す。
(必須) DELETE リクエストの対象リソースが削除済みの場合、 2 04 No Content を返す。 |
データ仕様と関係しない |
| レスポンスヘッダ |
(推奨) 必要に応じて標準的なレスポンスヘッダを設定する。 |
データ仕様と関係しない |
| レスポンスボディ |
(推奨) レスポンスボディを返却する場合は、JSON 形式を採用する。
(推奨) テキストデータの文字コードにはUTF 8 を使用する。
(必須) API のレスポンス ボディ に外字 を使用しない。
(必須) 日本語（全角文字）については『JIS X 0213 』に定義される JIS 第 1 水準～ JIS 第 4 水準を利用する。
(推奨) API に返却するデータについて、必要に応じて文字コードの変換、文字の縮退を行う。
(必須) レスポンスデータに複数行テキストが含まれる場合、改行コード には LF を使用する。
(必須) JSON で 0 個のリソースを返却する場合、その属性値を NULL ではなく空配列（[]）とする。
(必須) JSON の属性値にテキストを保持する場合、タブや改行などの特殊文字をエスケープする。
(推奨) 処理ステータス、処理ログ、ドキュメン ト、パラメータ、データ件数、実行結果データ、画面遷移などのメタデータを API 実行結果に含める。
(推奨) エラーレスポンス時として、エラー内容を示すレスポンスボディを返却する。 |
NGSI V2と矛盾しない |
| 認証方式 |
(推奨) API のクライアント認証では API Key を使用した認証方法を選択する。
(推奨) API のユーザ認証では OpenID Connect を使用する。
(必須) 個人情報など個人同意が必要となる情報の流通を行う場合はオプトイン管理を実装する。 |
データ仕様と関係しない |
| システム構成 |
(推奨) API ゲートウェイを利用し、 API の共通機能を取り まと めて提供する。 |
データ仕様と関係しない |
2022年5月5日
同じく表記方法について準拠すべき標準を例示しています。
| 内容 |
表記方法 |
表記例 |
| 日時 |
ISO8601 に準拠すること。日付のみであれば、全て半角で YYYY MM DD 。
日時（日本時間）の場合、日付と時間の間に T を挟み、全て半角で YYYY MM DDTHH:mm:ss+0900 と記載する。日本では UTC から 9 時間の時差があるため、 +0900 とする。 |
日付のみであれば、『 2017 02 06 』、日時（日本時間）であれば、『 2017 0206T13:50:40+0900 』で表す。 |
| 期間 |
ISO8601 に準拠すること。
P[n]Y[n]M[n]DT[n]H[n]M[n]S
P は、期間表現の開始時に配置される期間指定子。 |
『 P3Y6M4DT12H30M5S 』は「 3 年、 6 か月、 4 日、 12 時間、 30 分、 5 秒」の期間を表す。 |
| 言語 |
ISO 639 1 に準拠すること。
日本語を必須、英語については推奨とする。多くの言語に対応
する必要がある場合には、 ISO639 2 や ISO639 3 などを検討す
る。 |
日本語の場合『 ja 』、英語の場合『 en 』で表す。 |
| 貨幣 |
ISO 4217 に準拠すること。 |
日本円の場合『 JPY 』、アメリカドルの
場合『 USD 』で表す。
※あくまで円やドルなどの貨幣単位について記述するもので、貨幣の量の情報は含まれない 。 |
| 性別 |
ISO 5218 に準拠すること。 |
男性の場合『 1 』、女性は『 2 』、それ以外は『 9 』、不明な場合には『 0 』で表す。 |
| 国 |
ISO 3166 1 alpha 2 に準拠すること。 |
日本の場合『 JP 』、米国の場合『 US 』で表す。 |
| 都道府県 |
ISO 3166 2:2013JIS X 0401 に準拠すること（日本の場合、ISO3166 2:JP を参照する） 。 |
東京都の場合は『 JP 13 』で表す。 |
| 市区町村 |
JIS X 0402 に準拠すること。 |
東京都千代田区の場合は『 101 』で表す。 |
| 地名 |
地名等の英語表記規程 |
国土交通省が定める地名の英語表記。 |
| 経緯度 |
API で提供する場合は、地理空間情報（緯度経度データを含む）は GeoJSON の形式で提供することが望ましく、経緯度データはWGS84 （米国世界測地系）に変換して格納することを推奨するRFC7946 「 The GeoJSON Format 」で、 GeoJSON は WGS84 に準拠することを明記）。 |
東京都千代田区永田町 2 丁目 3 1 は、WGS84 で『 35.672947,139.742622 』と表す。 |
| 単位 |
ISO/IEC 80000 に記載のある国際単位系に準拠すること。 |
メートルは『 m eter 』、グラムは『 g ra m 』、アンペアは『 ampere 』と表す。 |
| 文字 |
JIS X 0213 |
JIS 第 4 水準までの 1 万文字。この範囲内で記述する |
2022年5月5日
| 標準 |
内容 |
| RFC 7231 |
HTTPレスポンスに設定するステータスコード |
| RFC 7807 |
「 Problem Details for HTTP APIs 」で は、次の
内容を含むレスポンスを返却することが推奨されている。 |
| UTF 8 |
インタネットの標準的な文字符号化。 |
|
