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
Metadata Preprocessing Open RESTful API Specification - FIWARE Forge Wiki

Metadata Preprocessing Open RESTful API Specification

From FIWARE Forge Wiki

Jump to: navigation, search

Contents

Introduction to the Metadata Preprocessing GE API

Metadata Preprocessing GE API Core

The Metadata Preprocessing GE API is a RESTful, resource-oriented API accessed via HTTP that uses XML-based representations for information interchange.

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

Intended Audience

This specification is intended for both software/application developers and application providers. This document provides a full specification of how to interoperate with the Metadata Preprocessing GE. To use this information, the reader should firstly have a general understanding of the Metadata Preprocessing GE (see Metadata Preprocessing GE Product Vision). You should also be familiar with:

  • RESTful web services,
  • HTTP/1.1,
  • XML data serialization formats.

API Change History

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

Revision Date Changes Summary
May 1, 2012 Initial version
May 16, 2012 Revision of API to support several MDPP instances
Oct 10, 2012 Revision due to internal review
Nov 8, 2012 Revision due to 3rd internal review
Apr 25, 2013 Update for Release 2.2
Sep 27, 2013 Update for Release 3.1
Dec 15, 2013 Update for Release 3.2
Feb 3, 2014 Minor update for deliverable D.6.1.c

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 Metadata Preprocessing GE Architecture.

Additional Resources

You can download the most current version of this document from the FIWARE API specification website at Summary of FI-WARE Open Specifications. For more details about the Metadata Preprocessing GE service that this API is based upon, please refer to Metadata Preprocessing GE Product Vision and Metadata Preprocessing GE Architecture.

General Metadata Preprocessing GE API Information

Resources Summary

The resource summary is shown in the following overview.

Metadata Preprocessing GE (server)
----------------------------------
//{serverRoot}/{assetName}
                  |
                  |--- /version                               GET -> getVersion
                  |
                  |--- /instances/                            GET -> listInstances
                         |                                   POST -> createInstance
                         |
                         |--- {instanceID}                    GET -> getInstanceInfo
                                 |                         DELETE -> destroyInstance
                                 |
                                 |--- ?action=start           PUT -> startInstance
                                 |
                                 |--- ?action=stop            PUT -> stopInstance
                                 |
                                 |--- /config                 GET -> getConfig
                                 |                            PUT -> configureInstance
                                 |
                                 |--- /metadata               GET -> getMetadata
                                 |
                                 |--- /sinks                  GET -> listSinks (removed)
                                        |                    POST -> addSink (removed)
                                        |
                                        |--- /{sinkID}        GET -> getSinkInfo (removed)
                                                           DELETE -> removeSink (removed)

Authentication

Authentication is not supported in the current version of the Metadata Preprocessing GE.

Representation Format

The Multimedia Analysis GE API supports XML-based representation formats for both requests and responses. This is specified by setting the Content-Type header to application/xml, if the request/response has a body. Note: In addition, the Metadata Preprocessing GE API supports XML-based representations for the payload metadata to be processed (i.e., transformed and/or filtered).

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 shall be used to specify the MIME type of wrapped representation. In addition, both client and server may use as many HTTP headers as they consider necessary. Note: In addition, payload metadata is transmitted between the Metadata Preprocessing GE and connected components by using RTP, as defined by IETF RFC-3550. In future versions, resource representation might also be transmitted by using HTTP 1.1 protocol, as defined by IETF RFC-2616.

Resource Identification

The resource identification for HTTP transport is made using the mechanisms described by HTTP protocol specification as defined by IETF RFC-2616.

Links and References

Request forwarding is not supported in the current version of the Metadata Preprocessing GE.

Limits

Limits are not yet identified or specified for the current version of the Metadata Preprocessing GE.

Versions

Querying the version is supported by the getVersion command of the Metadata Preprocessing GE, i.e., by placing the HTTP request "GET //{serverRoot}/mdp/version HTTP/1.1".

Extensions

Querying extensions is not supported in the current version of the Metadata Preprocessing GE.

Faults

Synchronous Faults

Synchronous fault elements and their associated error codes are described in the following table.

Fault Element Error Code Reason Phrase Description Expected in All Requests?
POST, GET, PUT, DELETE 400 Bad Request The client sent a request the server is not able to process. The message body may contain a detailed description of this error. [YES]
POST, GET, PUT, DELETE 404 Not Found The requested URI does not map any resource. [YES]
POST, GET, PUT, DELETE 405 Method Not Allowed The used HTTP method is not allowed for the requested resource. The message body may contain a detailed description of this error. [YES]
POST, GET, PUT, DELETE 500 Internal Server Error An unforeseen error occurred at the server. The message body may contain a detailed description of this error. [YES]

Asynchronous Faults

Asynchronous fault elements are not sent by the current implementation of the Metadata Preprocessing GE.

API Operations

Please note that the XML body of the requests are sent in one line and are only broken into several lines for better readability.

Version

Verb URI Description
GET //{serverRoot}/{assetName}/version getVersion: returns the current version of the Metadata Preprocessing GE realization/asset (e.g., MetadataProcessor)

getVersion

Example:

GET //127.0.0.1/mdp/version HTTP/1.1
Accept: application/xml

Sample result:

HTTP/1.1 200 OK
Content-Type: application/xml

<VersionResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/mdpp.rest.Dto">
  <Version>3.2</Version>
</VersionResponse>

Management of instances

Verb URI Description
GET //{serverRoot}/{assetName}/instances listInstances: lists all instances (i.e., processing units) of the Metadata Preprocessing GE
POST //{serverRoot}/{assetName}/instances createInstance: creates an instance (i.e., a processing unit) of the Metadata Preprocessing GE
DELETE //{serverRoot}/{assetName}/instance/{instanceID} destroyInstance: destroys a specific instance (i.e., processing unit)
PUT //{serverRoot}/{assetName}/instance/{instanceID}?action=start startInstance: starts the processing of the processing unit
PUT //{serverRoot}/{assetName}/instance/{instanceID}?action=stop stopInstance: stops the processing of the processing unit

listInstances

Example:

GET //127.0.0.1/mdp/instances HTTP/1.1
Accept: application/xml

Sample result:

HTTP/1.1 200 OK
Content-Type: application/xml
 
<InstancesResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/mdpp.rest.Dto">
  <Instances>
    <InstanceInfo>
      <Id>0</Id>
      <MetadataUri>rtsp://127.0.0.1:1554/0</MetadataUri>
      <SourceUri>rtsp://127.0.0.1:1554/stream0</SourceUri>
    </InstanceInfo>
  </Instances>
</InstancesResponse>

Other sample result:

HTTP/1.1 200 OK
Content-Type: application/xml

<InstancesResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/mdpp.rest.Dto">
  <Instances />
</InstancesResponse>

createInstance

Example:

POST //127.0.0.1/mdp/instances HTTP/1.1
Accept: application/xml

Sample result:

HTTP/1.1 201 Created
Content-Type: application/xml

<InstancesResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/mdpp.rest.Dto">
  <Instances>
    <InstanceInfo>
      <Id>0</Id>
      <MetadataUri>rtsp://127.0.0.1:1554/0</MetadataUri>
      <SourceUri>rtsp://127.0.0.1:1554/stream0</SourceUri>
    </InstanceInfo>
  </Instances>
</InstancesResponse>

destroyInstance

Example:

DELETE //127.0.0.1/mdp/instances/0 HTTP/1.1
Accept: application/xml

Sample result:

HTTP/1.1 200 OK
Content-Type: application/xml

<ActionResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/mdpp.rest.Dto">
  <Action>Delete</Action>
  <Id>0</Id>
</ActionResponse>

startInstance

Example:

PUT //127.0.0.1/mdp/instances/0?action=start HTTP/1.1
Accept: application/xml

Sample result:

HTTP/1.1 200 OK
Content-Type: application/xml

<ActionResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/mdpp.rest.Dto">
  <Action>Start</Action>
  <Id>0</Id>
</ActionResponse>

stopInstance

Example:

PUT //127.0.0.1/mdp/instances/0?action=stop HTTP/1.1
Accept: application/xml

Sample result:

HTTP/1.1 200 OK
Content-Type: application/xml

<ActionResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/mdpp.rest.Dto">
  <Action>Stop</Action>
  <Id>0</Id>
</ActionResponse>

Configuration of Instances

Verb URI Description
GET //{serverRoot}/{assetName}/instances/{instanceID}/config getConfig: returns the configuration of an existing processing unit
PUT //{serverRoot}/{assetName}/instances/{instanceID}/config configureInstance: configures an existing processing unit
GET //{serverRoot}/{assetName}/instances/{instanceID}/metadata getMetadata: returns metadata URI (i.e., RTSP URL)

getConfig

Example:

GET //127.0.0.1/mdp/instances/0/config HTTP/1.1
Accept: application/xml

Sample result:

HTTP/1.1 200 OK
Content-Type: application/xml
 
<ConfigurationResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/mdpp.rest.Dto">
  <Config>
    <ProcessorCsv2Xml>
      <Enabled>true</Enabled>
      <FieldDelimiter>SEMICOLON</FieldDelimiter>
      <GroupEmptyFields>true</GroupEmptyFields>
      <NumHeaderRows>1</NumHeaderRows>
      <SkipHeaderRows>true</SkipHeaderRows>
      <TextDelimiter>SINGLE_QUOTE</TextDelimiter>
    </ProcessorCsv2Xml>
    <ProcessorXslt>
      <Enabled>false</Enabled>
      <Stylesheet>
        PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPCEtLSBwZXJzb25saXN0LnhtbCB0byBvYmplY3RsaXN0LnhtbCAtLT4KPHhzb
        DpzdHlsZXNoZWV0IHZlcnNpb249IjEuMCIgeG1sbnM6eHNsPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5L1hTTC9UcmFuc2Zvcm0iPgogIDx4c2w6dG
        VtcGxhdGUgbWF0Y2g9Ii9wZXJzb25fbGlzdCI+CiAgICA8b2JqZWN0X2xpc3Q+CiAgICAgIDx4c2w6YXBwbHktdGVtcGxhdGVzIC8+CiAgICA8L29
        iamVjdF9saXN0PgogIDwveHNsOnRlbXBsYXRlPgogIDx4c2w6dGVtcGxhdGUgbWF0Y2g9InBlcnNvbiI+CiAgICA8b2JqZWN0IHR5cGU9InBlcnNv
        biI+CiAgICAgIDxpZD4KICAgICAgICA8eHNsOmFwcGx5LXRlbXBsYXRlcyBzZWxlY3Q9ImlkIiAvPgogICAgICA8L2lkPgogICAgICA8bGFiZWw+C
        iAgICAgICAgPHhzbDphcHBseS10ZW1wbGF0ZXMgc2VsZWN0PSJuYW1lIiAvPgogICAgICA8L2xhYmVsPgogICAgPC9vYmplY3Q+CiAgPC94c2w6dG
        VtcGxhdGU+CjwveHNsOnN0eWxlc2hlZXQ+
      </Stylesheet>
    </ProcessorXslt>
    <SourceURI>rtsp://127.0.0.1:1554/stream0</SourceURI>
  </Config>
  <Id>0</Id>
</ConfigurationResponse>

Please note: for technical reasons the XSLT stylesheet is BASE64 encoded.

configureInstance (XSLT)

The following example demonstrates the configuration of an XSLT transformation, i.e., the transformation of a person list into a more generic object list. In order to configure the Metadata Preprocessing GE, a stylesheet is sent to the GE.

PUT //127.0.0.1/mdp/instances/0/config HTTP/1.1
Content-Type: application/xml
Content-Length: 544
<Configuration xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/mdpp.rest.Dto">
  <Config>
    <ProcessorCsv2Xml>
      <Enabled>false</Enabled>
      <FieldDelimiter>SEMICOLON</FieldDelimiter>
      <GroupEmptyFields>true</GroupEmptyFields>
      <NumHeaderRows>1</NumHeaderRows>
      <SkipHeaderRows>false</SkipHeaderRows>
      <TextDelimiter>SINGLE_QUOTE</TextDelimiter>
    </ProcessorCsv2Xml>
    <ProcessorXslt>
      <Enabled>true</Enabled>
      <Stylesheet>
         Cjw/eG1sIHZlcnNpb249IjEuMCIgZW5jb2Rpbmc9IlVURi04Ij8+CjwhLS0gcGVyc29ubGlzdC54bWwgdG8gb2JqZWN0bGlzdC54bWw
         gLS0+Cjx4c2w6c3R5bGVzaGVldCB2ZXJzaW9uPSIxLjAiIHhtbG5zOnhzbD0iaHR0cDovL3d3dy53My5vcmcvMTk5OS9YU0wvVHJhbn
         Nmb3JtIj4KICA8eHNsOnRlbXBsYXRlIG1hdGNoPSIvcGVyc29uX2xpc3QiPgogICAgPG9iamVjdF9saXN0PgogICAgICA8eHNsOmFwc
         Gx5LXRlbXBsYXRlcyAvPgogICAgPC9vYmplY3RfbGlzdD4KICA8L3hzbDp0ZW1wbGF0ZT4KICA8eHNsOnRlbXBsYXRlIG1hdGNoPSJw
         ZXJzb24iPgogICAgPG9iamVjdCB0eXBlPSJwZXJzb24iPgogICAgICA8aWQ+CiAgICAgICAgPHhzbDphcHBseS10ZW1wbGF0ZXMgc2V
         sZWN0PSJpZCIgLz4KICAgICAgPC9pZD4KICAgICAgPGxhYmVsPgogICAgICAgIDx4c2w6YXBwbHktdGVtcGxhdGVzIHNlbGVjdD0ibm
         FtZSIgLz4KICAgICAgPC9sYWJlbD4KICAgIDwvb2JqZWN0PgogIDwveHNsOnRlbXBsYXRlPgo8L3hzbDpzdHlsZXNoZWV0Pgo=
       </Stylesheet>
     </ProcessorXslt>
     <SourceURI>rtsp://127.0.0.1:1554/stream0</SourceURI>
  </Config>
  <Id>0</Id>
</Configuration>

Please note: for technical reasons the XSLT stylesheet must be BASE64 encoded.

Please note: the “Content-Length” field must be present and set correctly.

Sample result:

HTTP/1.1 200 OK
Content-Type: application/xml
 
<ConfigurationResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance" mlns="http://schemas.datacontract.org/2004/07/mdpp.rest.Dto">
  <Config>
    <ProcessorCsv2Xml>
      <Enabled>false</Enabled>
      <FieldDelimiter>SEMICOLON</FieldDelimiter>
      <GroupEmptyFields>true</GroupEmptyFields>
      <NumHeaderRows>1</NumHeaderRows>
      <SkipHeaderRows>true</SkipHeaderRows>
      <TextDelimiter>SINGLE_QUOTE</TextDelimiter>
    </ProcessorCsv2Xml>
    <ProcessorXslt>
      <Enabled>true</Enabled>
      <Stylesheet>
        PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPCEtLSBwZXJzb25saXN0LnhtbCB0byBvYmplY3RsaXN0LnhtbCAtLT4KPHhzb
        DpzdHlsZXNoZWV0IHZlcnNpb249IjEuMCIgeG1sbnM6eHNsPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5L1hTTC9UcmFuc2Zvcm0iPgogIDx4c2w6dG
        VtcGxhdGUgbWF0Y2g9Ii9wZXJzb25fbGlzdCI+CiAgICA8b2JqZWN0X2xpc3Q+CiAgICAgIDx4c2w6YXBwbHktdGVtcGxhdGVzIC8+CiAgICA8L29
        iamVjdF9saXN0PgogIDwveHNsOnRlbXBsYXRlPgogIDx4c2w6dGVtcGxhdGUgbWF0Y2g9InBlcnNvbiI+CiAgICA8b2JqZWN0IHR5cGU9InBlcnNv
        biI+CiAgICAgIDxpZD4KICAgICAgICA8eHNsOmFwcGx5LXRlbXBsYXRlcyBzZWxlY3Q9ImlkIiAvPgogICAgICA8L2lkPgogICAgICA8bGFiZWw+C
        iAgICAgICAgPHhzbDphcHBseS10ZW1wbGF0ZXMgc2VsZWN0PSJuYW1lIiAvPgogICAgICA8L2xhYmVsPgogICAgPC9vYmplY3Q+CiAgPC94c2w6dG
        VtcGxhdGU+CjwveHNsOnN0eWxlc2hlZXQ+
      </Stylesheet>
    </ProcessorXslt>
    <SourceURI>rtsp://127.0.0.1:1554/stream0</SourceURI>
  </Config>
  <Id>0</Id>
</ConfigurationResponse>

With this configuration, incoming XML metadata is transformed. This is illustrated in the following example, which is kept simple for demonstration purposes.

Example input metadata stream:

<?xml version="1.0" encoding="UTF-8"?>
<person_list>
  <person>
    <id>09</id>
    <name>Guard01</name>
    <status>ClearanceLevel04</status>
  </person>
</person_list>

Example output metadata stream:

<?xml version="1.0" encoding="UTF-8"?>
<object_list>
  <object type="person">
    <id>09</id>
    <label>Guard01</label>
  </object>
</object_list>

As can be seen from the example, the transformation changes the label of the metadata and adds options to the XML elements. Furthermore, some metadata is filtered since it might not be needed by subsequent components.

configureInstance (CSV2XML)

Another configuration option that is supported by the Metadata Preprocessing GE is the transformation from the CSV (comma separated values) format to XML. An example is shown in the following.

PUT //127.0.0.1/mdp/instances/0/config HTTP/1.1
Content-Type: application/xml
Content-Length: 544
<Configuration xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/mdpp.rest.Dto">
  <Config>
    <ProcessorCsv2Xml>
      <Enabled>true</Enabled>
      <FieldDelimiter>COMMA</FieldDelimiter>
      <GroupEmptyFields>true</GroupEmptyFields>
      <NumHeaderRows>1</NumHeaderRows>
      <SkipHeaderRows>false</SkipHeaderRows>
      <TextDelimiter>SINGLE_QUOTE</TextDelimiter>
    </ProcessorCsv2Xml>
    <ProcessorXslt>
      <Enabled>false</Enabled>
      <Stylesheet />
    </ProcessorXslt>
    <SourceURI>rtsp://127.0.0.1:1554/stream0</SourceURI>
  </Config>
  <Id>0</Id>
</Configuration>

Sample result:

HTTP/1.1 200 OK
Content-Type: application/xml
 
<ConfigurationResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance" mlns="http://schemas.datacontract.org/2004/07/mdpp.rest.Dto">
  <Config>
    <ProcessorCsv2Xml>
      <Enabled>ture</Enabled>
      <FieldDelimiter>COMMA</FieldDelimiter>
      <GroupEmptyFields>true</GroupEmptyFields>
      <NumHeaderRows>1</NumHeaderRows>
      <SkipHeaderRows>false</SkipHeaderRows>
      <TextDelimiter>SINGLE_QUOTE</TextDelimiter>
    </ProcessorCsv2Xml>
    <ProcessorXslt>
      <Enabled>false</Enabled>
      <Stylesheet />
    </ProcessorXslt>
    <SourceURI>rtsp://127.0.0.1:1554/stream0</SourceURI>
  </Config>
  <Id>0</Id>
</ConfigurationResponse>

Note that CSV2XML transform and XSLT can be combined by enabling both filters.

getMetadata

Example:

GET //127.0.0.1/mdp/instances/0/metadata HTTP/1.1
Accept: application/xml

Sample result:

HTTP/1.1 200 OK
Content-Type: application/xml
 
<MetadataResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/mdpp.rest.Dto">
  <InstanceId>0</InstanceId>
  <MetadataUri>rtsp://127.0.0.1:1554/0</MetadataUri>
</MetadataResponse>

A metadata sink can connect to the RTSP address in the response.

Personal tools
Create a book