REST API

1 Using Web Integration Service's 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:

2 API Overview

2.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.

2.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 5 of the Configuration Chapter.

2.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.

2.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.

2.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.

2.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.

2.2 HTTP Requests

Table 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 Sections 3 and 4.

HeaderDescriptionRequired/Optional
Content-TypeIdentifies the content type of the body of the HTTP request. Valid values are:
  • application/dds-web+xml
  • application/dds-web+json
Required (must be application/dds-web+xml for operations other than write and read).
Cache-ControlMust be set to none.Required.
Content-LengthLength of the body of the HTTP request.Required (except for the GET and DELETE requests)
OMG-DDS-API-KeyKey that authorizes the client application for the operation being performed.Required (if authentication is enabled).
Table 1: HTTP Request Headers

2.3 HTTP Responses

Table 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.

HeaderDescription
Content-TypeIdentifies the content type of the body of the HTTP request. Valid values are:
  • application/dds-web+xml
  • application/dds-web+json
Cache-ControlMust be set to none.
Content-LengthLength of the body of the HTTP response.
DateTimestamp of the HTTP response.
Table 2: HTTP Response Headers

Table 3 describes the HTTP status codes and response bodies for all the common operations in case of success, whereas Table 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.

OperationStatus CodeResponse Body
Create204Empty body
Delete204Empty body
List200XML object representation of the requested listing
Enable204Empty body
Write204Empty body
Read200XML or JSON object representation of the samples read
Table 3: HTTP Status Code and Response Body for Successful Operations





Error KindStatus CodeResponse Body
Invalid Input422For application/dds-web+xml requests:
<error>
    <code>ERROR_CODE</code>
    <messsage>Error message</message>
</error>
For application/dds-web+json requests:
{
    "code": "ERROR_CODE",
    "message": "Error message"
}
Generic server error500
DDS error500
​

Table 4: HTTP Status Code and Response Body for Failed Operations

3 Creating, Deleting, Listing, and Updating DDS Entities

Section 2 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.

3.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), QoS Libraries (Table 6), QoS Profiles (Table 7), and Domain Libraries (Table 8).

3.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.



OperationConfiguration
Create TypeHTTP Verb:
POST
URL:
http://##HOST##/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 TypesHTTP Verb:
GET
URL:
http://##HOST##/dds/rest1/types
Preconditions:
  • None
Delete TypeHTTP Verb:
DELETE
URL:
http://##HOST##/dds/rest1/types/{type_name}
Preconditions:
  • The Type must exist.

Table 5: Type Operations

3.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.



OperationConfiguration
Create QoS LibraryHTTP Verb:
POST
URL:
http://##HOST##/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 LibrariesHTTP Verb:
GET
URL:
http://##HOST##/dds/rest1/qos_libraries
Preconditions:
  • None
Delete Qos LibraryHTTP Verb:
DELETE
URL:
http://##HOST##/dds/rest1/qos_libraries/{qos_lib_name}
Preconditions:
  • The QoS library to be deleted must exist.

Table 6: QoS Library Operations



OperationConfiguration
Create QoS ProfileHTTP Verb:
POST
URL:
http://##HOST##/dds/rest1/qos_libraries/{qos_lib_name}/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 ProfilesHTTP Verb:
GET
URL:
http://##HOST##/dds/rest1/qos_libraries/{qos_lib_name}/qos_profiles
Preconditions:
  • The QoS library from which we want to extract the list of contained QoS profiles must exist.
Delete QoS ProfileHTTP Verb:
DELETE
URL:
http://##HOST##/dds/rest1/qos_libraries/{qos_lib_name}/qos_profiles/{qos_profile_name}
Preconditions:
  • The Qos library containing the QoS profile to be deleted must exist.
  • The QoS profile to be deleted must exist.

Table 7: QoS Profile Operations

3.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.



OperationConfiguration
Create Domain LibraryHTTP Verb:
POST
URL:
http://##HOST##/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"
           kind="dynamicData" 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 LibrariesHTTP Verb:
GET
URL:
http://##HOST##/dds/rest1/domain_libraries
Preconditions:
  • None.
Delete Domain LibraryHTTP Verb:
DELETE
URL:
http://##HOST##/dds/rest1/domain_libraries/{domain_library}
Preconditions:
  • The Domain Library to be deleted must exist.

Table 8: Domain Library Operations

3.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 9), DomainParticipants (Table 10), Topics (Table 11), Register Types (Table 12), Publishers (Table 13), Subscribers (Table 14), DataWriters (Table 15), and DataReaders (Table 16).



OperationConfiguration
Create ApplicationHTTP Verb:
POST
URL:
http://##HOST##/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" kind="dynamicData"
        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 ApplicationsHTTP Verb:
GET
URL:
http://##HOST##/dds/rest1/applications
Preconditions:
  • None.
Delete Application
(and its contained entities)		HTTP Verb:
DELETE
URL:
http://##HOST##/dds/rest1/applications/{application}
Preconditions:
  • The Application to be deleted must exist.

Table 9: Application Operations



OperationConfiguration
Create Domain ParticipantHTTP Verb:
POST
URL:
http://##HOST##/dds/rest1/applications/{app_name}/domain_participants
Content-Type:
application/dds-web+xml
Example Body:
<domain_participant name="ShapesDomainParticipant"
      domain_ref="MyDomainLibrary::ShapeDomain"
      domain_id="0">
  <publisher name="MyPublisher">
      <data_writer name="MySquareWriter"
          topic_ref="Square" />
      <data_writer name="MyCircleWriter"
          topic_ref="Circle" />
      <data_writer name="MyTriangleWriter"
          topic_ref="Triangle" />
  </publisher>
</domain_participant>
Preconditions:
  • The Application must exist.
  • There cannot be another DomainParticipant with the same name within the given Application.
List All Domain Participants
within an Application		HTTP Verb:
GET
URL:
http://##HOST##/dds/rest1/applications/{app_name}/domain_participants
Preconditions:
  • The Application from which we want to retrieve the list of contained DomainParticipants must exist.
Delete Domain Participant
(and its contained entities)		HTTP Verb:
DELETE
URL:
http://##HOST##/dds/rest1/applications/{app_name}/domain_participants/{participant_name}
Preconditions:
  • The Application from which we want to delete the DomainParticipant must exist.
  • The DomainParticipant to be deleted must exist.
Enable Domain ParticipantHTTP Verb:
PUT
URL:
http://##HOST##/dds/rest1/applications/{app_name}/domain_participants/{participant_name}
Preconditions:
  • The Application containing the DomainParticipant must exist.
  • The DomainParticipant we want to enable must exist.

Table 10: DomainParticipant Operations


OperationConfiguration
Create TopicHTTP Verb:
POST
URL:
http://##HOST##/dds/rest1/applications/{app_name}/domain_participants/{participant_name}/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
within an DomainParticipant		HTTP Verb:
GET
URL:
http://##HOST##/dds/rest1/applications/{app_name}/domain_participants/{participant_name}/topics
Preconditions:
  • The Application must exist.
  • The DomainParticipant from which we want to retrieve the list of contained Topics must exist.
Delete TopicHTTP Verb:
DELETE
URL:
http://##HOST##/dds/rest1/applications/{app_name}/domain_participants/{participant_name}/topics/{topic_name}
Preconditions:
  • The Application must exist.
  • The DomainParticipant must exist.
  • The Topic must exist.

Table 11: Topic Operations


OperationConfiguration
Register TypeHTTP Verb:
POST
URL:
http://##HOST##/dds/rest1/applications/{app_name}/domain_participants/{participant_name}/registered_types
Content-Type:
application/dds-web+xml
Example Body:
<register_type name="ShapeType" kind="dynamicData"
      type_ref="ShapeType" />
Preconditions:
  • The Application must exist.
  • The DomainParticipant must exist.
  • There cannot be another Type registered with the same name within the given DomainParticipant.
List All Registered Types
within an DomainParticipant		HTTP Verb:
GET
URL:
http://##HOST##/dds/rest1/applications/{app_name}/domain_participants/{participant_name}/registered_types
Preconditions:
  • The Application must exist.
  • The DomainParticipant from which we want to retrieve the list of Registered Types must exist.
Unregister TypeHTTP Verb:
DELETE
URL:
http://##HOST##/dds/rest1/applications/{app_name}/domain_participants/{participant_name}/registered_types/{registered_type_name}
Preconditions:
  • The Application must exist.
  • The DomainParticipant must exist.
  • The Register Type must exist.

Table 12: Register Type Operations



OperationConfiguration
Create PublisherHTTP Verb:
POST
URL:
http://##HOST##/dds/rest1/applications/{app_name}/domain_participants/{participant_name}/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
within a DomainParticipant		HTTP Verb:
GET
URL:
http://##HOST##/dds/rest1/applications/{app_name}/domain_participants/{participant_name}/publishers
Preconditions:
  • The Application must exist.
  • The DomainParticipant from which we want to retrieve the list of Publishers must exist.

Delete Publisher
(and its contained entities)		HTTP Verb:
DELETE
URL:
http://##HOST##/dds/rest1/applications/{app_name}/domain_participants/{participant_name}/publishers/{publisher_name}
Preconditions:
  • The Application must exist.
  • The DomainParticipant from which we want to delete the Publisher must exist.
  • The Publisher must exist.
Enable PublisherHTTP Verb:
PUT
URL:
http://##HOST##/dds/rest1/applications/{app_name}/domain_participants/{participant_name}/publishers/{publisher_name}
Preconditions:
  • The Application must exist.
  • The DomainParticipant containing the Publisher must exist.
  • The Publisher must exist.

Table 13: Publisher Operations



OperationConfiguration
Create SubscriberHTTP Verb:
POST
URL:
http://##HOST##/dds/rest1/applications/{app_name}/domain_participants/{participant_name}/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
within a DomainParticipant		HTTP Verb:
GET
URL:
http://##HOST##/dds/rest1/applications/{app_name}/domain_participants/{participant_name}/subscribers
Preconditions:
  • The Application must exist.
  • The DomainParticipant from which we want to retrieve the list of Subscribers must exist.

Delete Subscriber
(and its contained entities)		HTTP Verb:
DELETE
URL:
http://##HOST##/dds/rest1/applications/{app_name}/domain_participants/{participant_name}/subscribers/{subscriber_name}
Preconditions:
  • The Application must exist.
  • The DomainParticipant from which we want to delete the Subscriber must exist.
  • The Subscriber must exist.
Enable SubscriberHTTP Verb:
PUT
URL:
http://##HOST##/dds/rest1/applications/{app_name}/domain_participants/{participant_name}/subscribers/{subscriber_name}
Preconditions:
  • The Application must exist.
  • The DomainParticipant containing the Subscriber must exist.
  • The Subscriber must exist.

Table 14: Subscriber Operations



OperationConfiguration
Create DataWriterHTTP Verb:
POST
URL:
http://##HOST##/dds/rest1/applications/{app_name}/domain_participants/{participant_name}/publishers/{publisher_name}/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 we want to add the DataWriter to must exist.
  • There cannot be another DataWriter with the same name within the given Publisher.
List All DataWriters
within a Publisher		HTTP Verb:
GET
URL:
http://##HOST##/dds/rest1/applications/{app_name}/domain_participants/{participant_name}/publishers/{publisher_name}/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.
Delete DataWriterHTTP Verb:
DELETE
URL:
http://##HOST##/dds/rest1/applications/{app_name}/domain_participants/{participant_name}/publishers/{publisher_name}/data_writers/{datawriter_name}
Preconditions:
  • The Application must exist.
  • The DomainParticipant must exist.
  • The Publisher from which we want to delete the DataWriter must exist.
  • The DataWriter must exist.
Enable DataWriterHTTP Verb:
PUT
URL:
http://##HOST##/dds/rest1/applications/{app_name}/domain_participants/{participant_name}/publishers/{publisher_name}/data_writers/{datawriter_name}
Preconditions:
  • The Application must exist.
  • The DomainParticipant must exist.
  • The Publisher containing the DataWriter must exist.
  • The DataWriter must exist.

Table 15: DataWriter Operations



OperationConfiguration
Create DataReaderHTTP Verb:
POST
URL:
http://##HOST##/dds/rest1/applications/{app_name}/domain_participants/{participant_name}/subscribers/{subscriber_name}/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 we want to add the DataReader to must exist.
  • There cannot be another DataReader with the same name within the given Subscriber.
List All DataReaders
within a Subscriber		HTTP Verb:
GET
URL:
http://##HOST##/dds/rest1/applications/{app_name}/domain_participants/{participant_name}/subscribers/{subscriber_name}/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.
Delete DataReaderHTTP Verb:
DELETE
URL:
http://##HOST##/dds/rest1/applications/{app_name}/domain_participants/{participant_name}/subscribers/{subscriber_name}/data_readers/{datareader_name}
Preconditions:
  • The Application must exist.
  • The DomainParticipant must exist.
  • The Subscriber from which we want to delete the DataReader must exist.
  • The DataReader must exist.
Enable DataReaderHTTP Verb:
PUT
URL:
http://##HOST##/dds/rest1/applications/{app_name}/domain_participants/{participant_name}/subscribers/{subscriber_name}/data_readers/{datareader_name}
Preconditions:
  • The Application must exist.
  • The DomainParticipant must exist.
  • The Subscriber containing the DataReader must exist.
  • The DataReader must exist.

Table 16: DataReader Operations

4 Writing and Reading Data

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

Table 17 describes write operation of the DataWriter class. Table 18 describes the read operation of the DataReader class.

OperationConfiguration
WriteHTTP Verb:
POST
URL:
http://##HOST##/dds/rest1/applications/{app_name}/domain_participants/{participant_name}/publishers/{publisher_name}/data_writers/{datawriter_name}
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>0xff</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": "0xff",
  "aUnsignedShort": 5,
  "aUnsignedLong": 123456789
}
    Preconditions:
    • The Application must exist.
    • The DomainParticipant must exist.
    • The Publisher must exist.
    • The DataWriter must exist.

    Table 17: Write Operation


    OperationConfiguration
    ReadHTTP Verb:
    GET
    URL:
    http://##HOST##/dds/rest1/applications/{app_name}/domain_participants/{participant_name}/subscribers/{subscriber_name}/data_readers/{datareader_name}
    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".
    • 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 to 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.
    • 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".
    Example Request:
    GET http://##HOST##/dds/rest1/applications/{app_name}/domain_participants/{participant_name}/subscribers/{subscriber_name}/data_readers/?sampleFormat="json"&removeFromReaderCache="false"
    Preconditions:
    • The Application must exist.
    • The DomainParticipant must exist.
    • The Subscriber must exist.
    • The DataReader must exist.
    HTTP Response:
    • Content-Type
      • application/dds-web+xml or
      • application/dds-web+json
    • Body
      The body of the HTTP response includes a sequence of samples read in the requested format. For example:
      • For 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>
          0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
        </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>0xff</anOctet>
      <aUnsignedShort>5</aUnsignedShort>
      <aUnsignedLong>123456789</aUnsignedLong>
    </data>
  </sample>
</read_sample_seq>
      • For Content-Type: application/dds-web+json:
        [
  {
    "read_sample_info":{
      "source_timestamp":{
        "sec":1456962954,
        "nanosec":150101000
      },
      "valid_data":true,
      "Instance_handle":
          "0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0",
      "instance_state":"ALIVE",
      "sample_state":"NOT_READ",
      "view_state":"NEW"
    },
    "data":{
      "aString":"This is a string!",
      "aUnion":{
        "aLongUnion":10
      },
      "aLong":-123456789,
      "aShort":125,
      "anOctet":"0xff",
      "aUnsignedShort":5,
      "aUnsignedLong":123456789
    }
  }
]

    Table 18: Read Operation

    As stated above, the write and read operations support both XML and JSON formats to represent the data samples that are sent and received. Sections 4.1 and 4.2 describe how these representations map to the supported data types.

    4.1 Write Samples XML and JSON Representation

    As described in Table 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 19 describes the representation of a simple ShapeType sample in both XML and JSON format.

    Type DefinitionXML RepresentationJSON 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
}

    Table 19: ShapeType Sample Representation

    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 XML. In JSON, the value is assigned to the member using JSON's native syntax. Table 20 shows the representation of all the supported data types.


    Type DefinitionXML RepresentationJSON Representation
    Structs (top level)
    <data>
  <aLong>0</aLong>
  <aLong>1</aLong>
</data>
    {
  "aLong": 1,
  "aBool":  "true"
}
    Structs (nested)
    <data>
  <anotherStruct>
    <aLong>0</aLong>
    <aLong>1</aLong>
  </anotherStruct>
</data>
    {
  "anotherStruct" : {
      "aLong": 1,
      "aBool":  "true"
  }
}
    Union
    <data>
  <aUnion>
    <aLong>0</aLong>
  </aUnion>
</data>
    {
  "aUnion":{
    "aLong":0
  }
}
    Arrays (simple members)
    <data>
  <anArrayOfLongs>
    <item>1</item>
    <item>2</item>
  </anArray>
</data>
    {
  "anArrayOfLongs" : [
    1,
    2
  ]
}
    Arrays (complex members)
    <data>
  <anArrayOfStructs>
    <item>
      <aFloat>
        0.000000
      </aFloat>
    </item>
    <item>
      <aFloat>
        1.000000
      </aFloat>
    </item>
  </anArrayOfStructs>
</data>
    {
  "anArrayOfStructs": [
    {
      "aFloat": 0.0
    },
    {
      "aFloat": 1.0
    }
  ]
}
    Sequences (simple members)
    <data>
  <aSequenceOfDoubles>
    <item>1.1</item>
    <item>1.2</item>
  </aSequence>
</data>
    {
  "aSequenceOfDoubles" : [
    1.1,
    1.2
  ]
}
    Sequences (complex members)
    <data>
  <aSequenceOfStructs>
    <item>
      <aFloat>
        0.000000
      </aFloat>
    </item>
    <item>
      <aFloat>
        1.000000
      </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>1</anEnum>
</data>
    {
  "anEnum": 1
}
    Longs
    <data>
  <aLong>2452</aLong>
</data>
    {
  "aLong": 2452
}
    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>
</data>
    {
  "aString": "A string!"
}
    Octets
    <data>
  <anOctet>
    0x00
  </anOctet>
</data>
    {
    "anOctet": "0x00"
}
    Chars
    <data>
  <aChar>
    a
  </aChar>
</data>
    {
  "aChar": "a"
}
    WChars
    <data>
  <aWchar>
    0x00000000
  </aWchar>
</data>
    {
  "aWchar": "0x00000000"
}
    Long DoublesUnsupportedUnsupported
    WStringsUnsupportedUnsupported

    Table 20: Sample Representation of Supported Data Types in XML and JSON

    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.

    4.2 Read Samples XML and JSON 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 18 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 20. 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.