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:
- An API overview (Section 5.1).
- How to create, delete, list, and update DDS entities (Section 5.2).
- How to write and read data (Section 5.3).
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.
| 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.
| 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.
| 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. |
| Error Kind | Status Code | Response Body |
|---|---|---|
| Invalid Input | 422 |
|
| DDS Error/Generic Server Error | 500 |
|
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.
| Operation | Configuration |
|---|---|
| Create a new type |
|
| List All Available Types |
|
| Delete Type |
|
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.
| Operation | Configuration |
|---|---|
| Create a new QoS Library |
|
| List QoS Libraries |
|
| Delete a QoS Library |
|
| Operation | Configuration |
|---|---|
| Create a new QoS Profile |
|
| List QoS Profiles |
|
| Delete a QoS Profile |
|
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.
| Operation | Configuration |
|---|---|
| Create a new Domain Library |
|
| List Domain Libraries |
|
| Delete a Domain Library |
|
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¶
| Operation | Configuration |
|---|---|
| Create a new Application |
|
| List All Applications |
|
| Delete an Application (and its contained entities) |
|
5.2.2.2. DomainParticipants¶
| Operation | Configuration |
|---|---|
| Create a new DomainParticipant |
|
| List All DomainParticipants |
|
| Enable a DomainParticipant |
|
| Delete a DomainParticipant (and its contained entities) |
|
5.2.2.3. Topics¶
| Operation | Configuration |
|---|---|
| Create a new Topic |
|
| List All Topics |
|
| Delete a Topic |
|
5.2.2.4. Register Types¶
| Operation | Configuration |
|---|---|
| Register a new Type |
|
| List All Registered Types |
|
| Unregister a type |
|
5.2.2.5. Publishers¶
| Operation | Configuration |
|---|---|
| Create a new Publisher |
|
| List All Publishers |
|
| Enable a Publisher |
|
| Delete a Publisher (and its contained entities) |
|
5.2.2.6. Subscribers¶
| Operation | Configuration |
|---|---|
| Create a new Subscriber |
|
| List All Subscribers |
|
| Enable a Subscriber |
|
| Delete a Subscriber (and its contained entities) |
|
5.2.2.7. DataWriters¶
| Operation | Configuration |
|---|---|
| Create a new DataWriter |
|
| List All DataWriters |
|
| Enable a DataWriter |
|
| Delete a DataWriter |
|
5.2.2.8. DataReaders¶
| Operation | Configuration |
|---|---|
| Create a new DataReader |
|
| List All DataReaders |
|
| Enable a DataReader |
|
| Delete a DataReader |
|
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.
| Operation | Configuration |
|---|---|
| Write |
|
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.
| 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.
| 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ío miñ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>
E;
</aWchar>
<anotherWchar>
a
</anotherWchar>
</data>
|
{
"aWchar": "\u007E",
"anotherWchar": "a"
}
|
| WStrings | <data>
<aWstring>
A string!
</aWstring>
<anotherWstring>
El río miñ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.
| Operation | Configuration |
|---|---|
| Read |
|
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.