Introduction to the

iDirect Web Service

Interface

Revision B

November 16, 2017

Copyright © 2017 VT iDirect, Inc. All rights reserved. Reproduction in whole or in part without permission is
prohibited. Information contained herein is subject to change without notice. The specifications and information
regarding the products in this document are subject to change without notice. All statements, information, and
recommendations in this document are believed to be accurate, but are presented without warranty of any kind,
express, or implied. Users must take full responsibility for their application of any products. Trademarks, brand
names and products mentioned in this document are the property of their respective owners. All such references
are used strictly in an editorial fashion with no intent to convey any affiliation with the name or the product's
rightful owner.

Document Name: IntroductionToWebService RevA.docx

ii Introduction To iDirect Web Service Interface

 Revision History

The following table shows all prior revisions of the document.

Revision Date Authors Reason for Change(s)

0.1 DRAFT 2012-12-13 C Bradford Initial Introduction to Web Service Document

0.1 DRAFT 2012-11-02 Guy Adams Initial Web Service Standards document
Ivan Miletic
Tom Najdek
0.2 DRAFT 2012-11-16 Ivan Miletic Web Service Standards Work-in-progress document:
Tom Najdek
 Resource relations
 Non-CRUD operations
 File Upload
 Use cases
0.3 DRAFT 2012-11-20 Milosz Chmura Work-in-progress document:
Ivan Miletic
 Web Service Standards Streaming
Tom Najdek
 Adding/Removing relations
 Major re-formatting
1.0 DRAFT 2012-11-27 Milosz Chmura Web Service Standards Final document recommendation:
Tom Najdek
 Streaming
 Non-fatal errors
 Consistency fixes
 Adding/Removing relations
 Applied template, major re-formatting
1.1 DRAFT 2012-12-11 Tom Najdek Web Service Standards added ‘in’ filter

0.2 DRAFT 2013-05-05 J Orgren Merge with Web Service Standards

A 2013-08-12 J Orgren Initial Release

B 2017-11-16 N Naisbitt Updates for Pulse API 2.0

Introduction To iDirect Web Service Interface iii

 Disclaimer

While iDirect, Inc. strives to make the information in this document as accurate as possible, iDirect
makes no claims, promises, or guarantees about the accuracy, completeness, or adequacy of the
contents, and expressly disclaims liability for errors and omissions. No warranty of any kind, whether
implied, expressed, or statutory, including but not limited to the warranties of non-infringement of
third party rights, title, merchantability, or fitness for a particular purpose, is given with respect to the
contents of this document.
iDirect, Inc. reserves the right to change or update this document at any time.

iv Introduction To iDirect Web Service Interface

 Contents

Revision History ................................................................... iii

Disclaimer .......................................................................... iv

Contents .............................................................................v

List of Tables ..................................................................... viii

About ................................................................................ ix
Purpose ..................................................................................................... ix
Audience ................................................................................................... ix
Contents .................................................................................................... ix
iDirect Documents ........................................................................................ ix
Standards References.................................................................................... ix
Document Conventions ................................................................................... x

1 The Web Service Interface .............................................. 1

1.1 When to Use the Web Service ................................................................. 1
1.2 Locating the Web Service Endpoint .......................................................... 1
1.3 Overview of the API ............................................................................. 1

2 Request Format ............................................................ 2

2.1 Request Versions ................................................................................ 2
2.2 Authentication ................................................................................... 2
2.3 Request Verbs .................................................................................... 2

Introduction To iDirect Web Service Interface v

2.4 Request Headers ................................................................................. 3

3 Response Status Codes ................................................... 4

4 Request/Response Data Format ........................................ 6

4.1 Sample Responses ............................................................................... 6
4.2 Standard Formatting ............................................................................ 7

5 Resource Relations ........................................................ 8

6 GET Request Filtering/Searching ...................................... 10

6.1 Searching for a Resource Instance via Unique ID ......................................... 10
6.2 Searching for Resource Instances via Complex Filter.................................... 10

7 Executing Actions on Resources ....................................... 12

8 File Uploads ............................................................... 14

8.1 Single File REST Upload........................................................................ 14
8.2 Multi-Part File Upload.......................................................................... 14

9 Use Cases .................................................................. 18

9.1 Adding/Removing Relations ................................................................... 18

10 Streaming Model with WebSocket..................................... 20

10.1 Establishing Connection ....................................................................... 20
10.1.1 User-Requested Streaming .......................................................................... 20
10.1.2 Two-way Handshake .................................................................................. 20
10.2 Detailed Explanation of Web Service Handshake ......................................... 21
10.3 WebSocket Protocol ............................................................................ 21
10.3.1 Message Format ........................................................................................ 22
10.3.1 Message Payload ....................................................................................... 22
10.3.2 Message Headers ....................................................................................... 22
10.4 Streaming Requests ............................................................................ 22
10.4.1 GET Streaming Request ............................................................................... 22
10.4.2 POST Streaming Request – not supported in 4.0 ................................................ 23
10.4.2.1 For Verbose Output ................................................................................... 23
10.4.2.2 For Non-Verbose Output ............................................................................. 23
10.4.3 PUT/PATCH Streaming Request – not supported in 4.0 ....................................... 23

vi Introduction To iDirect Web Service Interface

10.4.3.1 For Verbose Output ................................................................................... 24
10.4.3.2 For Non-Verbose Output ............................................................................. 24
10.4.4 DELETE Streaming Request – not supported in 4.0............................................. 24
10.5 Error Messages .................................................................................. 25
10.5.1 Error 500 ................................................................................................ 25
10.5.2 Error 501 ................................................................................................ 25
10.5.3 Other Errors ............................................................................................. 25
10.5.4 Non-Fatal Errors........................................................................................ 25
10.6 Ping/Pong ......................................................................................... 26
10.7 Heartbeats ....................................................................................... 26

Introduction To iDirect Web Service Interface vii

 List of Tables

Table 1: Request Verbs ................................................................................................. 3

Table 2: Request Headers .............................................................................................. 3
Table 3: Response Status Codes ....................................................................................... 4
Table 4: Middle-End Exceptions ....................................................................................... 5
Table 5: Standard Formatting ......................................................................................... 7
Table 6: Filter Operators ............................................................................................. 10

viii Introduction To iDirect Web Service Interface

 About

Purpose
This document is an introduction to the iDirect system web service interface. It explains when the web
service interface should be used, and an overview of how to use it. Detailed descriptions of the
methods available in the web service are available in other documentation. All system-wide iDX web
services are based on common use cases and best-practices of the REST architecture.

Audience
The intended audience for this document is a system engineering team responsible for interfacing with
iDirect hub (NMS) or remote systems.

Contents
The document contains the following chapters and appendices:
 The Web Service Interface
 Request Format
 Response Status Codes
 Request/Response Data Format
 Resource Relations
 GET Request Filtering/Searching
 Executing Actions on Resources
 File Uploads
 Use Cases
 Streaming Model with WebSocket

iDirect Documents

Standards References
 http://tools.ietf.org/html/rfc6455

Introduction To iDirect Web Service Interface ix

 Document Conventions
This section illustrates and describes the conventions used throughout the manual. Please review the
conventions before using this document, to better understand how to interpret the presented
information.
Convention Description Example
Used when the user is required to Enter the command:
Blue Courier
enter a command at a command line cd /etc/snmp/
font
prompt or in a console.

Courier font Used when showing resulting output

from a command that was entered crc report all
at a command line or on a console. 3100.3235 : DATA CRC [ 1]
3100.3502 : DATA CRC [5818]
3100.4382 : DATA CRC [ 20]

Bold Trebuchet font Used when referring to text that
appears on the screen on a
windows-type Graphical User
Interface (GUI).
Used when specifying names of
commands, menus, folders, tabs,
dialogs, list boxes, and options.
1. To add a remote to an inroute group,
right-click the Inroute Group and select
Add Remote.
The Remote dialog box has a number of
user selectable tabs across the top. The
Information tab is visible when the dialog
box opens.

Used to show all hyperlinked text

 Blue Trebuchet  For instructions on adding a transmit
within a document.
font line card to the network tree and
selecting a Hub RFT for the line card,
see “Adding a Transmit Line Card” on
page 108.
Used to emphasize information for
Bold italic the user, such as in notes.
Note: Only real-time and Get Past
Trebuchet font requests are saved in workspace
files.

Used when the user needs to strictly

Red italic follow the instructions or have
CAUTION: The following procedure
Trebuchet font additional knowledge about a may cause a network outage.
procedure or action.

Used for front panel labels

Copperplate STATUS
Bold Font

x Introduction To iDirect Web Service Interface

1 The Web Service
Interface
This chapter contains the following sections:
 When to Use the Web Service
 Locating the Web Service Endpoint
 Overview of the API
The iDirect system provides a RESTful interface over HTTPS. This interface abstracts many of the
complexities of the iDirect system, and presents a straightforward interface.

1.1 When to Use the Web Service

The Web service interface provides a highly featured interface into the iDirect system. It aims to hide
the complexity of the distributed iDirect system platform, and provide a simple, straightforward
interface for all business processes.
iDirect remotes provide interfaces such as discrete signals and On/Off Key (OOK) signals for real-time
control of RF elements of the terminal. Remotes have historically provided the Console and Systray
interfaces, which are now deprecated in favor of the Web Service. For low-level testing of a remote,
other command-line interfaces may be provided.
The Web Service interface is meant for machine to machine connections. It also provides the
underlying mechanism for the Web GUI (human to machine) interface.

1.2 Locating the Web Service Endpoint

The Web Service endpoint will be running on the HTTPS port (443) on a well-known IP address. This IP
address is a virtual address, and so will not change if the iDirect system cluster moves the web service
process from one physical server to another.

1.3 Overview of the API

The web service API follows REST principles, using HTTP methods as verbs. Reading data is performed
using HTTP GET methods. Creating new resources is performed using HTTP POST, and updating
resources uses the HTTP PUT method. Where a single resource is addressed, the ID of the resource is
part of the URI (uniform resource identifier). Where a query is being performed that may return more
than one resource, HTTP query parameters are used to describe the query.
All resources are described using JSON (JavaScript Object Notation) encoding.
The Pulse NMS API provides self documenting endpoints using the OPTIONS and PROPFIND Verbs.

Introduction To iDirect Web Service Interface 1

2 Request Format
This chapter contains the following sections:
 Request Versions
 Authentication
 Request Verbs
 Request Headers
The Web Service framework expects REST requests with the following format.
HTTP/1.1 <verb> /api/<version>/<resource_path>
<header1>
<header2>
…

2.1 Request Versions

The Pulse NMS API supports several versions;
1.0 Is the primary interface and all resoruces are available on that endpoint.
1.1 is an updated interface limited to improvements in statistics and DDE resources.
2.0 is an updated interface limited to improvements in the config resource.
Minor version updates retain full backwards compatibility with previous Major version.
Major version changes do not guarantee to be 100% compatible with the previous version

2.2 Authentication
Clients authenticate to the iDirect system using a username and password. This is passed in every
request to the service, as an HTTP Basic authentication header.
The username, a colon, and the password should be concatenated. This string should then be base64
encoded. The string “Basic” and a space is prepended to the resulting string, and this is used as the
value in an “Authorization” header that is passed along with the request.
For example, if the username is “test”, and the password is “password”, then the authentication
header will be:
Authorization: Basic dGVzdDpwYXNzd29yZA==
This header should be sent with every request. A request without the header, or with an incorrect
username/password combination, will be rejected.

2.3 Request Verbs

The table below contains all the REST verbs supported by the Web Service framework. Not every verb
is applicable to every resource.

2 Introduction To iDirect Web Service Interface

 Table 1: Request Verbs
Name Description
GET Used to read/query a resource. Individual resources may be queried by specifying its unique
id, or multiple instances may be queries using complex queries specified in the URI.

This is a read-only operation, and thus does not change the visibility or state of the resource.
POST Adds new instance of a resource.

Posting multiple times will usually result in multiple items being created.
PUT Sends an update of a uniquely identified resource where the ENTIRE resource is contained
within a message. Missing fields are assumed nulls.

Putting multiple times attempts to change the same resource over and over again and will
always result in the same outcome.
PATCH Sends a partial update of a uniquely identified resource. Missing fields are assumed
unchanged.

Patching multiple times attempts to change the same resource over and over again and will
always result in the same outcome.
DELETE Removes an instance of a uniquely identified resource.

Deleting multiple times attempts to remove the same resource over and over again and will
always result in the same outcome.
OPTIONS Returns detailed descriptions on resource actions. Not applicable to Pulse NMS API 2.0
PROPFIND Returns detailed descriptions on resource actions. Applicable only to Pulse NMS API 2.0

PUT vs. PATCH

Both verbs update a resource instance, with one major difference. PUT completely replaces the entire
instance with the passed data, while PATCH only updates properties specified in the request.

2.4 Request Headers

The table below contains all the headers supported in iDX 4.0. Currently only headers regarding
request/response body formatting are supported.
Table 2: Request Headers
Name Description Example
Content-type In requests, specifies the MIME type of the request Content-
body. Applicable to POST, PUT and PATCH verbs. type:application/json
In responses, specifies the MIME type of the response
body.

Note: Only JSON is supported in iDX 4.0.

XML support is planned for iDX 4.1.
Accept Used in requests to specify the MIME type of the Accept:application/json
response body acceptable by the client. Applicable to
all verbs.

Note: Only JSON is supported in iDX 4.0 with

exception for file upload/download.
Other formats might be added in iDX 4.1.

Introduction To iDirect Web Service Interface 3

3 Response Status Codes
The Web Service framework can automatically respond with one of the following status codes. The
status codes are divided into three categories:
 2xx – success codes
 4xx – errors on the client side, e.g. the request is invalid
 5xx – errors on the server side
The below table lists all currently supported respond codes with their appropriate error cases.
Table 3: Response Status Codes
Error case Status Error Title
code
- 200 Ok
- 201 OK, Created
Incorrectly formatted requests, non-existing 400 Bad Request
path/prefix/resource name etc.
User not authorized. 401 Unauthorized
403 Forbidden
Resource instance not found when querying by unique 404 Not Found
ID.
REST verb not allowed on resource. 405 Method Not Allowed

The response MUST include an Allow header containing

a list of valid methods for the requested resource.
Server not able to format the requested resource 406 Not Acceptable
instance in the MIME type specified in the Accept
header.
Server doesn’t support MIME type of request body 415 Unsupported Media Type
specified in Content-type header.

Too many requests have been made to the system. This 429 Too Many Requests
can be used for request throttling.
Uncaught exceptions in the Middle-End. 500 Internal Server Error
The requested function isn’t supported. 501 Unsupported

In the case of an Error Status, the response body may contain additional error messages in the
following format.
"errors":[
{
"message": "<error message>", // the text of the error
"code": <error code>, // a unique number
"source": "BE", // Back End, “FE” Front End, or “ME” Middle
End
"silent": false, // or true if this error is not for
display in the GUI

4 Introduction To iDirect Web Service Interface

 "severity": "MAJOR" // or “MINOR”
}
]
Middle-End exceptions
When the Web Service framework catches a Middle-End exception, it will return a HTTP 500 return
code with details about the exception in the response body. The table below contains standardized
error messages for common errors.
Table 4: Middle-End Exceptions
Error case Error messages
Invalid filter in complex query Server error: Filter <filter_name> not
supported.
Unsupported operator used in complex query Server error: Operator <op> not supported
by filter <filter_name>

Config API 2.0 Developer Info

When the Pulse NMS API 2.0 Web Service framework detects a minor error in the request, but one that
does not fail the request, then it may respond with an ‘info’ field in the meta section of the response
payload. This serves a useful source of information for developers.

Introduction To iDirect Web Service Interface 5

4 Request/Response Data
Format
This chapter contains the following sections:
 Sample Responses
 Standard Formatting
Requests and responses are in JSON format, shown in the following examples.

4.1 Sample Responses

The response will contain a data key that is an array of found objects and might contain optional
‘meta’ and ‘errors’ keys. The Meta key might contain ‘count’, ‘next’ and ‘previous’ keys when paging.
In API 2.0 it may also contain an ‘info’ key to warn developers of potential mistakes in the query.
Errors will contain any non-fatal errors if applicable.
{
“data”: [],
“meta”:{
"count": 0,
"next”:"",
"previous:"",
},
"errors": []
}
Explicitly accessing a single item by id will yield a response that contains ‘data’ key representing the
fetched object and optionally might contain ‘meta’ key with additional sub-resources or actions
available for this object.
{
“data”: {},
“meta”:{
"url": "",
“actions”:[]
},
"errors": []
}

6 Introduction To iDirect Web Service Interface

4.2 Standard Formatting
Non-numerical and string-based values must be identically formatted throughout requests and
responses. The table below provides the formatting standard for each data-type.
Table 5: Standard Formatting
Name Description Example
Date/Time Always represented as numerical Unix/POSIX {
epoch values. Unix time, or POSIX time, is a …
system for describing instances in time, “Timestamp” : 1354320000,
defined as the number of seconds that have …
elapsed since midnight Coordinated Universal }
Time (UTC), 1 January 1970, not counting
leap seconds.
Enumerations Always represented by the textual name of {
the enumerated value. …
“Severity” : “CRITICAL”,
…
}

Introduction To iDirect Web Service Interface 7

5 Resource Relations
Relations may exist between resources, e.g. events may be attached to an alarm. Resource relations
are expressed using simple URIs. Alarms may have attached events; this relation is shown below.
Alarm: {
"ID":60,
<other alarm properties>
“EventSiteIDs”:[
“/api/1.0/dde/event/32/432”,
“/api/1.0/dde/event/32/433”,
“/api/1.0/dde/event/55/434”
],
“AlarmIDs”:[],
“IncidentIDs”:[]
}

8 Introduction To iDirect Web Service Interface

Introduction To iDirect Web Service Interface 9
6 GET Request
Filtering/Searching
This chapter contains the following sections:
 Searching for a Resource Instance via Unique
 Searching for Resource Instances via Complex Filter
Additional filters may be used with GET requests to filter the response data set.

6.1 Searching for a Resource Instance via Unique ID

Accessing a single resource instance by its unique ID can be done with the below request:
GET http://<resource_URI>/<unique_id>
Accept:application/json
The result will be a single resource instance in the format specified in the request by the Accept
header. Accessing a resource instance with an unknown unique ID will result in a 404 Not Found
response. Below is a generic example.
GET http://api/1.0/dde/alarm/5
Accept:application/json

6.2 Searching for Resource Instances via Complex

Filter
Multiple instances may be queried by specifying a complex filter with the format below.
GET http://<resource_URI>?<complex_filter>
Accept:application/json
Complex queries are basically a collection of resource property filters combined together. All filters
are combined by AND. Below is a generic example.
GET http://api/1.0/dde/alarm?Severity=CRITICAL&State=LATCHED
Accept:application/json
Operators may be used with numerical and string properties. See the below table for all available
operators with examples on their use.
Table 6: API 1.x Filter Operators
Name Description Example
Equal eq Returns objects with a http://<URI>?id=100
parameter value equal to http://<URI>?id__eq=100
passed argument.
Greater gt Returns objects with a http://<URI>?id__gt=100
than parameter value greater
than passed argument.
Less than lt Returns objects with a http://<URI>?id__lt=100
parameter value greater
than passed argument.

10 Introduction To iDirect Web Service Interface

 Name Description Example
Contains contains Returns objects with a string http://<URI>?name__contains=terminal
parameter containing a
substring.
Starts with startswith Returns objects with a string http://<URI>?name__startswith=prefix
parameter starting with a
substring.
Ends with endswith Returns objects with a string http://<URI>?name__endswith=suffix
parameter ending with a
substring.
In set in Returns objects where a http://<URI>?id__in=10,25,33,42
property belongs to a set
represented by a comma-
separated list

The result will be a list of resource instances in the format specified in the request by the Accept
header. If no resources instances match the specified filter, an empty list will be returned.
In Config API 2.x Query filters use a more SQL like syntax, with a wildcard character % placed before,
after or before and after the text in the argument. For queries searching for a set, the arguments are
passed as a comma separated list in brackets, e.g. ?id=[10,25,33,42]
Note: The results are returned in pages. Navigating pages is done by specifying the skip and
limit filters in the complex filter. The default values can be overridden on per resource basis.
 skip – how many instances to skip before returning. (Default=0)
 limit – number of instances to return in one page. (Default=20)

The limit is capped by a system wide default, so the total returned will be the lower of the limit
and the system wide cap.

Introduction To iDirect Web Service Interface 11

7 Executing Actions on
Resources
Actions are defined as sub-resources of a higher-level resource. A list of all supported actions will be
returned when querying the higher-level resource. A detailed description of each action can be
retrieved using the OPTIONS verb.
Examples:
GET /~/server/1
Accept: application/json

HTTP 200 OK
Content-type: application/json
{
“data”: [
…
],
“meta”:{
“actions”:[
“/~/server/1/iptables”,
“/~/server/1/reboot”,
“/~/server/1/apply-changes”
]
},
“errors”: <optional non-fatal errors>
}

OPTIONS /~/server/1/reboot
Accept: application/json

HTTP 200 OK
Allow: POST
Content-type:application/json
{
“POST”: {
Description: “Sends TERM signal to all processes and reboots the
server”,
resource_uri: “/~/server/1/iptables”
}

POST /~/server/1/reboot

HTTP 202 ACCEPTED

12 Introduction To iDirect Web Service Interface

OPTIONS /~/server/1/iptables

HTTP 200 OK
Allow: GET, POST, DELETE
Content-type: application/json
{
“GET”: {
description: “List all rules”,
resource_uri: “/~/server/1/iptables”
}
“POST”: {
description:“Append rule from the POST body”,
resource_uri: “/~/server/1/iptables”,
arguments: {
protocol: “The protocol of the rule or of the packet to check. The
specified protocol can be one of tcp, udp, udplite, icmp, esp, ah,
sctp or the special keyword "all", or it can be a numeric
value, representing one of these protocols or a different one.”,
source: “Source specification. Address can be either a network
name, a hostname, a network IP address (with/mask), or a plain IP
address”,
destination: “Destination specification. Address can be either a
network name, a hostname, a network IP address (with/mask), or a
plain IP address”,
…
}
},
“DELETE: {
description:“Drop all current rules”,
resource_uri: “/~/server/1/iptables”
}
}

Introduction To iDirect Web Service Interface 13

8 File Uploads
This chapter contains the following sections:
 Single File REST Upload
 Multi-Part File Upload

8.1 Single File REST Upload

This is a standard approach commonly used by Web Services including Amazon Web Services and
Dropbox.
Example:
GET /~/files/example.txt
Accept: */*

HTTP 404 Not Found

POST /~/files/example.txt
Content-type: text/plain
Hello World!

HTTP 201 Created

GET /~/files/example.txt
Accept: */*

HTTP 200 OK
Content-type: text/plain
Hello World

8.2 Multi-Part File Upload

This approach is not common for REST Web Services, but addresses the requirement of multi-file
upload support.
Example:

POST /~/files/
Content-Length: <length>
Content-Type: multipart/form-data; boundary=----------------8237465289374652

------------------8237465289374652
Content-Length: <length of software.pkg>
Content-Type: application/octet-stream
Content-Disposition: form-data; name=softwarePackage; filename=software.pkg

14 Introduction To iDirect Web Service Interface

Content-Transfer-Encoding: binary

<binary content of software.pkg>

------------------8237465289374652
Content-Length: <length of remote_DID.opt>
Content-Disposition: form-data; name=optionsFile; filename=remote_DID.opt
Content-Type: text/plain
Content-Transfer-Encoding: binary

<binary content of remote_DID.opt>

------------------8237465289374652
Content-Length: <length of bsp.pkg>
Content-Type: application/octet-stream
Content-Disposition: form-data; name=bspPackage; filename=bsp.pkg
Content-Transfer-Encoding: binary

<binary content of bsp.pkg>

------------------8237465289374652--

HTTP 201 Created

Content-type:application/json
{
Data: [
{
filename: “software.pkg”,
size: “<length of software.pkg”>,
type: “application/octet-stream”,
resource_uri: “/~/files/software.pkg”
},
{
filename: “remote_DID.opt”,
size: “<length of remote_DID.opt”>,
type: “text/plain”,
resource_uri: “/~/files/remote_DID.opt”
},
{ … }
]
}

To obtain file uploaded using this method, specific endpoint has to be used. It can be obtained using a
GET request on the same endpoint used for multiple-part file upload. Consider the following workflow:

GET /~/files/
Accept: application/json

HTTP 200 OK
Content-type:application/json
{
Data: [
{
filename: “software.pkg”,
size: “<length of software.pkg”>,

Introduction To iDirect Web Service Interface 15

 type: “application/octet-stream”,
resource_uri: “/~/files/software.pkg”
},
{
filename: “remote_DID.opt”,
size: “<length of remote_DID.opt”>,
type: “text/plain”,
resource_uri: “/~/files/remote_DID.opt”
},
{ … }
]
}

GET /~/files/software.pkg
Accept: */*

HTTP 200 OK
Content-type:application/octet-stream
<binary content of software.pkg>

16 Introduction To iDirect Web Service Interface

Introduction To iDirect Web Service Interface 17
9 Use Cases
This chapter contains the following sections:
 Adding/Removing Relations

9.1 Adding/Removing Relations

To add or remove a relation, the client is required to send the entire key either in a PATCH request or
together with all the other properties of the modified object in a PUT request. Following is the
example workflow of adding a new related item:

GET /~/alarm/80
Accept:application/json

HTTP 200 OK
Content-Type:application/json
{
...
“EventSiteIDs”:[
“/api/1.0/dde/event/32/432”,
“/api/1.0/dde/event/32/433”,
“/api/1.0/dde/event/55/434”
]
}

Once relations are known, additional ones can be attached and sent back to the server:

PATCH /~alarm/80
Content-type:application/json
{
“EventSiteIDs”:[
“/api/1.0/dde/event/32/432”,
“/api/1.0/dde/event/32/433”,
“/api/1.0/dde/event/55/434”,
“/api/1.0/dde/event/55/500”
]
}

HTTP 202 ACCEPTED

In similar fashion, one or more related item can be removed from the related objects list.

18 Introduction To iDirect Web Service Interface

Introduction To iDirect Web Service Interface 19
10 Streaming Model with
WebSocket
This chapter contains the following sections:
 Establishing Connection
 Detailed Explanation of Web Service Handshake
 WebSocket Protocol
 Streaming Requests
 Error Messages
 Ping/Pong
 Heartbeats
Web Service for non-streaming resources is implemented using an HTTP protocol that can be easily
implemented in a RESTful manner.
It contains of request and response scenario. The client sends a request with a verb/method, headers
and optionally body/payload. The server replies with a response that contains status code, headers and
optionally body/payload.
In the case of streaming, REST principles are rather harder to apply. The following specification tries to
follow REST principles.

10.1 Establishing Connection

Initiation of streaming can be either explicitly requested by the user or initiated by the server and
acquired in a two-way handshake.

10.1.1 User-Requested Streaming

The user calls a resource using the ws(s):// protocol instead of the traditional https(s)://
protocol. This requests the resource to work in streaming mode. It is possible that the selected
resource cannot handle streaming, in which case a “Not Implemented” error is returned.

10.1.2 Two-way Handshake

Streaming is implemented using the WebSocket protocol. In order to get a WebSocket connection, the
client initiates a two-way handshake using the HTTP protocol.
The client sends a request to the web service API with:
 Verb
 Version, prefix, resource name
 ID or query parameters
 Authorization, WebSocket-specific and other optional headers
For a successful WebSocket connection, the client’s request must fulfill ALL of the following criteria:
 It must include a valid authorization/session header.

20 Introduction To iDirect Web Service Interface

  It must include “Upgrade: websocket” header; it should send other WebSocket-
specific headers: Sec-WebSocket-Key and Sec-WebSocket-Version.
 The resource object must be found in registered resources based on version, prefix and
resource name; resource model must inherit from streaming model resource.
When the server’s acknowledgement response is received the protocol is switched from HTTP to
WebSocket.

10.2 Detailed Explanation of Web Service Handshake

In the following HTTP request and response, the green color marks WebSocket-specific parts of the
message.
The client’s request should look similar to:
GET /api/1.0/dde/event HTTP/1.1
Host: idirect.net
Upgrade: websocket
Connection: keep-alive, Upgrade
Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==
Sec-WebSocket-Version: 13
Origin: http://idirect.net
Authorization: Basic dXNlcjM6WmczU0R2UXY=
The server’s response should then be:
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: HSmrc0sMlYUkAGmm5OPpG2HaGWk=

The “Connection” header that contains “Upgrade” indicates that the client wants to switch to the
protocol specified in the “Upgrade” header (“websocket” in this case).
If the server supports the protocol requested by the client it replies with “101 Switching Protocols”. In
the response it includes the “Connection” header that contains “Upgrade” and “Upgrade” header
with value of one of the supported protocol (“websocket” in this case).
If the server does not support the WebSocket protocol it will respond with HTTP code “400 Bad
Request”.
“Sec-WebSocket-Key” header is used to ensure that the server does not accept connections from
non-WebSocket clients. Its value is calculated by base64 encoding of random 16-byte data.
The server concatenates its value to “258EAFA5-E914-47DA-95CA-C5AB0DC85B11” string and the
resulting string is hashed by SHA-1. The resultant value is base64 encoded and is sent in the response
using “Sec-WebSocket-Accept” header.
Using this header’s value, the client can then check if the server truly supports WebSocket connection
by performing the same operations performed on the server and by comparing the resultant strings.

10.3 WebSocket Protocol

Based on the client’s HTTP handshake request, the server extracts:
 Streaming model
 Streaming method; can be one of the following: GET, POST, PUT, PATCH, DELETE

Introduction To iDirect Web Service Interface 21

  ID of model and/or query parameters; skip and limit parameters are not used
 Additional headers used for Serializer/Deserializer of payload
Over one WebSocket connection client can communicate with only one predetermined streaming
model.

10.3.1 Message Format

Messages sent over the WebSocket protocol are encoded in JSON. They resemble messages sent over
the HTTP protocol. Keys used for messages depend on: request/response and method used.
A message can have a “payload” key that is analogous to body in the HTTP protocol and a “headers”
key that is analogous to headers in the HTTP protocol. Keys “result” and “status” are analogous to
the response status code in the HTTP protocol.

10.3.1 Message Payload

The payload of a message represents the resource object the client wants to send to the server or the
server wants to send to the client. The format of the payload depends on the Serializer/Deserializer
chosen.
A Streaming Resource can have additional parameters which determine the output of payload.
The payload received from the server contains only allowed fields and custom fields (values of which
are determined by the custom fields’ callbacks). If relations are defined for the resource, output of
relation fields depends on the enable_rich_read parameter which is URL-based or nested.
The payload sent by the client should contain only allowed fields; all other fields are ignored. If
relations are defined for the resource, the relation field value must be appropriate to the
enable_rich_write parameter; the value must be either URL-based or nested.

10.3.2 Message Headers

The only message header currently used is “Content-Type.”

10.4 Streaming Requests

The following section contains successful responses only.

10.4.1 GET Streaming Request

The GET streaming request is used to stream resources from server only.
The client handshake HTTP GET request has:
 URL identifying the streaming resource
 Optional query with resource ID or more complex query filter
 Accept header for determining format of payload of response messages
The server streams resource objects filtered by the client’s query filter with payload of format
determined from the Accept header. Each message represents one/more resources:
{
"result": 200,
"status": "OK",
"payload": $payload,
"headers": {

22 Introduction To iDirect Web Service Interface

 "Content-Type": "application/json"
}
}
“Content-Type” key of “headers” key defines the format of the payload.
The server may stream resources with the same ID more times, when resource fields change for
example.

10.4.2 POST Streaming Request – not supported

The POST streaming request is used to stream resources from the client only.
The client handshake HTTP POST request has:
 URI identifying the right streaming resource
 Accept header for determining format of payload of response message; this is only used
when resource is set up as verbose
The client streams new resource objects with payload of format defined in the Content-Type header.
Each message represents one resource:
{
"payload": $payload
"headers": {
"Content-Type": "application/json"
}
}
“Content-Type” key of “headers” key defines the format of the payload.

For each request, the server replies with one of the messages described below.

10.4.2.1 For Verbose Output

{
"result": 201,
"status": "Created",
"payload": $payload,
"headers": {
"Content-Type": "application/json"
}
}
Where $payload represents the created resource object in the format defined in “Content-Type” key of
“headers” key.

10.4.2.2 For Non-Verbose Output

{
"result": 204,
"status": "No Content",
}

10.4.3 PUT/PATCH Streaming Request – not supported

The PUT/PATCH streaming request is used to stream resources from the client only. PUT is used to
replace a specified resource and PATCH is used to update specific fields of a specified resource.

Introduction To iDirect Web Service Interface 23

The client handshake HTTP PUT/PATCH request has:
 URI identifying the streaming resource
 Resource ID
 Accept header for determining format of payload of response message; this is only used
when resource is set up as verbose
The client streams new resource objects with payload of format defined in Content-Type header. Each
message represents one resource:
{
"payload": $payload
"headers": {
"Content-Type": "application/json"
}
}
“Content-Type” key of “headers” key define the format of payload.
For each request, the server replies with one of the messages described below.

10.4.3.1 For Verbose Output

{
"result": 200,
"status": "OK",
"payload": $payload,
"headers": {
"Content-Type": "application/json"
}
}
Where $payload represents the created resource object in the format defined in “Content-Type” key of
“headers” key.

10.4.3.2 For Non-Verbose Output

{
"result": 204,
"status": "No Content",
}

10.4.4 DELETE Streaming Request – not supported

The DELETE streaming request is used to delete resources on the server.
The client handshake HTTP DELETE request has:
 URI identifying the right streaming resource
 Optional query with resource ID or more complex query filter
The server streams messages back to the client whenever the deleted resource/resources match the
client’s query filter. Each message is of the form:
{
"result": 204,
"status": "No Content"

24 Introduction To iDirect Web Service Interface

}

10.5 Error Messages

The following section contains error responses only.

10.5.1 Error 500

Error with code 500 happens on internal server error. This error breaks the WebSocket connection.
Message is of the form:
{
"result": 500,
"status": "Internal Server Error"
"payload": {
errors: [$error]
}
}
Where $error describes the error in more detail.

10.5.2 Error 501

An error with code 501 happens whenever the requested server functionality is not implemented. This
error breaks the WebSocket connection. The message is of the form:
{
"result": 501,
"status": "Not Implemented"
"payload": {
errors: [$error]
}
}
Where $error describes the error in more detail.

10.5.3 Other Errors

Typical HTTP client errors happen on the HTTP handshake. On these errors the connection is closed
without proceeding to WebSocket protocol:
 401 Unauthorized
 403 Forbidden
 404 Not Found
 In case of unrecognized URI, i.e. resource type cannot be determined from URI
 In case of PATCH/PUT method when resource is not found
 405 Method Not Allowed
 406 Not Acceptable
 415 Unsupported Media Type

10.5.4 Non-Fatal Errors

Non-fatal errors do not affect the status or result keys. Should any occur, these are included under
‘errors’ key inside the payload of a message with 2xx result:

Introduction To iDirect Web Service Interface 25

{
"result": 200,
"status": "OK",
"payload": {
data: $data,
meta: $meta,
errors: [$nonFatalError1, $nonFatalError2]
},
"headers": {
"Content-Type": "application/json"
}
}

10.6 Ping/Pong
In WebSocket protocol there exist ping and pong frames. This is a low level of the protocol and they
cannot be controlled through JavaScript. They are described in more detail in
http://tools.ietf.org/html/rfc6455.
Whenever the client sends a ping frame (opcode 0x9), the server must reply with pong frame (opcode
0xA).

10.7 Heartbeats
Checking that the WebSocket connection to the server is still alive can be achieved by sending a ping
frame to the server at equal intervals. This is a low level of the protocol and the browser’s
implementation should handle keeping the connection alive. If the network connection has dropped
then the client will already have received a disconnect, but if the WS network connection is still up but
the server has stopped responding to this connection then the Ping -> Pong will detect it. When a Pong
is not received back then the connection should be re-established.

26 Introduction To iDirect Web Service Interface

Introduction To iDirect Web Service Interface 27
Appendix A: Acronyms
Term Definition
0…9
A
API Application Programming Interface
B
BSS Broadcast Satellite Service
OR
Business Support System
C
CRUD Create, Read, Update, Delete
D
E
ESP Encapsulating Security Payload
F
G
GUI Graphical User Interface
H
HTTP HyperText Transfer Protocol
HTTPS HyperText Transfer Protocol, Secure
I
ICD Interface Control Document
ICMP Internet Control Message Protocol
ID IDentifier
iDX (iDirect software)
IP Internet Protocol
J
JSON JavaScript Object Notation
K
L
M
MIME Multipurpose Internet Mail Extensions
N
NMS Network Management System
O
OOK On/Off Keying
P
POSIX Portable Operating System Interface [UNI]X
Q
R
REST REpresentational State Transfer
RF Radio Frequency
S
SAS Satellite Access Station
SCTP Stream Control Transmission Protocol
T
TCP Transmission Control Protocol

28 Introduction To iDirect Web Service Interface

 Term Definition
U
UDP User Datagram Protocol
URI Uniform Resource Identifier
URL Uniform Resource Locator
UTC Universal Time, Coordinated
V
W
X
XML eXtensible Markup Language
Y
Z

Introduction To iDirect Web Service Interface 29

Appendix B: Glossary
Term Definition
Action An action is a sub-resource of a higher-level resource.
Antenna Antenna used by satellite operator to communicate with satellite
Hub Networking components within the SAS
Java Script Object A text-based open standard described in the Internet Engineering Task
Notation (JSON) Force’s RFC 4627
Message Payload The message payload represents a resource object that the client wants to
send to the server or the server wants to send to the client.
REST Architecture A web API design model for software architecture
Satellite Access Common description for all satellite operator entities from IF to connection
Equipment to external IP networks. This entity also interfaces with BSS and NMS
Satellite Access Station Common description for all ground segment entities including Antenna, RFS
and Satellite Access Equipment
Terminal An integrated maritime (or other) system to be installed as a unit. It
comprises a radome, Antenna, radio frequency section, Antenna control
mechanics and electronics, and the router.
Web Service Interface The web service interface provides an interface into the iDirect system
which aims to hide the complexity of the distributed iDirect system
platform, and provide a simple, straightforward interface for all business
processes.

30 Introduction To iDirect Web Service Interface

Introduction To iDirect Web Service Interface 31
Heading 2their country.Heading

32 Introduction To iDirect Web Service Interface