ValidationAPI仕様
- 本番環境: https://ddbj.nig.ac.jp/api
- ステージング環境: https://ddbj-staging.nig.ac.jp/api
API 仕様 (swagger)
https://ddbj.nig.ac.jp/api/apispec/index.html
Client
https://ddbj.nig.ac.jp/api/client/index
| メソッド | URL | 説明 | パラメータ | 結果Contents-type | 戻り値 |
|---|---|---|---|---|---|
| POST | /validation | 新規実行要求 | XML files | application/json | ステータス情報 |
| GET | /validation/{:uuid}/status | validationの実行状況を取得 | uuid | application/json | ステータス情報 |
| GET | /validation/{:uuid} | 実行要求したファイルに対する結果を取得 | uuid | application/json | validation結果 |
| GET | /validation/{:uuid}/{filetype} | 既にアップロードしたファイルを取得 | uuid,filetype | text/xml | validationしたXML元ファイル |
| GET | /validation/{:uuid}/{filetype}/autocorrect | Validationの結果に基づいた自動補正後ファイルを取得 | uuid,filetype | text/xml | 補正後XMLファイル |
ValidationAPIでValidation結果として返されるjsonのスキーマを説明します。
{
"uuid": 【リクエスト受付時に発行されたUUID】,
"status": 【Validationの実行状況.終われば"finished"】,
"start_time": 【Validation開始時刻】,
"end_time": 【Validation終了時刻】,
"result":
{
"version": 【Validation実行バージョン】,
"validity": 【Validationの成否.一個でもエラーがあるとfalse, ワーニングだけであればtrue】,
"stats": {}, //後述
"messages": [] //後述
}
}
Validationが検知したエラー(ワーニング)の統計情報。
"stats":
{
"error_count": 【エラーの個数】,
"warning_count": 【ワーニングの個数】,
"error_type_count":【エラーの個数の内訳】
{
"common_error": 【internal_ignoreではないエラーの個数】
"common_warning": 【internal_ignoreではないワーニングの個数】
"external_error": 【internal_ignoreなエラー(内部向けシステムでは無視できる)の個数】
"external_warning": 【internal_ignoreなワーニング(内部向けシステムでは無視できる)の個数】
}
"autocorrect": 【ファイル毎のauto-correctの可否】
{
"biosample": 【BioSampleデータに対してauto-correct出来るものがあるか(true|false)】,
"bioproject": 【BioProjectデータに...(true|false)】,
"submission": 【Submissionデータに...(true|false)】,
"experiment": 【Experimentデータに...(true|false)】,
"run": 【Runデータに...(true|false)】,
"analysis": 【Analysisデータに...(true|false)】
}
}
Validationが検知したエラー(ワーニング)の詳細リスト。
リストの個々の要素にはエラー(ワーニング)になったルール情報の他、"annotation"の配列にはテーブル形式で表示しやすいようにkey-valueでエラーになった箇所が格納される。
補正候補(is_suggest)または、自動補正候補(is_auto_annotation)がある場合には、"annotation"の配列に補正候補や場所(Xpath)等の詳細が追加される。
"messages": [
{
"id":【ルールNo】,
"message":【エラーメッセージ】,
"reference": 【ルールの詳細説明URLの配列】,
"level":【エラーレベル(error|warning)】,
"external":【internal_ignoreかどうかのフラグ(true|false)】,
"method":【validatorの種類(biosample_validator)】,
"object":【関わるobjectの配列(BioSampleは組合せチェックはないため常に["BioSample"])】,
"source":【入力データ(ファイルパス)】,
"annotation": [ //エラー詳細
{
"key":【項目名1】,
"value": "値"
},
{
"key":【項目名2】,
"value": "値"
},
{
"key":【項目名3】,
"value": "値"
},
{ //suggest or auto-annotation
"key":【項目名4】,
"is_suggest": true, //suggestの場合.変更候補が複数ありauto-annotationは出来ないケース. "is_auto_correct"との併用はない
"is_auto_annotation": true, //auto-annotationの場合. "is_suggest"との併用はない
"suggested_value":【候補値のリスト】, //何個か候補がある場合もあるため常に配列.auto_annotationの場合は要素数1.
"target_key":【項目名】, //どの項目の値を修正するか(他の"key"の項目名)
"location":【targetのlocation(XPath, lineNo + columnNo)】//複数箇所を同時に直すケースがあるため配列
}
]
},
{
}
]
D-wayからのValidationAPIを利用する際の留意点を記します。
将来的にはユーザが直接ValidationAPIにアクセスできる予定で、その際にはsubmitter情報は認証情報に埋め込まれる。D-wayからAPIを実行する場合には認証情報を取得する代わりにBioSampleSet要素に"submitter_id"属性を追加する。
またユーザからの直接実行かD-Way(orDDBJ内部利用者)からの実行かで区別するべきルールがあり詳細、その識別のためにBioSampleSet要素に"submission_id"も追記する。
<BioSampleSet submitter_id="user_id" submission_id="SSUB00NNNN">
BioSample以外のfiletypeについては未調整
D-wayのBioSample登録システムからValidationAPIを利用してチェックを行う過程のシーケンス(想定)
APIのAuto-annotation機能は修正後のXMLを返すが、D-way登録時にユーザはXMLを意識していないため、そのままの利用は難しい。
Auto-annotationの情報はValidation結果jsonに埋め込まれていて、補正前、補正後、補正するXpath等の必要事項が記述されているので、パースすればユーザへの提示やDBへの反映は可能。
locationのXpathは何番目のBioSampleのどの位置であるかを示す。
# sample name. SampleName要素とAttributes要素の両方に記述されるため、location配列の要素数は2個になる
[
"//BioSample[0]/Description/SampleName",
"//BioSample[0]/Attributes/Attribute[@attribute_name=\"sample_name\"]"
]
# sample title
["//BioSample[0]/Description/Title"]
# description
["//BioSample[0]/Description/Comment/Paragraph"]
# organism
["//BioSample[0]/Description/Organism/OrganismName"]
# taxonomy_id
["//BioSample[0]/Description/Organism/@taxonomy_id"]
# その他属性
["//BioSample[0]/Attributes/Attribute[@attribute_name=\"{attr_name}\"]"