Application Programming Interface

---

Introduction

This API allows to retrieve daily validation results from our databases. It describes a web service which can be called via HTTP POST with a JSON body, and returns a JSON output. The URL for the web service is:

https://voparis-validation-reports.obspm.fr/validation/api_v1

Input Format

To retrieve validation results for several ivoids

{
	"action": "query_services",
	"mode": "multiple_ivoids",
	"protocol": "ConeSearch"|"SIA"|"SSA"|"TAP"|"EPN-TAP"|"SIAv2"|"all",
	"ivoids" : ["array","of","ivoids"]
}

To retrieve validation results by ivoid substring

{
	"action": "query_services",
	"mode": "ivoid_substring",
	"protocol": "ConeSearch"|"SIA"|"SSA"|"TAP"|"EPN-TAP"|"SIAv2"|"all",
	"ivoid_substring": "substring (at least 3 characters)"
}

Optional input parameters

"include_aux_services": "yes"|"no" => "yes" to include all services, not only those with "aux" in capability's standard_id. Default is "no".
"vot_ok": "yes"|"no"|""|"all"  => to only include services with valid/invalid/no result VOT. Default is "all".
"spec_ok": "yes"|"no"|""|"all" => to only include services with valid/invalid/no result Specification. Default is "all".

Notes:

• vot_ok and spec_ok conditions are combined with AND.
• Specifying vot_ok = "all" and spec_ok="all" will return all services.

To retrieve validation results and error details

Same as above, but add suffix _errors to the action parameter.

Output Format

{
    "status": "OK"|"ERROR"
    "msg": "error msg in case of status=ERROR",
    "date_val_min": "YYY-MM-DD", => minimum validation date used
    "nb_services": N, => nb of services found
    "services": [
        {
            "protocol" : "protocol of the service: ConeSearch|SIA|SSA|TAP|EPN-TAP|SIAv2",
            "ivoid": "ivoid of the service",
            "url": "url of the service",
            "title": "title of the service",
            "short_name": "short name of the service",
            "date": "validation date used",
            "vot_ok": "yes"|"no"|"",  => was the VOTable returned by the service valid /invalid /no result ?
            "spec_ok": "yes"|"no"|"", => was the service compliant/not compliant/no result with its protocol specification ?
            "nb_fatal": "N", => nb of fatal errors found
            "nb_err": "N", => nb of errors found
            "nb_warn": "N", => nb of warnings found
            "nb_fail": "N", => nb of failures found
            "days_same": "N", => nb of days for which the above results did not change
            "standard_id": "standard id of the service"
            "validation_url": "a validation URL that can be used to check for errors"
            "errors": [ => if input action ends with "_errors" a errors section is available with all the errors found for the service
                {
                    "type": "warning"|"error",
                    "num": "N", => sequence number of error
                    "name": "error name",
                    "msg": "error message",
                    "section": "test section where error found"
                },
                ...
        },
        ...
    ]
 }

Examples

Retrieve validation results and error details for several ivoids

$ curl -d '{ "action": "query_services_errors", "mode": "multiple_ivoids", "protocol": "TAP", "ivoids" : ["ivo://org.gavo.dc/tap","ivo://org.gavo.dc/gcpms/q/data"] }' https://voparis-validation-reports.obspm.fr/validation/api_v1

Retrieve validation results by ivoid substring

$ curl -d '{ "action": "query_services", "mode": "ivoid_substring", "protocol": "ConeSearch", "ivoid_substring": "gavo.dc" }' https://voparis-validation-reports.obspm.fr/validation/api_v1

Retrieve validation results and error details by ivoid substring, for all protocols, return all services including #aux ones

$ curl -d '{ "action": "query_services", "mode": "ivoid_substring", "protocol": "all", "ivoid_substring" : "gavo.dc", "include_aux_services":"yes" }' https://voparis-validation-reports.obspm.fr/validation/api_v1

Retrieve validation results by ivoid substring, for all protocols

$ curl -d '{ "action": "query_services", "mode": "ivoid_substring", "protocol": "all", "ivoid_substring" : "gavo.dc" }' https://voparis-validation-reports.obspm.fr/validation/api_v1