5. REST API

The Configuration and Usage chapters explained how to configure the Web Integration Service server to load a base scenario. This chapter focuses on Web Integration Service’s REST API, which enables client applications to participate as first-class citizens in the DDS Global Data Space.

In particular, this chapter describes:

5.1. API Overview

5.1.1. Common Operations

Web Integration Service’s REST API defines a common set of CRUD-like operations to manipulate DDS entities using HTTP requests. Additionally, Web Integration Service provides operations for sending and receiving data samples using DDS.

Unlike in the common CRUD-like operations, where only XML format is supported, write and read operations can use both XML and JSON format to represent data samples.

5.1.1.1. Create Operations

All DDS entities can be dynamically created given the name of their parent entities and XML representations. Create operations translate to HTTP POST requests, where:

  • The URL identifies the parent entity (e.g., if we are creating a new Publisher, the URL identifies the DomainParticipant it belongs to).
  • The XML representation of the entity to be created. That is, the specific tag from that defines the entity to be created (e.g., the <publisher> tag if we are creating a new Publisher). For more information on entity tags, see Section 3.5.

5.1.1.2. Delete Operations

All DDS entities can be dynamically deleted given their name. Delete operations translate to DELETE HTTP requests, where:

  • The URL identifies the entity to be deleted (e.g., the URL identifying the Publisher we want to delete).
  • The body of the HTTP request is empty.

5.1.1.3. List Operations

This operation returns a list of all the DDS entities under a specific parent. List operations translate to GET HTTP requests, where:

  • The URL identifies the entities to be listed (e.g., all the Publishers under a specific DomainParticipant).
  • The body of the HTTP request is empty.

The subsequent HTTP response returns the list of entities in its body.

5.1.1.4. Enable operation

DDS DomainParticipants, Publishers, Subscribers, DataWriters, and DataReaders can be marked as disabled upon creation. This operation enables a given entity and all of its contained entities. The enable operation is idempotent, so enable operations on already enabled entities will have no effect. Enable operations translate to PUT HTTP requests, where:

  • The URL identifies the entity to be enabled (e.g., the URL identifying a Publisher to be enabled).
  • The body of the HTTP request is empty.

5.1.1.5. Write Operation

DataWriters provide an extra operation that allows users to send data samples represented in XML or JSON format. The write operation translates to a POST HTTP request, where:

  • The URL identifies the DataWriter that is going to write the sample.
  • The body of the HTTP request contains the XML or JSON representation of the sample to be sent.

5.1.1.6. Read Operation

DataReaders provide an extra operation that allows users to receive sequences of data samples in the corresponding DDS DataReader’s cache. The read operation translates to an HTTP GET operation, where:

  • The URL identifies the DataReader that performs the read operation.
  • Different query strings to customize the read operation.
  • The body of the HTTP request is empty.

The body of the subsequent HTTP response contains a sequence of data samples read by the DDS DataReader.

5.1.2. HTTP Requests

Table 5.1 lists all the HTTP headers required in HTTP requests. The body of the different HTTP requests that realize the operations defined by the REST API are described in Section 5.2 and Section 5.3.

Table 5.1 HTTP Request Headers
Header Description Required/Optional
Content-Type Identifies the content type of the body of the HTTP request. Valid values are application/dds-web+xml and application/dds-web+json. Required (must be application/dds-web+xml for operations other than write and read).
Cache-Control Must be set to none. Required.
Content-Length Length of the body of the HTTP request. Required (except for the GET and DELETE requests)
OMG-DDS-API-Key Key that authorizes the client application for the operation being performed. Required (if authentication is enabled).

5.1.3. HTTP Responses

Table 5.2 lists the common HTTP response headers. These can be found in every response generated by Web Integration Service, regardless of the success or failure of the operation.

Table 5.2 HTTP Response Headers
Header Description
Content-Type Identifies the content type of the body of the HTTP response. Valid values are: application/dds-web+xml and application/dds-web+json.
Cache-Control Must be set to none.
Content-Length Length of the body of the HTTP response.
Date Timestamp of the HTTP response.

Table 5.3 describes the HTTP status codes and response bodies for all the common operations in case of success, whereas Table 5.4 describes the HTTP responses in case of failure. Note that every response will include a short Reason Phrase indicating the success or failure of the operation.

Table 5.3 HTTP Status Code and Response Body for Successful Operations
Operation Status Code Response Body
Create 204 Empty body
Delete 204 Empty body
List 200 XML object representation of the requested listing.
Enable 204 Empty body
Write 204 Empty body
Read 200 XML or JSON object representation of the samples read.
Table 5.4 HTTP Status Code and Response Body for Failed Operations
Error Kind Status Code Response Body
Invalid Input 422
For application/dds-web+xml requests:
<error>
    <code>INVALID_INPUT</code>
    <messsage>Error message</message>
</error>
For application/dds-web+json requests:
{
    "code": "INVALID_INPUT",
    "messsage": "Error message"
}
DDS Error/Generic Server Error 500
For application/dds-web+xml requests:
<error>
    <code>GENERIC_SERVER_ERROR</code>
    <messsage>Error message</message>
</error>
For application/dds-web+json requests:
{
    "code": "GENERIC_SERVER_ERROR",
    "messsage": "Error message"
}

5.2. Creating, Deleting, Listing, and Updating DDS Entities

Section 5.1 provided a high-level overview of the different operations that Web Integration Service’s REST API provides. This section describes the complete set of operations that can be performed on each DDS entity.

The list of supported DDS entities is divided into two categories: Resource Entities and Application Entities.

5.2.1. Resource Entities

We use the term resource entities for DDS entities within a Web Integration Service scenario that can be shared across applications. For example, DomainParticipants from different applications can be created with the same QoS Profile. Therefore, resource entities can be treated as templates that can be used in the instantiation of applications and their contained entities.

The list of resource entities includes Types (Table 5.5), QoS Libraries (Table 5.6), QoS Profiles (Table 5.7), and Domain Libraries (Table 5.8).

5.2.1.1. Types

The <types> tag represents a library of types. That is, is a collection of data types specified in XML that can be used across applications.

Table 5.5 Type Operations
Operation Configuration
Create a new type
HTTP Verb
POST
URL
http://<host>[:<port>]/dds/rest1/types
Content-Type
application/dds-web+xml
Example Body
<types>
    <const name="MAX_COLOR_LEN" type="long" value="128"/>
    <struct name="ShapeType">
        <member name="color" type="string"
                stringMaxLength="128" key="true"/>
        <member name="x" type="long"/>
        <member name="y" type="long"/>
        <member name="shapesize" type="long"/>
    </struct>
</types>
Preconditions
There cannot be any Types with the same name in the system.
List All Available Types
HTTP Verb
GET
URL
http://<host>[:<port>]/dds/rest1/types
Preconditions
None.
Delete Type
HTTP Verb
DELETE
URL
http://<host>[:<port>]/dds/rest1/types/<tn>
Preconditions
The Type must exist.

5.2.1.2. QoS Libraries and QoS Profiles

A QoS Library is a collection of QoS profiles and/or QoS settings—specified in XML format—that can be used across applications.

Table 5.6 QoS Library Operations
Operation Configuration
Create a new QoS Library
HTTP Verb
POST
URL
http://<host>[:<port>]/dds/rest1/qos_libraries
Content-Type
application/dds-web+xml
Example Body
<qos_library name="qosLibrary">
    <qos_profile name="defaultProfile" is_default_qos="true">
        <participant_qos>
            <resource_limits>
                <type_code_max_serialized_length>
                  32000
                </type_code_max_serialized_length>
                <type_object_max_serialized_length>
                 32000
                </type_object_max_serialized_length>
            </resource_limits>
        </participant_qos>
    </qos_profile>
</qos_library>
Preconditions
There cannot be any QoS library with the same name in the system.
List QoS Libraries
HTTP Verb
GET
URL
http://<host>[:<port>]/dds/rest1/qos_libraries
Preconditions
None.
Delete a QoS Library
HTTP Verb
DELETE
URL
http://<host>[:<port>]/dds/rest1/qos_libraries/<ql>
Preconditions
The QoS Library to be deleted must exist.
Table 5.7 QoS Profile Operations
Operation Configuration
Create a new QoS Profile
HTTP Verb
POST
URL
http://<host>[:<port>]/dds/rest1/qos_libraries/<ql>/qos_profiles
Content-Type
application/dds-web+xml
Example Body
<qos_profile name="defaultProfile" is_default_qos="true">
    <participant_qos>
        <resource_limits>
            <type_code_max_serialized_length>
              32000
            </type_code_max_serialized_length>
            <type_object_max_serialized_length>
             32000
            </type_object_max_serialized_length>
        </resource_limits>
    </participant_qos>
</qos_profile>
Preconditions
  • The QoS Library to which the QoS Profile will be added must exist.
  • There cannot be another QoS profile with the same name within the given QoS library.
List QoS Profiles
HTTP Verb
GET
URL
http://<host>[:<port>]/dds/rest1/qos_libraries/<ql>/qos_profiles
Preconditions
The QoS library from which we want to extract the list of contained QoS profiles must exist.
Delete a QoS Profile
HTTP Verb
DELETE
URL
http://<host>[:<port>]/dds/rest1/qos_libraries/<ql>/qos_profiles/<qp>
Preconditions
  • The Qos library containing the QoS profile to be deleted must exist.
  • The QoS profile to be deleted must exist.

5.2.1.3. Domain Libraries

Domain Libraries provide a way to organize a set of domains that belong to the same system. Domain Libraries can be shared across applications.

Table 5.8 Domain Library Operations
Operation Configuration
Create a new Domain Library
HTTP Verb
POST
URL
http://<host>[:<port>]/dds/rest1/domain_libraries
Content-Type
application/dds-web+xml
Example Body
<domain_library name="MyDomainLibrary">
  <domain name="ShapeDomain" domain_id="0">
      <register_type name="ShapeType" type_ref="ShapeType"/>
      <topic name="Square" register_type_ref="ShapeType" />
      <topic name="Circle" register_type_ref="ShapeType" />
      <topic name="Triangle" register_type_ref="ShapeType" />
  </domain>
</domain_library>
Preconditions
There cannot be another Domain Library with the same name in the system.
List Domain Libraries
HTTP Verb
GET
URL
http://<host>[:<port>]/dds/rest1/domain_libraries
Preconditions
None.
Delete a Domain Library
HTTP Verb
DELETE
URL
http://<host>[:<port>]/dds/rest1/domain_libraries/<dl>
Preconditions
The Domain Library to be deleted must exist.

5.2.2. Application Entities

We use the term application entities for all the DDS entities that are instantiated within the context of an Application. For example, in Web Integration Service, DomainParticipants are application entities, since they belong to a specific Application and are instantiated upon creation.

The list of application entities includes Applications (Table 5.9), DomainParticipants (Table 5.10), Topics (Table 5.11), Register Types (Table 5.12), Publishers (Table 5.13), Subscribers (Table 5.14), DataWriters (Table 5.15), and DataReaders (Table 5.16).

5.2.2.1. Applications

Table 5.9 Application Operations
Operation Configuration
Create a new Application
HTTP Verb
POST
URL
http://<host>[:<port>]/dds/rest1/applications
Content-Type
application/dds-web+xml
Example Body
<application name="ShapesDemo">
    <domain_participant name="ShapesDomainParticipant"
            domain_id="0">
        <register_type name="ShapeType" type_ref="ShapeType" />
        <topic name="Square" register_type_ref="ShapeType" />
        <publisher name="ShapesPublisher"/>
    </domain_participant>
</application>
Preconditions
There cannot be another Application with the same name in the system.
List All Applications
HTTP Verb
GET
URL
http://<host>[:<port>]/dds/rest1/applications
Preconditions
None.
Delete an Application (and its contained entities)
HTTP Verb
DELETE
URL
http://<host>[:<port>]/dds/rest1/applications/<a>
Preconditions
The Application to be deleted must exist.

5.2.2.2. DomainParticipants

Table 5.10 DomainParticipant Operations
Operation Configuration
Create a new DomainParticipant
HTTP Verb
POST
URL
http://<host>[:<port>]/dds/rest1/applications/<a>/domain_participants
Content-Type
application/dds-web+xml
Example Body
<domain_participant name="ShapesDomainParticipant"
        domain_id="0">
    <register_type name="ShapeType" type_ref="ShapeType" />
    <topic name="Square" register_type_ref="ShapeType" />
    <publisher name="ShapesPublisher"/>
</domain_participant>
Preconditions
  • The Application must exist.
  • There cannot be another DomainParticipant with the same name within the given Application.
List All DomainParticipants
HTTP Verb
GET
URL
http://<host>[:<port>]/dds/rest1/applications/<a>/domain_participants
Preconditions
The Application from which we want to retrieve the list of contained DomainParticipants must exist.
Enable a DomainParticipant
HTTP Verb
PUT
URL
http://<host>[:<port>]/dds/rest1/applications/<a>/domain_participants/<dp>
Preconditions
  • The Application containing the DomainParticipant must exist.
  • The DomainParticipant to be enabled must exist.
Delete a DomainParticipant (and its contained entities)
HTTP Verb
DELETE
URL
http://<host>[:<port>]/dds/rest1/applications/<a>/domain_participants/<dp>
Preconditions
  • The Application from which we want to delete the DomainParticipant must exist.
  • The DomainParticipant to be deleted must exist.

5.2.2.3. Topics

Table 5.11 Topic Operations
Operation Configuration
Create a new Topic
HTTP Verb
POST
URL
http://<host>:[:<port>]/dds/rest1/applications/<a>/domain_participants/<dp>/topics
Content-Type
application/dds-web+xml
Example Body
<topic name="Square" register_type_ref="ShapeType"/>
Preconditions
  • The Application must exist.
  • The DomainParticipant must exist.
  • There cannot be another Topic registered with the same name in within the given DomainParticipant.
List All Topics
HTTP Verb
GET
URL
http://<host>[:<port>]/dds/rest1/applications/<a>/domain_participants/<dp>/topics
Preconditions
  • The Application must exist.
  • The DomainParticipant from which we want to retrieve the list of contained Topics must exist.
Delete a Topic
HTTP Verb
DELETE
URL
http://<host>[:<port>]/dds/rest1/applications/<a>/domain_participants/<dp>/topics/<t>
Preconditions
  • The Application must exist.
  • The DomainParticipant must exist.
  • The Topic must exist.

5.2.2.4. Register Types

Table 5.12 Register Type Operations
Operation Configuration
Register a new Type
HTTP Verb
POST
URL
http://<host>:[:<port>]/dds/rest1/applications/<a>/domain_participants/<dp>/registered_types
Content-Type
application/dds-web+xml
Example Body
<register_type name="ShapeType" type_ref="ShapeType" />
Preconditions
  • The Application must exist.
  • The DomainParticipant must exist.
  • There cannot be another type registered with the same name in within the given DomainParticipant.
List All Registered Types
HTTP Verb
GET
URL
http://<host>[:<port>]/dds/rest1/applications/<a>/domain_participants/<dp>/registered_types
Preconditions
  • The Application must exist.
  • The DomainParticipant from which we want to retrieve the list of Registered Types must exist.
Unregister a type
HTTP Verb
DELETE
URL
http://<host>[:<port>]/dds/rest1/applications/<a>/domain_participants/<dp>/registered_types/<rt>
Preconditions
  • The Application must exist.
  • The DomainParticipant must exist.
  • The Registered Type must exist.

5.2.2.5. Publishers

Table 5.13 Publisher Operations
Operation Configuration
Create a new Publisher
HTTP Verb
POST
URL
http://<host>[:<port>]/dds/rest1/applications/<a>/domain_participants/<dp>/publishers
Content-Type
application/dds-web+xml
Example Body
<publisher name="publisherName"/>
Preconditions
  • The Application must exist.
  • The DomainParticipant must exist.
  • There cannot be another Publisher with the same name within the given DomainParticipant.
List All Publishers
HTTP Verb
GET
URL
http://<host>[:<port>]/dds/rest1/applications/<a>/domain_participants/<dp>/publishers
Preconditions
  • The Application must exist.
  • The DomainParticipant from which we want to retrieve the list of Publishers must exist
Enable a Publisher
HTTP Verb
PUT
URL
http://<host>[:<port>]/dds/rest1/applications/<a>/domain_participants/<dp>/publishers/<p>
Preconditions
  • The Application must exist.
  • The DomainParticipant must exist.
  • The Publisher to be enabled must exist.
Delete a Publisher (and its contained entities)
HTTP Verb
DELETE
URL
http://<host>[:<port>]/dds/rest1/applications/<a>/domain_participants/<dp>/publishers/<p>
Preconditions
  • The Application must exist.
  • The DomainParticipant must exist.
  • The Publisher to be deleted must exist.

5.2.2.6. Subscribers

Table 5.14 Subscriber Operations
Operation Configuration
Create a new Subscriber
HTTP Verb
POST
URL
http://<host>[:<port>]/dds/rest1/applications/<a>/domain_participants/<dp>/subscribers
Content-Type
application/dds-web+xml
Example Body
<subscriber name="subscriberName"/>
Preconditions
  • The Application must exist.
  • The DomainParticipant must exist.
  • There cannot be another Subscriber with the same name within the given DomainParticipant.
List All Subscribers
HTTP Verb
GET
URL
http://<host>[:<port>]/dds/rest1/applications/<a>/domain_participants/<dp>/subscribers
Preconditions
  • The Application must exist.
  • The DomainParticipant from which we want to retrieve the list of Subscribers must exist
Enable a Subscriber
HTTP Verb
PUT
URL
http://<host>[:<port>]/dds/rest1/applications/<a>/domain_participants/<dp>/subscribers/<s>
Preconditions
  • The Application must exist.
  • The DomainParticipant must exist.
  • The Subscriber to be enabled must exist.
Delete a Subscriber (and its contained entities)
HTTP Verb
DELETE
URL
http://<host>[:<port>]/dds/rest1/applications/<a>/domain_participants/<dp>/subscribers/<s>
Preconditions
  • The Application must exist.
  • The DomainParticipant must exist.
  • The Subscriber to be deleted must exist.

5.2.2.7. DataWriters

Table 5.15 DataWriter Operations
Operation Configuration
Create a new DataWriter
HTTP Verb
POST
URL
http://<host>[:<port>]/dds/rest1/applications/<a>/domain_participants/<dp>/publishers/<p> /data_writers
Content-Type
application/dds-web+xml
Example Body
<data_writer name="SquareWriter" topic_ref="Square"/>
Preconditions
  • The Application must exist.
  • The DomainParticipant must exist.
  • The Publisher must exist.
  • There cannot be another DataWriter with the same name within the given Publisher.
List All DataWriters
HTTP Verb
GET
URL
http://<host>[:<port>]/dds/rest1/applications/<a>/domain_participants/<dp>/publishers/<p> /data_writers
Preconditions
  • The Application must exist.
  • The DomainParticipant must exist.
  • The Publisher from which we want to retrieve the list of DataWriters must exist
Enable a DataWriter
HTTP Verb
PUT
URL
http://<host>[:<port>]/dds/rest1/applications/<a>/domain_participants/<dp>/publishers/<p> /data_writers/<dw>
Preconditions
  • The Application must exist.
  • The DomainParticipant must exist.
  • The Publisher must exist.
  • The DataWriter to be enabled must exist.
Delete a DataWriter
HTTP Verb
DELETE
URL
http://<host>[:<port>]/dds/rest1/applications/<a>/domain_participants/<dp>/publishers/<p> /data_writers/<dw>
Preconditions
  • The Application must exist.
  • The DomainParticipant must exist.
  • The Publisher must exist.
  • The DataWriter to be deleted must exist.

5.2.2.8. DataReaders

Table 5.16 DataReader Operations
Operation Configuration
Create a new DataReader
HTTP Verb
POST
URL
http://<host>[:<port>]/dds/rest1/applications/<a>/domain_participants/<dp>/subscribers/<s> /data_readers
Content-Type
application/dds-web+xml
Example Body
<data_reader name="SquareReader" topic_ref="Square"/>
Preconditions
  • The Application must exist.
  • The DomainParticipant must exist.
  • The Subscriber must exist.
  • There cannot be another DataReader with the same name within the given Subscriber.
List All DataReaders
HTTP Verb
GET
URL
http://<host>[:<port>]/dds/rest1/applications/<a>/domain_participants/<dp>/subscribers<s> /data_readers
Preconditions
  • The Application must exist.
  • The DomainParticipant must exist.
  • The Subscriber from which we want to retrieve the list of DataReaders must exist
Enable a DataReader
HTTP Verb
PUT
URL
http://<host>[:<port>]/dds/rest1/applications/<a>/domain_participants/<dp>/subscribers/<s> /data_readers/<dr>
Preconditions
  • The Application must exist.
  • The DomainParticipant must exist.
  • The Subscriber must exist.
  • The DataReader to be enabled must exist.
Delete a DataReader
HTTP Verb
DELETE
URL
http://<host>[:<port>]/dds/rest1/applications/<a>/domain_participants/<dp>/subscribers/<s> /data_readers/<dr>
Preconditions
  • The Application must exist.
  • The DomainParticipant must exist.
  • The Subscriber must exist.
  • The DataReader to be deleted must exist.

5.3. Writing and Reading Data

Section 5.2 described all the CRUD-like operations that Web Integration Service’s REST API provides. This section focuses on the write and read operations.

5.3.1. Writing Data

5.3.1.1. Write Operation

Table 5.17 describes the write operation of the DataWriter class.

Table 5.17 Write Operation
Operation Configuration
Write
HTTP Verb
POST
URL
http://<host>[:<port>]/dds/rest1/applications/<a>/domain_participants/<dp>/publishers/<p> /data_writers/<dw>
Content-Type
application/dds-web+xml or application/dds-web+json
Example Body

For Content-Type: application/dds-web+xml

<data>
    <aString>This is a string!</aString>
    <aLong>-123456789</aLong>
    <aShort>125</aShort>
    <anOctet>255</anOctet>
    <aUnsignedShort>5</aUnsignedShort>
    <aUnsignedLong>123456789</aUnsignedLong>
</data>

For Content-Type: application/dds-web+json

{
  "aString": "This is a string!",
  "aLong": -123456789,
  "aShort": 125,
  "anOctet": 255,
  "aUnsignedShort": 5,
  "aUnsignedLong": 123456789
}
Preconditions
  • The Application must exist.
  • The DomainParticipant must exist.
  • The Publisher must exist.
  • The DataWriter must exist.

5.3.1.2. XML and JSON Sample Representation

As described in Table 5.17, the write operation requires sending an XML or JSON representation of the sample in the body of the POST request. This sample representation is an instantiation of the data type associated with the topic the DataWriter sends. Table 5.18 describes the representation of a simple ShapeType sample in both XML and JSON format.

Table 5.18 ShapeType Sample Representation
Type Definition XML Representation JSON Representation
<struct name="ShapeType">
  <member name="color" key="true"
    type="string"/>
  <member name="x" type="long" />
  <member name="y" type="long" />
  <member name="shapesize" type="long" />
</struct>
<data>
  <color>BLUE</color>
  <x>20</x>
  <y>30</y>
  <shapesize>
    3
  </shapesize>
</data>
{
  "color": "BLUE",
  "x": 20,
  "y": 30,
  "shapesize": 3
}

All the different XML tags and JSON members are named after the members they represent. In XML, the value assigned becomes a child of the appropriate XM tag. In JSON, the value is assigned to the member using JSON’s native syntax. Table 5.19 shows the representation of all the supported data types.

Table 5.19 Sample Representation of Supported Data Types in XML and JSON
Type Definition XML Representation JSON Representation
Structs (top level)
<data>
  <aLong>1</aLong>
  <aBoolean>true</aBoolean>
</data>
{
  "aLong": 1,
  "aBoolean":  true
}
Structs (nested)
<data>
  <anotherStruct>
    <aLong>1</aLong>
    <aBoolean>true</aBoolean>
  </anotherStruct>
</data>
{
  "anotherStruct" : {
      "aLong": 1,
      "aBoolean":  true
  }
}
Union (top level)
<data>
  <aLong>1</aLong>
</data>
{
  "aLong":1
}
Union (nested)
<data>
  <aBoolean>true</aBoolean>
  <aUnion>
    <aLong>1</aLong>
  </aUnion>
</data>
{
  "aBoolean": true,
  "aUnion":{
    "aLong":1
  }
}
Arrays (simple members)
<data>
  <anArrayOfLongs>
    <item>1</item>
    <item>2</item>
  </anArrayOfLongs>
</data>
{
  "anArrayOfLongs" : [
    1,
    2
  ]
}
Arrays (complex members)
<data>
  <anArrayOfStructs>
    <item>
      <aFloat>
        0.0
      </aFloat>
    </item>
    <item>
      <aFloat>
        1.0
      </aFloat>
    </item>
  </anArrayOfStructs>
</data>
{
  "anArrayOfStructs": [
    {
      "aFloat": 0.0
    },
    {
      "aFloat": 1.0
    }
  ]
}
Sequences (simple members)
<data>
  <aSequenceOfDoubles>
    <item>1.1</item>
    <item>1.2</item>
  </aSequenceOfDoubles>
</data>
{
  "aSequenceOfDoubles" : [
    1.1,
    1.2
  ]
}
Sequences (complex members)
<data>
  <aSequenceOfStructs>
    <item>
      <aFloat>
        0.0
      </aFloat>
    </item>
    <item>
      <aFloat>
        1.0
      </aFloat>
    </item>
  </aSequenceOfStructs>
</data>
{
  "aSequenceOfStructs": [
    {
      "aFloat": 0.0
    },
    {
      "aFloat": 1.0
    }
  ]
}
Shorts
<data>
  <aShort>3</aShort>
</data>
{
  "aShort": 3
}
Unsigned Shorts
<data>
  <aUShort>2</aUShort>
</data>
{
  "aUShort": 2
}
Enums
<data>
  <anEnum>ACE</anEnum>
</data>
{
  "anEnum": "ACE"
}
Enums (Using enumsAsIntegers option)
<data>
  <anEnum>1</anEnum>
</data>
{
  "anEnum": 1
}
Longs
<data>
  <aLong>2452</aLong>
</data>
{
  "aLong": 2452
}
Unsigned Longs
<data>
  <aULong>245</aULong>
</data>
{
  "aULong": 245
}
Long Longs
<data>
  <aLongLong>
    23121
  </aLongLong>
</data>
{
  "aLongLong": 23121
}
Unsigned Long Longs
<data>
  <aULongLong>
    2345212
  </aULongLong>
</data>
{
  "aULongLong": 2345212
}
Floats
<data>
  <aFloat>
    2.3
  </aFloat>
</data>
{
  "aFloat": 2.3
}
Doubles
<data>
  <aDouble>
    3.14
  </aDouble>
</data>
{
  "aDouble": 3.14
}
Booleans
<data>
  <aBoolean>
    false
  </aBoolean>
  <anotherBoolean>
    true
  </anotherBoolean>
</data>
{
  "aBoolean": false,
  "anotherBoolean": true
}
Strings
<data>
  <aString>
    A string!
  </aString>
  <anotherString>
    El r&#x00ED;o mi&#x00F1;o
  </anotherString>
</data>
{
  "aString": "A string!",
  "anotherString": "El r\u00EDo mi\u00F1o"
}
Octets
<data>
  <anOctet>
    255
  </anOctet>
</data>
{
    "anOctet": 255
}
Chars
<data>
  <aChar>
    a
  </aChar>
</data>
{
  "aChar": "a"
}
WChars
<data>
  <aWchar>
    &#007E;
  </aWchar>
  <anotherWchar>
    a
  </anotherWchar>
</data>
{
  "aWchar": "\u007E",
  "anotherWchar": "a"
}
WStrings
<data>
  <aWstring>
    A string!
  </aWstring>
  <anotherWstring>
    El r&#x00ED;o mi&#x00F1;o
  </anotherWstring>
</data>
{
  "aWstring": "A string!",
  "anotherWstring": "El r\u00EDo mi\u00F1o"
}
Long Doubles Unsupported Unsupported

In XML, the parser ignores the root tag’s name. As a convention, we use the <data> tag to name it, but users may choose a different convention (e.g., they can choose to name the top-level tag after the data type that is being set). In JSON, the top-level tag is an object that may contain objects, arrays, and other members.

Unset members are automatically set to zero. As a result, DataReaders will receive a complete sample with all the unset members set to zero. In contrast, invalid members will cause a parsing error, which will trigger the cancellation of the write operation and an error HTTP response.

5.3.2. Reading Data

5.3.2.1. Read Operation

Table 5.20 describes the read operation of the DataReader class.

Table 5.20 Read Operation
Operation Configuration
Read
HTTP Verb
GET
URL
http://<host>[:<port>]/dds/rest1/applications/<a>/domain_participants/<dp>/subscribers/<s> /data_readers/<dr>
URL Query Parameters
  • sampleFormat—Optional query parameter to indicate what format should be used to represent the read samples. The sampleFormat parameter can be set to either "xml" or "json". If unspecified, it defaults to "xml".
  • prettyPrint—Optional query parameter to indicate whether the response should contain indentations and line breaks. If unspecified, it defaults to false.
  • enumsAsIntegers—Optional query parameter to indicate whether the response should represent enumeration literals as integers. If unspecified, it defaults to false.
  • removeFromReaderCache—Optional query parameter indicating whether the samples should be removed from the DataReader’s cache (equivalent to DDS’ take operation) or left in the cache (equivalent to DDS’ read operation). The removeFromReaderCache parameter can be set to "true" or "false". If unspecified, it defaults to "true", meaning that the samples are removed from the DataReader’s cache.
  • maxSamples—Optional query parameter indicating the maximum number of samples to retrieve. It unspecified, it defaults to unlimited.
  • maxWait—Optional query parameter indicating the willingness of the caller to wait a certain number of seconds until the conditions to read data are met. If unspecified, it defaults to zero seconds (i.e., maxWait=0).
  • filterExpression—Optional query parameter indicating a DDS SQL filter expression that is used to create a DDS QueryCondition. When used along with the read and take operations, this QueryCondition allows us to generate a list of samples that match it.</li>
  • instanceStateMask—Optional query parameter to obtain samples that match the desired instance states. The values that can be used in the mask are: "ALIVE", "NOT_ALIVE_DISPOSED", and "NOT_ALIVE_NO_WRITERS". For example, a valid instanceStateMask would be "ALIVE|NOT_ALIVE_DISPOSED".
  • sampleStateMask—Optional query parameter to obtain samples that match the desired sample states. The values that can be used in the mask are "READ" and "NOT_READ".
  • viewStateMask—Optional query parameter to obtain samples that match the desired view states. The values that can be used in the mask are "NEW" or "NOT_NEW".
Preconditions
  • The Application must exist.
  • The DomainParticipant must exist.
  • The Subscriber must exist.
  • The DataReader must exist.
Example Request
GET /dds/rest1/applications/<a>/domain_participants/<dp>/subscribers/<s>
/data_readers/<dr>?sampleFormat="json"&removeFromReaderCache="false" HTTP/1.1
Host: <host>[:<port>]
HTTP Response

The body of the HTTP response includes a sequence of samples read in the requested format. For example:

  • Content-Type: application/dds-web+xml
    <read_sample_seq>
        <sample>
            <read_sample_info>
                <source_timestamp>
                    <sec>1456957176</sec>
                    <nanosec>207723000</nanosec>
                </source_timestamp>
                <valid_data>true</valid_data>
                <instance_handle>
                  00000000000000000000000000000000
                </instance_handle>
                <instance_state>
                  ALIVE
                </instance_state>
                <sample_state>
                  NOT_READ
                </sample_state>
                <view_state>NEW</view_state>
            </read_sample_info>
            <data>
                <aString>This is a string!</aString>
                <aLong>-123456789</aLong>
                <aShort>125</aShort>
                <anOctet>255</anOctet>
                <aUnsignedShort>5</aUnsignedShort>
                <aUnsignedLong>123456789</aUnsignedLong>
            </data>
        </sample>
    </read_sample_seq>
    
  • Content-Type: application/dds-web+json

    [
        {
            "read_sample_info":{
              "source_timestamp":{
                "sec":1456962954,
                "nanosec":150101000
              },
              "valid_data":true,
              "Instance_handle":
                  "00000000000000000000000000000000",
              "instance_state":"ALIVE",
              "sample_state":"NOT_READ",
              "view_state":"NEW"
            },
            "data":{
              "aString":"This is a string!",
              "aUnion":{
                "aLongUnion":10
              },
              "aLong":-123456789,
              "aShort":125,
              "anOctet":255,
              "aUnsignedShort":5,
              "aUnsignedLong":123456789
            }
        }
    ]
    

5.3.2.2. XML and JSON Sample Representation

A successful read operation generates a response that includes a sequence of samples read in its body. The sequence is represented in XML or JSON format, depending on the value of the sampleFormat query parameter (if set). Table 5.20 shows example responses both in XML and JSON format.

Every sample contains a metadata section (i.e., the read sample info) and data section (i.e., the sample data itself). The data section contains the sample itself following the same syntax depicted in Table 5.19. The metadata section contains the following information for the sample that has been read:

  • source_timestamp—Shows the timestamp when the sample was written by a DataWriter.
  • valid_data—Indicates whether the data sample contains data or if is only used to communicate a change in the instance_state of the instance.
  • instance_handle—Identifies locally the corresponding instance.
  • instance_state—Indicates whether or not the samples are from a live DataWriter.
  • sample_state—Indicates whether or not a sample has ever been read.
  • view_state—Indicates whether or not an instance is new.