VERSION 1.0.0 MANDATORY
Contents
2.1. Introduction
The query interface specification for the Common Services is based on the OASIS ebXML RegRep V4 standard. This standard has multiple protocol bindings that can be used to execute queries. Since the Common Services queries have only simple, single-value parameters, the REST binding is used to implement the query interfaces. This implies that the query transaction is executed as an HTTP GET request with the URL representing the query to execute and the HTTP response carrying the query response as an XML document. This section profiles the REST binding as specified in the OASIS RegRep standard for use by the Common Services.
2.2. The RegRep Query Request
The URL pattern for parameterised query invocation is defined as follows in the OASIS RegRep REST binding:
«server base url»/rest/search?queryId={the query id}(&{param-name}={param-value})*
The query interface consists of a simple predefined parameterised query detailed below. In addition, the RegRep standard defines a set of canonical queries and query parameters that can be used. As the Data Service Diirectory and Evidence Broker are not a complete implementation of a RegRep server, it is NOT REQUIRED to support these canonical queries and query parameters. Clients, therefore, SHOULD only use the queries and query parameters specified by this specification. When the canonical queries or parameters are used, the Common Service implementation MAY return an error.
2.3. The RegRep Successful Response
As specified by the RegRep REST binding, the implemented Common Service MUST always return a RegRep QueryResponse document which MUST either contain an Exception or RegistryObjectList element with zero or more RegistryObjects .
An example response, with response-specific details omitted, is provided in the following table:
<?xml version="1.0" encoding="UTF-8"?>
<query:QueryResponse
xmlns:query="urn:oasis:names:tc:ebxml-regrep:xsd:query:4.0"
xmlns:rim="urn:oasis:names:tc:ebxml-regrep:xsd:rim:4.0"
xmlns:rs="urn:oasis:names:tc:ebxml-regrep:xsd:rs:4.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:sdg="http://data.europa.eu/p4s"
status="urn:oasis:names:tc:ebxml-regrep:ResponseStatusType:Success"
totalResultCount="1"
startIndex="0">
<!-- depending on the count of datasets returned, the totalResultCount attribute should
reflect the number of the datasets returned -->
<rim:RegistryObjectList>
<!-- One registry object per dataset -->
<rim:RegistryObject id="urn:uuid:45c2b94b-5d2b-484b-b6ab-eb542da191cc">
<rim:Slot name="DataServiceEvidenceType">
<rim:SlotValue xsi:type="rim:AnyValueType">
<sdg:DataServiceEvidenceType>
<!-- Omitted for clarity -->
</sdg:DataServiceEvidenceType>
</rim:SlotValue>
</rim:Slot>
</rim:RegistryObject>
</rim:RegistryObjectList>
</query:QueryResponse>
2.4. The RegRep Error Response
When an error occurs during the execution of the query, the Common Service returns an exception as defined in the Common Service Query Interface Specification. The exception has the following properties that are profiled for each expected error of the query.
- xsi:type: The type of the error, selectable from a predefined set of error classes of the Query Interface of the Common Service.
- severity: The severity of the error, selectable from a predefined set of error classes of the Query Interface of the Common Service.
- message: A string describing the error in Human Readable form.
- code: A code for the error, specified by the Common Service Technical Design documents.
- detail: The detail may contain further freely defined information about the error
An Example of a wrong query parameter is provided below:
<?xml version="1.0" encoding="UTF-8"?>
<query:QueryResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:rs="urn:oasis:names:tc:ebxml-regrep:xsd:rs:4.0"
xmlns:rim="urn:oasis:names:tc:ebxml-regrep:xsd:rim:4.0"
xmlns:query="urn:oasis:names:tc:ebxml-regrep:xsd:query:4.0"
xmlns:xlink="http://www.w3.org/1999/xlink"
status="urn:oasis:names:tc:ebxml-regrep:ResponseStatusType:Failure">
<!-- Valid parameter combinations are defined by the DSDErrorResponseCodes (or EBErrorResponseCodes) -->
<!-- The Codelists DSDErrorCodes (and EBErrorCodes) provide the values for xsi:type, message and code - - -->
<!-- The ErrorSeverity provides allowed values for severity. The default value for EB and DSD is "Error". In case of code DSD:ERR:0005 the severity "AdditionalInput" may point to a DSD request that requires additional discovery metadata of the user in order to be answered successfully. -->
<!-- The detail may contain further freely defined information about the error -->
<rs:Exception xsi:type="rs:InvalidRequestExceptionType"
severity="urn:oasis:names:tc:ebxml-regrep:ErrorSeverityType:Error"
message="The query parameters do not follow the query specification"
detail="country-code"
code="DSD:ERR:0003">
</rs:Exception>
</query:QueryResponse>
Depending on the exception raised, the message response may contain information on how to properly recover from the exception. For example, a common service may send back an exception when more attributes are needed to be provided in order for the Common Service to properly respond. These details are further specified in their respective specifications (see 3.1.4 Query Interface Specification of the DSD - section 4.4.3. Query Error Response of the DSD requesting additional User Provided Attributes (DSD:ERR:005). )
2.5 HTTP status code
When returning either a RegRep successful response or a RegRep error response with content as defined in section 2.3 and 2.4 above, servers shall set the HTTP response code to the value 200.
Common service clients shall not use only the HTTP status code to determine the presence of RegRep successful or error responses. As there are situations where the Web infrastructure changes the HTTP status code, and for general reliability, clients shall examine the HTTP response body text if present irrespective of HTTP status code and process accordingly.