We use proprietary and third party's cookies to improve your experience and our services, identifying your Internet Browsing preferences on our website; develop analytic activities and display advertising based on your preferences. If you keep browsing, you accept its use. You can get more information on our Cookie Policy
Cookies Policy
Query Broker Open RESTful API Specification - FIWARE Forge Wiki

Query Broker Open RESTful API Specification

From FIWARE Forge Wiki

Jump to: navigation, search

Contents

Introduction to the REST-Interface of the QueryBroker

Please check the Legal Notice to understand the rights to use FI-WARE Open Specifications.

QueryBroker REST-API Core

The QueryBroker REST-API is a RESTful, resource-oriented API accessed via HTTP that uses XML-based representations for information interchange. It offers a convenient way to manage a QueryBroker instance and to submit complex multi-part and multimodal queries to multiple connected MMRS by sending appropriate MPQF expressions.

Intended Audience

This specification is intended for both software developers and Cloud Providers. For the former, this document provides a specification of how to interoperate with Cloud Platforms that implements the QueryBroker REST API. For the latter, this specification indicates the interface to be provided in order for clients to interoperate with Cloud Platform to provide the described functionalities. To use this information, the reader should firstly have a general understanding of the Media-enhanced Query Broker GE. You should also be familiar with:

API Change History

This version of the QueryBroker REST API Guide replaces and obsoletes all previous versions. The most recent changes are described in the table below:

Revision Date Changes Summary
Apr 24, 2012
  • initial version
July 4, 2012
  • version 0.5
Oct 4, 2012
  • version 0.6
Jan 25, 2013
  • version 0.7
Apr 16, 2013
  • version 0.8
June 26, 2013
  • version 0.9
Sept 13, 2013
  • version 1.0
...
  • ...

How to Read This Document

In the whole document it is taken the assumption that reader is familiarized with REST architecture style. Along the document, some special notations are applied to differentiate some special words or concepts. The following list summarizes these special notations.

  • A bold, mono-spaced font is used to represent code or logical entities, e.g., HTTP method (GET, PUT, POST, DELETE).
  • An italic font is used to represent document titles or some other kind of special text, e.g., URI.
  • The variables are represented between brackets, e.g. {id} and in italic font. When the reader find it, can change it by any value.


For a description of some terms used along this document, see High Level Description of Query Broker GE.

Additional Resources

You can download the most current version of this document from the FIWARE API specification website at the Summary of FI-WARE Open Specifications. For more details about the Media-enhanced Query Broker GE that this API is based upon, please refer to "Architecture Description of Media-enhanced Query Broker GE". Related documents, including an Architectural Description, are available at the same site."

General QueryBroker REST API Information

Resources Summary

Image:QB-REST-API_diagram_R3.png

Authentication

Authentication is currently NOT supported - this feature may be incorporated in the future employing the Access Control GE.

At that time each HTTP request against the QueryBroker will require the inclusion of specific authentication credentials. The specific implementation of this API may support multiple authentication schemes (OAuth, Basic Auth, Token) and will be determined by the specific provider that implements the GE. Please contact them to determine the best way to authenticate against this API. Remember that some authentication schemes may require that the API operate using SSL over HTTP (HTTPS).

Apart from that specific authentication credentials may be required for accessing the registered services (data repositories). These authentication data need to be handled by the service interface, which has to be implemented by any service endpoint and installed at the QueryBroker.

Representation Format

The QueryBroker REST API supports XML based representation formats for both requests and responses, namely MPQF. This is specified by setting the Content-Type header to multipart/form-data, and is required for operations that have a request body. The response format is in the current version MPQF.

Representation Transport

Resource representation is transmitted between client and server by using HTTP 1.1 protocol, as defined by IETF RFC-2616. Each time an HTTP request contains payload, a Content-Type header has to be used to specify the MIME type of the wrapped representation.

Resource Identification

The resource identification used by the API in order to identify unambiguously the resource will be provided over time. For HTTP transport, this is made using the mechanisms described by HTTP protocol specification as defined by IETF RFC-2616.

Links and References

None

Paginated Collections

The MPQF allows the specification of limits on the number of elements to return; if desired it is recommended to use this feature to control/reduce the load on the service(s) as it provides more sophisticated configuration options.

Limits

Please have in mind, that in the current version the processing is done in-memory, i.e. many very large intermediate results delivered simultaneously by the registered data repositories may exhaust the available RAM (min. 1 GB, but 4 GB preferred) causing an fault.

Versions

The current version of the used implementation of the Query Broker GE can be requested by the following HTTP request:

GET http://{ServerRoot}/QueryBrokerServer/version  HTTP/1.1


Faults

Please find below a list of possible fault elements and error codes

Fault ElementAssociated Error CodesDescriptionExpected in All Requests?
POST 400 (“Bad Request”)The document in the entity-body, if any, contains an error message. Hopefully the client can understand the error message and use it to fix the problem. [YES]
POST 404 (“Not Found”)The requested URI doesn’t map to any resource. The server has no clue what the client is asking for. [YES]
POST 500 (“Internal Server Error”)There’s a problem on the server side. The document in the entity-body, if any, is an error message. The error message probably won’t do much good, since the client can’t fix the server problem.[YES]


API Operations

The QueryBroker is implemented as a middleware to establish unified retrieval in distributed and heterogeneous environments with extension functionalities to integrate multimedia specific retrieval paradigms in the overall query execution plan, e.g., multimedia fusion technique. To ensure interoperability between the query applications and the registered database services, the QueryBroker uses as internal query representation format the MPEG Query Format (MPQF). MPQF is an XML-based (multimedia) query language which defines the format of queries and replies to be interchanged between clients and servers in a (multimedia) information search and retrieval environment.

The normative parts of the MPEG Query Format define three main components:

- The Input Query Format provides means for describing query requests from a client to a information retrieval system.
- The Output Query Format specifies a message container for the connected retrieval systems responses and finally
- the Query Management Tools provide means for functionalities such as service discovery, service aggregation and service capability description (e.g.,which query types or formats are supported).

Therefore MPQF can be and is used for managing all essential tasks submitting complex multi-part and multimodal queries to multiple connected data resources, namely

- (de-)register a retrieval system/service,
- creating a semantic link in case of an included join operation, and
- the actual query.

As appropriate MPQF expressions can be lengthy this is done by POST allowing the data to be transmitted in the body of the http request.


Important:

In order to be able to register and access data repositories "data base connectors" or service interfaces need to be implemented. The fully qualified class name (e.g., de.uop.dimis.test.Service) of the implemented service is used as serviceID. Hence, all services which will be registered at the QueryBroker have to be in the classpath of the QueryBroker-Server WAR-file.

A description on how to realize such a service interface is given in QueryBroker GE Installation and Administration Guide.


QueryBroker operations

Welcome page of QueryBroker

Verb URI Description
GET //{serverRoot}/QueryBrokerServer/ Returns a welcome page in html format.


Request example:

GET //localhost/QueryBrokerServer/ HTTP/1.1
Host: localhost:8080
Accept: */*

Response example:

 HTTP/1.1 200 OK
 Content-Length: 8798
 Content-Type: text/xml

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"><html  ...  </html>  

Submit MPQF query

Verb URI Description
POST //{serverRoot}/QueryBrokerServer/query Submit a valid MPQF query (The request body must contain a valid MPQF query in XML serialization.)

Request example:

POST //localhost/QueryBrokerServer/query HTTP/1.1
Host: localhost:8080
Accept: */*
Content-Type:multipart/form-data
Content-Length: 864
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<ns4:mpegQueryType xmlns:ns2="JPSearch:schema:coremetadata" xmlns:ns4="urn:mpeg:mpqf:schema:2008" xmlns:ns3="urn:medico:dicom:schema:2011" mpqfID="quasia_2">
    <ns4:Query>
        <ns4:Input immediateResponse="true">
            <ns4:OutputDescription maxItemCount="32"/>
            <ns4:QueryCondition>
                <ns4:TargetMediaType>image/jpeg</ns4:TargetMediaType>
                <ns4:Condition xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns4:QueryByDescription" matchType="similar" preferenceValue="1.0">
                    <ns4:DescriptionResource resourceID="resource_4">
                        <ns4:AnyDescription>
                            <ns2:ImageDescription>
                                <ns2:Keyword>water</ns2:Keyword>
                            </ns2:ImageDescription>
                        </ns4:AnyDescription>
                    </ns4:DescriptionResource>
                </ns4:Condition>
            </ns4:QueryCondition>
        </ns4:Input>
    </ns4:Query>
</ns4:mpegQueryType> 

Response example:

 HTTP/1.1 200 OK
 Content-Length: 17089
 Content-Type: text/plain;charset=ISO-8859-1

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<mpegQueryType mpqfID="10a38241-3f7b-4540-9152-669669267013" xmlns:ns2="JPSearch:schema:coremetadata" xmlns="urn:mpeg:mpqf:schema:2008" xmlns:ns3="urn:medico:dicom:schema:2011">
    <Query>
        <Input immediateResponse="true">
            <OutputDescription maxItemCount="32"/>
            <QueryCondition>
                <TargetMediaType>image/jpeg</TargetMediaType>
                <Condition xsi:type="QueryByDescription" matchType="similar" preferenceValue="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                    <DescriptionResource resourceID="resource_4">
                        <AnyDescription>
                            <ns2:ImageDescription>
                                <ns2:Keyword>water</ns2:Keyword>
                            </ns2:ImageDescription>                                             </AnyDescription>
                    </DescriptionResource>
                </Condition>
            </QueryCondition>
        </Input>
        <Output>
            <ResultItem confidence="1.0" originID="www.flickr.com" recordNumber="1">
                <Thumbnail fromREF="www.flickr.com">http://farm9.static.flickr.com/8406/8618577025_6f2f98b87f_t.jpg</Thumbnail>
                <MediaResource fromREF="www.flickr.com">http://farm9.static.flickr.com/8406/8618577025_6f2f98b87f.jpg</MediaResource>
                <Description>
                    <ns2:jpSearchCoreType>
                        <ns2:Identifier>http://farm9.static.flickr.com/8406/8618577025_6f2f98b87f.jpg</ns2:Identifier>
                        <ns2:Creators>
                            <ns2:GivenName>hannabergstrom</ns2:GivenName>
                        </ns2:Creators>
                        <ns2:Publisher>
                            <ns2:OrganizationInformation>
                                <ns2:Name>www.flickr.com</ns2:Name>
                            </ns2:OrganizationInformation>
                        </ns2:Publisher>
                        <ns2:CreationDate>2013-03-06T23:36:16.000+01:00</ns2:CreationDate>
                        <ns2:Description></ns2:Description>
                        <ns2:RightsDescription>
                            <ns2:RightsDescriptionInformation>unknown</ns2:RightsDescriptionInformation>
                            <ns2:Description>All Rights Reserved</ns2:Description>
                            <ns2:ActualRightsDescriptionReference>unknown</ns2:ActualRightsDescriptionReference>
                        </ns2:RightsDescription>
                        <ns2:Source>
                            <ns2:SourceElementType>unknown</ns2:SourceElementType>
                            <ns2:SourceElement>
                                <ns2:SourceElementTitle>unknown</ns2:SourceElementTitle>
                                <ns2:SourceElementDescription>unknown</ns2:SourceElementDescription>
                                <ns2:SourceElementIdentifier>unknown</ns2:SourceElementIdentifier>
                            </ns2:SourceElement>
                            <ns2:CreationMethod>unknown</ns2:CreationMethod>
                            <ns2:CreationDescription>www.flickr.com/65051422@N08</ns2:CreationDescription>
                        </ns2:Source>
                        <ns2:Keyword>photograpgy</ns2:Keyword>
                        <ns2:Keyword>blackandwhite</ns2:Keyword>
                        <ns2:Keyword>summer</ns2:Keyword>
                        <ns2:Keyword>water</ns2:Keyword>
                        <ns2:Keyword>analog</ns2:Keyword>
                        <ns2:Title>Family, Gotland</ns2:Title>
                        <ns2:Width>100</ns2:Width>
                        <ns2:Height>100</ns2:Height>
                    </ns2:jpSearchCoreType>
                </Description>
            </ResultItem>
                   :
                   :
 
            <SystemMessage>
                <Status>
                    <Code>1</Code>
                    <Description>Query was successful</Description>
                </Status>
            </SystemMessage>
        </Output>
    </Query>
</mpegQueryType> 

(De-)Register Database

Verb URI Description
POST //{serverRoot}/QueryBrokerServer/services/{serviceID}/{capability}/ Registers the service at the QueryBroker endpoint e.g., /services/de.uop.dimis.FlickrService/QueryByMedia/ (remark: a serviceID is the full qualified class name (e.g., de.uop.dimis.test.Service) of the implemented service.)
POST //{serverRoot}/QueryBrokerServer/services/{serviceID}/CapabilityDescription Registers a 'SQL'-service at the QueryBroker endpoint. Its capability description has to be provided as valid MPQF-query in the body and a configuration file containing credential data for accessing the 'SQL'-service with the name {serviceID}.properties is necessary for that class (available with Release 2).
DELETE //{serverRoot}/QueryBrokerServer/services/{serviceID}/ Deregister the service at the QueryBroker e.g., /services/de.uop.dimis.FlickrService/
GET //{serverRoot}/QueryBrokerServer/services/{capability}/ Service discovery for given capability. Returns a semicolon separated list of all registered services which will handle the given capability. e.g., /services/QueryByMedia/

Request example:

POST //localhost/QueryBrokerServer/services/de.uop.dimis.services.FlickrService/QueryByMedia HTTP/1.1
Host: localhost:8080
Content-Type:multipart/form-data
Accept: */*

Response example:

HTTP/1.1 200 OK
Content-Length: 129
Content-Type: text/plain;charset=ISO-8859-1

Service "de.uop.dimis.services.FlickrService" registered for cability QueryByMedia ("urn:mpeg:mpqf:2008:CS:full:100.3.6.1 ").

Creating a Semantic Link

Verb URI Description
POST //{serverRoot}/QueryBrokerServer/link/{serviceID1}/{linkField1}/{serviceID2}/{linkField2} Registers a semantic link between two registered endpoints.
GET //{serverRoot}/QueryBrokerServer/link/{serviceID1}/{serviceID2} Returns information about the registered semantic link between the given services.

Request example:

POST //localhost/QueryBrokerServer/link/de.uop.dimis.FlickrService/identifier/de.uop.dimis.GoogleService/description/ HTTP/1.1
Host: localhost:8080
Content-Type:multipart/form-data
Accept: */*


Response example:

HTTP/1.1 200 OK
Content-Length: 136
Content-Type: text/plain;charset=ISO-8859-1

de.uop.dimis.FlickrService:identifier and de.uop.dimis.GoogleService:description are now semantically connected

Report version of QueryBroker

Verb URI Description
GET //{serverRoot}/QueryBrokerServer/version Returns the version number and in brackets the version info of the underlying components as a string.

Request example:

GET //localhost/QueryBrokerServer/version HTTP/1.1
Host: localhost:8080
Accept: */*

Response example:

HTTP/1.1 200 OK
Content-Length: 49
Content-Type: text/plain;charset=ISO-8859-1

Release 2.3 (QB: 2.5.8, QB-A: 0.7.1, QB-S: 1.0.0)


Return a concise listing of the RESTful commands

Verb URI Description
GET //{serverRoot}/QueryBrokerServer/help Returns a concise listing of the RESTful commands for controlling the QueryBroker.

Request example:

GET //localhost/QueryBrokerServer/help HTTP/1.1
Host: localhost:8080
Accept: */*

Response example:

HTTP/1.1 200 OK
Content-Length: 2093
Content-Type: text/plain;charset=ISO-8859-1


 Supported commands (always use "Content-Type: multipart/form-data" as header information):

-- registering and deregistering services:

GET: http://localhost:8080/QueryBrokerServer/services/{capability} -- Returns all service adapters that support the given capability.

POST: http://localhost:8080/QueryBrokerServer/services/{service}/{capability} -- Registers the given service with the given capability.

POST: http://localhost:8080/QueryBrokerServer/services/{service}/CapabilityDescription -- Registers the given service with all capabilities that are supplied in the MPQF XML string inside the request body.

DELETE: http://localhost:8080/QueryBrokerServer/services/{service} -- Removes the given service from the list of registered services with all his capabilities.

-- managing semantic links between services:

POST: http://localhost:8080/QueryBrokerServer/link/{serviceid1}/{link1}/{serviceid2}/{link2} -- Creates a semantic link between the two services (which both must be registered beforehand).

GET: http://localhost:8080/QueryBrokerServer/link/{serviceid1}/{serviceid2} -- Displays the semantic link between the two services (which both must be registered beforehand).

-- querying services:

POST: http://localhost:8080/QueryBrokerServer/query -- Sends the query that is supplied in the MPQF XML string inside the request body.

-- miscellaneous information:

GET: http://localhost:8080/QueryBrokerServer/ -- Displays a welcome message.

GET: http://localhost:8080/QueryBrokerServer/help -- Displays this help message.

GET: http://localhost:8080/QueryBrokerServer/version -- Returns the version numbers of the Querybroker, Querybroker-Adapters and Querybroker-Server.

-- further reading:

A complete overview for this service can be found at: http://forge.fi-ware.eu/plugins/mediawiki/wiki/fiware/index.php/Query_Broker_Open_RESTful_API_Specification
Personal tools
Create a book