blob: 477a99446ad648457c7f0fcdf9bb3be3d2ec5963 [file] [log] [blame]
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="description" content="">
<meta name="keywords" content="protocolhttprql, binding, protocol, websocket, http">
<title> WebSocket protocol binding • Eclipse Ditto • a digital twin framework</title>
<link rel="stylesheet" href="css/syntax.css">
<link rel="stylesheet" type="text/css" href="//cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css" crossorigin="anonymous">
<link rel="stylesheet" href="css/modern-business.css">
<link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/css/bootstrap.min.css" crossorigin="anonymous">
<link rel="stylesheet" href="css/customstyles.css">
<link rel="stylesheet" href="css/boxshadowproperties.css">
<link rel="stylesheet" href="css/theme-ditto.css">
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:400,700|Source+Code+Pro:300,600|Titillium+Web:400,600,700">
<script src="//cdnjs.cloudflare.com/ajax/libs/jquery/2.1.4/jquery.min.js" crossorigin="anonymous"></script>
<script src="//cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/js/bootstrap.min.js" crossorigin="anonymous"></script>
<script src="//cdnjs.cloudflare.com/ajax/libs/anchor-js/2.0.0/anchor.min.js" crossorigin="anonymous"></script>
<script src="js/toc.js"></script>
<script src="js/customscripts.js"></script>
<script type="application/ld+json">
{
"@context": "http://schema.org",
"@type": "Organization",
"url": "https://eclipse.org/ditto/",
"logo": "https://eclipse.org/ditto/images/ditto.svg"
}
</script>
<link rel="icon" type="image/png" href="images/favicon-16x16.png" sizes="16x16">
<link rel="icon" type="image/png" href="images/favicon-32x32.png" sizes="32x32">
<link rel="icon" type="image/png" href="images/favicon-96x96.png" sizes="96x96">
<link rel="alternate" type="application/rss+xml" title="Eclipse Ditto Blog" href="https://www.eclipse.org/ditto/feed.xml">
<!-- Eclipse Foundation cookie consent: -->
<link rel="stylesheet" type="text/css" href="//www.eclipse.org/eclipse.org-common/themes/solstice/public/stylesheets/vendor/cookieconsent/cookieconsent.min.css" />
<script src="//www.eclipse.org/eclipse.org-common/themes/solstice/public/javascript/vendor/cookieconsent/default.min.js"></script>
<script>
$(document).ready(function() {
$("#tg-sb-link").click(function() {
$("#tg-sb-sidebar").toggle();
$("#tg-sb-content").toggleClass('col-md-9');
$("#tg-sb-content").toggleClass('col-md-12');
$("#tg-sb-icon").toggleClass('fa-toggle-on');
$("#tg-sb-icon").toggleClass('fa-toggle-off');
});
});
</script>
</head>
<script>
(function(w,d,s,l,i){
w[l]=w[l]||[];
w[l].push({'gtm.start':
new Date().getTime(),event:'gtm.js'});
var f=d.getElementsByTagName(s)[0],
j=d.createElement(s),
dl=l!='dataLayer'?'&l='+l:'';
j.async=true;
j.src='https://www.googletagmanager.com/gtm.js?id='+i+dl;
f.parentNode.insertBefore(j,f);
})(window,document,'script','dataLayer','GTM-5WLCZXC');
</script>
<body>
<!-- Navigation -->
<nav class="navbar navbar-inverse navbar-fixed-top">
<div class="container topnavlinks">
<div class="navbar-header">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#bs-example-navbar-collapse-1">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-ditto-home" href="index.html">&nbsp;<img src="images/ditto_allwhite_symbolonly.svg" class="ditto-navbar-symbol" alt="Home"> <img src="images/ditto_allwhite_textonly.svg" class="ditto-navbar-symbol-text" alt="Ditto"></a>
</div>
<div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">
<ul class="nav navbar-nav navbar-right">
<!-- toggle sidebar button -->
<!--<li><a id="tg-sb-link" href="#"><i id="tg-sb-icon" class="fa fa-toggle-on"></i> Nav</a></li>-->
<!-- entries without drop-downs appear here -->
<li><a href="blog.html">Blog</a></li>
<li><a href="intro-overview.html">Documentation</a></li>
<li><a href="http-api-doc.html">HTTP API</a></li>
<li><a href="https://ditto.eclipse.org" target="_blank">Sandbox</a></li>
<li><a href="https://github.com/eclipse/ditto" target="_blank">GitHub</a></li>
<li><a href="https://github.com/eclipse/ditto-examples" target="_blank">GitHub examples</a></li>
<!-- entries with drop-downs appear here -->
<!-- conditional logic to control which topnav appears for the audience defined in the configuration file.-->
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Links<b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="https://projects.eclipse.org/projects/iot.ditto" target="_blank">Eclipse Ditto Project</a></li>
<li><a href="https://www.eclipse.org/forums/index.php/f/364/" target="_blank">Forum</a></li>
<li><a href="https://ci.eclipse.org/ditto/" target="_blank">Jenkins</a></li>
<li><a href="https://dev.eclipse.org/mhonarc/lists/ditto-dev/" target="_blank">Mailing list archives</a></li>
<li><a href="https://gitter.im/eclipse/ditto" target="_blank">Gitter.im chat</a></li>
</ul>
</li>
<!--comment out this block if you want to hide search-->
<li>
<!--start search-->
<div id="search-demo-container">
<input type="text" id="search-input" placeholder="search...">
<ul id="results-container"></ul>
</div>
<script src="//cdnjs.cloudflare.com/ajax/libs/simple-jekyll-search/0.0.9/jekyll-search.js" type="text/javascript"></script>
<script type="text/javascript">
SimpleJekyllSearch.init({
searchInput: document.getElementById('search-input'),
resultsContainer: document.getElementById('results-container'),
dataSource: 'search.json',
searchResultTemplate: '<li><a href="{url}" title="WebSocket protocol binding">{title}</a></li>',
noResultsText: 'No results found.',
limit: 10,
fuzzy: true,
})
</script>
<!--end search-->
</li>
</ul>
</div>
</div>
<!-- /.container -->
</nav>
<!-- Page Content -->
<div class="container">
<div id="main">
<!-- Content Row -->
<div class="row">
<!-- Sidebar Column -->
<div class="col-md-3" id="tg-sb-sidebar">
<ul id="mysidebar" class="nav">
<li class="sidebarTitle">
<label for="docVersion">Eclipse Ditto version:</label>
<div class="select-wrapper">
<select id="docVersion" name="docVersion">
<option value="">development</option>
<option value="1.0">1.0</option>
<option value="1.1">1.1</option>
<option value="1.2">1.2</option>
<option value="1.3">1.3</option>
<option value="1.4">1.4</option>
</select>
</div>
<div id="dev-warning">
<div markdown="span" class="alert alert-warning" role="alert" style="font-size:0.6em"><i class="fa fa-warning"></i> <b>Important:</b> This documentation reflects the latest 'development'. You might want to choose a released version.</div>
</div>
</li>
<li class="subfolders">
<a href="#"><span></span>Introduction</a>
<ul>
<li><a href="intro-overview.html">Overview</a></li>
<li><a href="intro-digitaltwins.html">Digital twins</a></li>
<li><a href="intro-hello-world.html">Hello world</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>Release Notes</a>
<ul>
<li><a href="release_notes_110.html">1.1.0</a></li>
<li><a href="release_notes_100.html">1.0.0</a></li>
<li><a href="release_notes_090.html">0.9.0</a></li>
<li><a href="release_notes_080.html">0.8.0</a></li>
<li class="subfolders">
<a href="#"><span></span>Milestone releases</a>
<ul>
<li><a href="release_notes_100-M2.html">1.0.0-M2</a></li>
<li><a href="release_notes_100-M1a.html">1.0.0-M1a</a></li>
<li><a href="release_notes_090-M2.html">0.9.0-M2</a></li>
<li><a href="release_notes_090-M1.html">0.9.0-M1</a></li>
<li><a href="release_notes_080-M3.html">0.8.0-M3</a></li>
<li><a href="release_notes_080-M2.html">0.8.0-M2</a></li>
<li><a href="release_notes_080-M1.html">0.8.0-M1</a></li>
<li><a href="release_notes_030-M2.html">0.3.0-M2</a></li>
<li><a href="release_notes_030-M1.html">0.3.0-M1</a></li>
<li><a href="release_notes_020-M1.html">0.2.0-M1</a></li>
<li><a href="release_notes_010-M3.html">0.1.0-M3</a></li>
<li><a href="release_notes_010-M1.html">0.1.0-M1</a></li>
</ul>
</li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>Installation</a>
<ul>
<li><a href="installation-building.html">Building Ditto</a></li>
<li><a href="installation-running.html">Running Ditto</a></li>
<li><a href="installation-operating.html">Operating Ditto</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>Basic concepts</a>
<ul>
<li><a href="basic-overview.html">Overview</a></li>
<li class="subfolders">
<a href="#"><span></span>Model entities</a>
<ul>
<li><a href="basic-thing.html">Thing</a></li>
<li><a href="basic-acl.html">Access Control List (ACL)</a></li>
<li><a href="basic-feature.html">Feature</a></li>
<li><a href="basic-policy.html">Policy</a></li>
<li><a href="basic-namespaces-and-names.html">Namespaces and Names</a></li>
</ul>
</li>
<li><a href="basic-auth.html">Authentication and Authorization</a></li>
<li><a href="basic-messages.html">Messages</a></li>
<li><a href="basic-signals.html">Signals</a></li>
<li class="subfolders">
<a href="#"><span></span>Signal types</a>
<ul>
<li><a href="basic-signals-command.html">Command</a></li>
<li><a href="basic-signals-commandresponse.html">Command response</a></li>
<li><a href="basic-signals-errorresponse.html">Error response</a></li>
<li><a href="basic-signals-event.html">Event</a></li>
</ul>
</li>
<li><a href="basic-apis.html">APIs</a></li>
<li><a href="basic-connections.html">Connections</a></li>
<li><a href="basic-placeholders.html">Placeholders</a></li>
<li><a href="basic-changenotifications.html">Change notifications</a></li>
<li><a href="basic-rql.html">RQL expressions</a></li>
<li><a href="basic-enrichment.html">Signal enrichment</a></li>
<li><a href="basic-search.html">Search</a></li>
<li><a href="basic-acknowledgements.html">Acknowledgements</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>Architecture</a>
<ul>
<li><a href="architecture-overview.html">Overview</a></li>
<li class="subfolders">
<a href="#"><span></span>Services</a>
<ul>
<li><a href="architecture-services-policies.html">Policies</a></li>
<li><a href="architecture-services-things.html">Things</a></li>
<li><a href="architecture-services-things-search.html">Things-Search</a></li>
<li><a href="architecture-services-connectivity.html">Connectivity</a></li>
<li><a href="architecture-services-concierge.html">Concierge</a></li>
<li><a href="architecture-services-gateway.html">Gateway</a></li>
</ul>
</li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>HTTP API</a>
<ul>
<li><a href="httpapi-overview.html">Overview</a></li>
<li><a href="httpapi-concepts.html">Concepts</a></li>
<li><a href="httpapi-search.html">Search</a></li>
<li><a href="httpapi-messages.html">Messages</a></li>
<li class="active"><a href="httpapi-protocol-bindings-websocket.html">WebSocket protocol binding</a></li>
<li><a href="httpapi-sse.html">Server sent events</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>Connectivity API</a>
<ul>
<li><a href="connectivity-overview.html">Overview</a></li>
<li><a href="connectivity-manage-connections.html">Manage connections</a></li>
<li><a href="connectivity-protocol-bindings-amqp091.html">AMQP 0.9.1 protocol binding</a></li>
<li><a href="connectivity-protocol-bindings-amqp10.html">AMQP 1.0 protocol binding</a></li>
<li><a href="connectivity-protocol-bindings-mqtt.html">MQTT 3.1.1 protocol binding</a></li>
<li><a href="connectivity-protocol-bindings-mqtt5.html">MQTT 5 protocol binding</a></li>
<li><a href="connectivity-protocol-bindings-http.html">HTTP 1.1 protocol binding</a></li>
<li><a href="connectivity-protocol-bindings-kafka2.html">Kafka 2.x protocol binding</a></li>
<li><a href="connectivity-mapping.html">Payload mapping</a></li>
<li><a href="connectivity-header-mapping.html">Header mapping</a></li>
<li><a href="connectivity-tls-certificates.html">TLS certificates</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>Client SDK</a>
<ul>
<li><a href="client-sdk-overview.html">Overview</a></li>
<li><a href="client-sdk-java.html">Java</a></li>
<li><a href="client-sdk-javascript.html">JavaScript</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>Ditto Protocol</a>
<ul>
<li><a href="protocol-overview.html">Overview</a></li>
<li><a href="protocol-twinlive.html">Twin/live channel</a></li>
<li><a href="protocol-specification.html">Specification</a></li>
<li><a href="protocol-specification-topic.html">Protocol topic</a></li>
<li><a href="protocol-specification-things.html">Things group</a></li>
<li class="subfolders">
<a href="#"><span></span>→ commands/events</a>
<ul>
<li><a href="protocol-specification-things-create-or-modify.html">Create/Modify</a></li>
<li><a href="protocol-specification-things-retrieve.html">Retrieve</a></li>
<li><a href="protocol-specification-things-delete.html">Delete</a></li>
<li><a href="protocol-specification-acks.html">Acknowledgements</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>→ search/messages</a>
<ul>
<li><a href="protocol-specification-things-search.html">Search</a></li>
<li><a href="protocol-specification-things-messages.html">Messages</a></li>
</ul>
</li>
<li><a href="protocol-specification-policies.html">Policies group</a></li>
<li class="subfolders">
<a href="#"><span></span>→ commands/events</a>
<ul>
<li><a href="protocol-specification-policies-create-or-modify.html">Create/Modify</a></li>
<li><a href="protocol-specification-policies-retrieve.html">Retrieve</a></li>
<li><a href="protocol-specification-policies-delete.html">Delete</a></li>
</ul>
</li>
<li><a href="protocol-bindings.html">Bindings</a></li>
<li><a href="protocol-examples.html">Examples</a></li>
<li class="subfolders">
<a href="#"><span></span>→ Things examples</a>
<ul>
<li><a href="protocol-examples-creatething.html">Create a Thing</a></li>
<li><a href="protocol-examples-deletething.html">Delete a Thing</a></li>
<li><a href="protocol-examples-modifything.html">Modify a Thing</a></li>
<li><a href="protocol-examples-retrievething.html">Retrieve a Thing</a></li>
<li><a href="protocol-examples-retrievethings.html">Retrieve multiple Things</a></li>
<li><a href="protocol-examples-modifypolicyid.html">Modify the Policy ID of a Thing</a></li>
<li><a href="protocol-examples-createattributes.html">Create Attributes</a></li>
<li><a href="protocol-examples-deleteattributes.html">Delete Attributes</a></li>
<li><a href="protocol-examples-modifyattributes.html">Modify Attributes</a></li>
<li><a href="protocol-examples-retrieveattributes.html">Retrieve Attributes</a></li>
<li><a href="protocol-examples-createattribute.html">Create a single Attribute</a></li>
<li><a href="protocol-examples-deleteattribute.html">Delete a single Attribute</a></li>
<li><a href="protocol-examples-modifyattribute.html">Modify a single Attribute</a></li>
<li><a href="protocol-examples-retrieveattribute.html">Retrieve a single Attribute</a></li>
<li><a href="protocol-examples-createthingdefinition.html">Create a Definition</a></li>
<li><a href="protocol-examples-deletethingdefinition.html">Delete a Definition</a></li>
<li><a href="protocol-examples-modifythingdefinition.html">Modify a Definition</a></li>
<li><a href="protocol-examples-retrievethingdefinition.html">Retrieve a Definition</a></li>
<li><a href="protocol-examples-createfeatures.html">Create Features</a></li>
<li><a href="protocol-examples-deletefeatures.html">Delete Features</a></li>
<li><a href="protocol-examples-modifyfeatures.html">Modify Features</a></li>
<li><a href="protocol-examples-retrievefeatures.html">Retrieve Features</a></li>
<li><a href="protocol-examples-createfeature.html">Create a single Feature</a></li>
<li><a href="protocol-examples-deletefeature.html">Delete a single Feature</a></li>
<li><a href="protocol-examples-modifyfeature.html">Modify a single Feature</a></li>
<li><a href="protocol-examples-retrievefeature.html">Retrieve a single Feature</a></li>
<li><a href="protocol-examples-createdefinition.html">Create Feature Definition</a></li>
<li><a href="protocol-examples-deletedefinition.html">Delete Feature Definition</a></li>
<li><a href="protocol-examples-modifydefinition.html">Modify Feature Definition</a></li>
<li><a href="protocol-examples-retrievedefinition.html">Retrieve Feature Definition</a></li>
<li><a href="protocol-examples-createproperties.html">Create Feature Properties</a></li>
<li><a href="protocol-examples-deleteproperties.html">Delete Feature Properties</a></li>
<li><a href="protocol-examples-modifyproperties.html">Modify Feature Properties</a></li>
<li><a href="protocol-examples-retrieveproperties.html">Retrieve Feature Properties</a></li>
<li><a href="protocol-examples-createproperty.html">Create a single Property</a></li>
<li><a href="protocol-examples-deleteproperty.html">Delete a single Property</a></li>
<li><a href="protocol-examples-modifyproperty.html">Modify a single Property</a></li>
<li><a href="protocol-examples-retrieveproperty.html">Retrieve a single Property</a></li>
<li><a href="protocol-examples-errorresponses.html">Error responses</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>→ Policies examples</a>
<ul>
<li><a href="protocol-examples-policies-createpolicy.html">Create a Policy</a></li>
<li><a href="protocol-examples-policies-deletepolicy.html">Delete a Policy</a></li>
<li><a href="protocol-examples-policies-modifypolicy.html">Modify a Policy</a></li>
<li><a href="protocol-examples-policies-retrievepolicy.html">Retrieve a Policy</a></li>
<li><a href="protocol-examples-policies-modifypolicyentries.html">Modify entries</a></li>
<li><a href="protocol-examples-policies-retrievepolicyentries.html">Retrieve entries</a></li>
<li><a href="protocol-examples-policies-createpolicyentry.html">Create a single entry</a></li>
<li><a href="protocol-examples-policies-deletepolicyentry.html">Delete a single entry</a></li>
<li><a href="protocol-examples-policies-modifypolicyentry.html">Modify a single entry</a></li>
<li><a href="protocol-examples-policies-retrievepolicyentry.html">Retrieve a single entry</a></li>
<li><a href="protocol-examples-policies-modifysubjects.html">Modify subjects</a></li>
<li><a href="protocol-examples-policies-retrievesubjects.html">Retrieve subjects</a></li>
<li><a href="protocol-examples-policies-createsubject.html">Create a single subject</a></li>
<li><a href="protocol-examples-policies-deletesubject.html">Delete a single subject</a></li>
<li><a href="protocol-examples-policies-modifysubject.html">Modify a single subject</a></li>
<li><a href="protocol-examples-policies-retrievesubject.html">Retrieve a single subject</a></li>
<li><a href="protocol-examples-policies-modifyresources.html">Modify resources</a></li>
<li><a href="protocol-examples-policies-retrieveresources.html">Retrieve resources</a></li>
<li><a href="protocol-examples-policies-createresource.html">Create a single resource</a></li>
<li><a href="protocol-examples-policies-deleteresource.html">Delete a single resource</a></li>
<li><a href="protocol-examples-policies-modifyresource.html">Modify a single resource</a></li>
<li><a href="protocol-examples-policies-retrieveresource.html">Retrieve a single resource</a></li>
<li><a href="protocol-examples-policies-errorresponses.html">Error responses</a></li>
</ul>
</li>
<li><a href="protocol-examples-search.html">→ Search examples</a></li>
</ul>
</li>
<li><a href="sandbox.html">Sandbox</a></li>
<li><a href="presentations.html">Presentations</a></li>
<li><a href="glossary.html">Glossary</a></li>
<li><a href="feedback.html">Feedback</a></li>
<p class="external">
<a href="#" id="collapseAll">Collapse All</a> | <a href="#" id="expandAll">Expand All</a>
</p>
</ul>
<!-- this highlights the active parent class in the sidebar. this is critical so that the parent expands when you're viewing a page. This must appear below the sidebar code above. Otherwise, if placed inside customscripts.js, the script runs before the sidebar code runs and the class never gets inserted.-->
<script>$("li.active").parents('li').toggleClass("active");
</script>
</div>
<!-- Content Column -->
<div class="col-md-9" id="tg-sb-content">
<div class="post-header">
<h1 class="post-title-main">WebSocket protocol binding</h1>
</div>
<div class="post-content">
<!-- this handles the automatic toc. use ## for subheads to auto-generate the on-page minitoc. if you use html tags, you must supply an ID for the heading element in order for it to appear in the minitoc. -->
<script>
$( document ).ready(function() {
// Handler for .ready() called.
$('#toc').toc({ minimumHeaders: 0, listType: 'ul', showSpeed: 0, headers: 'h2,h3,h4' });
/* this offset helps account for the space taken up by the floating toolbar. */
$('#toc').on('click', 'a', function() {
var target = $(this.getAttribute('href'))
, scroll_target = target.offset().top
$(window).scrollTop(scroll_target - 10);
return false
})
});
</script>
<div id="toc"></div>
<p><a href="protocol-overview.html">Ditto Protocol</a> messages can be sent <em>as is</em> as <a href="https://tools.ietf.org/html/rfc6455">WebSocket</a> message.
The Ditto Protocol JSON must be sent as <code class="highlighter-rouge">UTF-8</code> encoded String payload.</p>
<h2 id="websocket-features">WebSocket features</h2>
<p>The WebSocket provides an alternative to the <a href="httpapi-overview.html">HTTP API</a> in order to manage your digital twins.</p>
<p>The benefits of the WebSocket compared to HTTP are multiple ones:</p>
<ul>
<li>a single connection (socket like) is established and for commands to digital twins no further HTTP overhead
(e.g. HTTP headers, HTTP connection establishment) is produced which means you can get more commands/seconds
through the WebSocket compared to the HTTP endpoint</li>
<li>as the WebSocket is a duplex connection, <a href="basic-changenotifications.html">change notifications</a> can be sent via the
WebSocket for changes to entities done in Ditto</li>
<li>additionally, <a href="basic-messages.html">messages</a> and <a href="protocol-twinlive.html">live commands/events</a> can be exchanged
(sending and receiving) via multiple connected WebSocket sessions</li>
</ul>
<h3 id="send-commands-and-get-responses">Send commands and get responses</h3>
<p>When sending a command via WebSocket you will receive a corresponding response (the response can be related to the
request by the <code class="highlighter-rouge">correlation-id</code> header). <br />
The response indicates the success or the failure of the command and, depending on the command type, contains the result
payload.</p>
<p>Please find examples of commands and their response pattern at <a href="protocol-examples.html">Protocol examples</a>.</p>
<h3 id="request-receiving-eventschange-notifications">Request receiving events/change notifications</h3>
<p>In addition to the response, which Ditto addresses directly to the instance which was sending the command, an event
is generated. <br />
This will be delivered to all other clients with read permissions for the respective thing, feature change, etc.</p>
<p>See <a href="#request-events">request events</a> for subscribing/unsubscribing for receiving change notifications.</p>
<h3 id="request-receiving-messages">Request receiving messages</h3>
<p><a href="basic-messages.html">Messages</a> can be sent both via the <a href="httpapi-overview.html">HTTP API</a> and the WebSocket. Receiving
messages and answering to them however can only be done via the WebSocket.</p>
<p>See <a href="#request-messages">request messages</a> for subscribing/unsubscribing for receiving messages.</p>
<h3 id="request-receiving-live-commands--events">Request receiving live commands + events</h3>
<p>In order to receive <a href="protocol-twinlive.html">live commands and events</a>, the WebSocket API can be used. The Ditto Protocol
messages are the same as for the “twin” channel, only with <em>live</em> as channel in the
<a href="protocol-specification-topic.html">topic</a>.</p>
<p>See <a href="#request-live-commands">request live commands</a> and <a href="#request-live-events">request live events</a> for
subscribing/unsubscribing for receiving live commands and events.</p>
<h2 id="websocket-endpoint">WebSocket endpoint</h2>
<p>The WebSocket endpoint is accessible at these URLs (depending on which API version to use):</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>ws://localhost:8080/ws/1
ws://localhost:8080/ws/2
</code></pre></div></div>
<h3 id="authentication">Authentication</h3>
<p>A user who connects to the WebSocket endpoint can be authenticated by using</p>
<ul>
<li>HTTP BASIC Authentication by providing a username and the password of a user managed within nginx or</li>
<li>a JSON Web Token (JWT) issued by an OpenID connect provider.</li>
</ul>
<p>See <a href="basic-auth.html">Authenticate</a> for more details.</p>
<h2 id="websocket-protocol-format">WebSocket protocol format</h2>
<p>As defined in the <a href="protocol-specification.html">Protocol specification</a> a Ditto Protocol message consists of different
information. This information is combined into a single JSON message for the WebSocket endpoint:</p>
<ul>
<li><a href="protocol-specification.html#topic">topic</a>: JSON string with key <code class="highlighter-rouge">topic</code></li>
<li><a href="protocol-specification.html#headers">headers</a>: JSON object with key <code class="highlighter-rouge">headers</code></li>
<li><a href="protocol-specification.html#path">path</a>: JSON string with key <code class="highlighter-rouge">path</code></li>
<li><a href="protocol-specification.html#value">value</a>: JSON value (e.g. JSON object, string, array, …) with key <code class="highlighter-rouge">value</code></li>
<li><a href="protocol-specification.html#status">status</a> (for responses): JSON number with key <code class="highlighter-rouge">status</code></li>
</ul>
<p>The schema for Ditto Protocol message via WebSocket:</p>
<div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="s2">"topic"</span><span class="p">:</span><span class="w"> </span><span class="s2">"&lt;the topic&gt;"</span><span class="p">,</span><span class="w">
</span><span class="s2">"headers"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="s2">"correlation-id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"&lt;a correlation-id&gt;"</span><span class="p">,</span><span class="w">
</span><span class="s2">"a-header"</span><span class="p">:</span><span class="w"> </span><span class="s2">"&lt;header value&gt;"</span><span class="w">
</span><span class="p">},</span><span class="w">
</span><span class="s2">"path"</span><span class="p">:</span><span class="w"> </span><span class="s2">"&lt;the path&gt;"</span><span class="p">,</span><span class="w">
</span><span class="s2">"value"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre></div></div>
<h2 id="websocket-binding-specific-messages">WebSocket binding specific messages</h2>
<p>The WebSocket binding defines several specific messages which are not defined in the Ditto Protocol specification.</p>
<p>Those are also not defined as JSON messages, but as plain text messages. All of those declare a demand for some kind
of information from the backend to be pushed into the WebSocket session.</p>
<h3 id="request-events">Request events</h3>
<p>In order to subscribe for <a href="basic-changenotifications.html">events/change notifications</a> for entities (e.g. Things),
following text message has to be sent to the backend: <code class="highlighter-rouge">START-SEND-EVENTS</code></p>
<p>From then on the WebSocket session will receive all change notifications it is entitled to see.</p>
<h3 id="request-messages">Request messages</h3>
<p>In order to subscribe for <a href="basic-messages.html">messages</a> which can be sent from a WebSocket session to another
WebSocket session or from the <a href="httpapi-overview.html">HTTP API</a> to a WebSocket session, the following text message has
to be sent to the backend: <code class="highlighter-rouge">START-SEND-MESSAGES</code></p>
<p>From then on the WebSocket session will receive all messages it is entitled to see.</p>
<h3 id="request-live-commands">Request live commands</h3>
<p>In order to subscribe for <a href="protocol-twinlive.html">live commands</a> which can be sent from a WebSocket session to another
WebSocket session, the following text message has to be sent to the backend: <code class="highlighter-rouge">START-SEND-LIVE-COMMANDS</code></p>
<p>From then on the WebSocket session will receive all live commands it is entitled to see.</p>
<h3 id="request-live-events">Request live events</h3>
<p>In order to subscribe for <a href="protocol-twinlive.html">live events</a> which can be sent from a WebSocket session to another
WebSocket session, the following text message has to be sent to the backend: <code class="highlighter-rouge">START-SEND-LIVE-EVENTS</code></p>
<p>From then on the WebSocket session will receive all live events it is entitled to see.</p>
<h3 id="overview">Overview</h3>
<p>The following table shows which WebSocket protocol message are supported:</p>
<table>
<thead>
<tr>
<th>Description</th>
<th>Request message</th>
<th>Response message</th>
</tr>
</thead>
<tbody>
<tr>
<td>Subscribe for <a href="basic-changenotifications.html">events/change notifications</a></td>
<td><code class="highlighter-rouge">START-SEND-EVENTS</code></td>
<td><code class="highlighter-rouge">START-SEND-EVENTS:ACK</code></td>
</tr>
<tr>
<td>Stop receiving change notifications</td>
<td><code class="highlighter-rouge">STOP-SEND-EVENTS</code></td>
<td><code class="highlighter-rouge">STOP-SEND-EVENTS:ACK</code></td>
</tr>
<tr>
<td>Subscribe for <a href="basic-messages.html">messages</a></td>
<td><code class="highlighter-rouge">START-SEND-MESSAGES</code></td>
<td><code class="highlighter-rouge">START-SEND-MESSAGES:ACK</code></td>
</tr>
<tr>
<td>Stop receiving messages</td>
<td><code class="highlighter-rouge">STOP-SEND-MESSAGES</code></td>
<td><code class="highlighter-rouge">STOP-SEND-MESSAGES:ACK</code></td>
</tr>
<tr>
<td>Subscribe for <a href="protocol-twinlive.html">live commands</a></td>
<td><code class="highlighter-rouge">START-SEND-LIVE-COMMANDS</code></td>
<td><code class="highlighter-rouge">START-SEND-LIVE-COMMANDS:ACK</code></td>
</tr>
<tr>
<td>Stop receiving live commands</td>
<td><code class="highlighter-rouge">STOP-SEND-LIVE-COMMANDS</code></td>
<td><code class="highlighter-rouge">STOP-SEND-LIVE-COMMANDS:ACK</code></td>
</tr>
<tr>
<td>Subscribe for <a href="protocol-twinlive.html">live events</a></td>
<td><code class="highlighter-rouge">START-SEND-LIVE-EVENTS</code></td>
<td><code class="highlighter-rouge">START-SEND-LIVE-EVENTS:ACK</code></td>
</tr>
<tr>
<td>Stop receiving live commands</td>
<td><code class="highlighter-rouge">STOP-SEND-LIVE-EVENTS</code></td>
<td><code class="highlighter-rouge">STOP-SEND-LIVE-EVENTS:ACK</code></td>
</tr>
</tbody>
</table>
<h3 id="enrichment">Enrichment</h3>
<div class="bs-callout bs-callout-primary">Available since Ditto <strong>1.1.0</strong></div>
<p>When extra fields should be added to outgoing messages on the WebSocket channel, an <code class="highlighter-rouge">extraFields</code> parameter can be added
to the request message. This is supported for all request messages:</p>
<table>
<thead>
<tr>
<th>Description</th>
<th>Request message</th>
<th><a href="basic-enrichment.html">Enrich by extra fields</a></th>
</tr>
</thead>
<tbody>
<tr>
<td>Subscribe for <a href="basic-changenotifications.html">events/change notifications</a></td>
<td><code class="highlighter-rouge">START-SEND-EVENTS</code></td>
<td></td>
</tr>
<tr>
<td>Subscribe for <a href="basic-messages.html">messages</a></td>
<td><code class="highlighter-rouge">START-SEND-MESSAGES</code></td>
<td></td>
</tr>
<tr>
<td>Subscribe for <a href="protocol-twinlive.html">live commands</a></td>
<td><code class="highlighter-rouge">START-SEND-LIVE-COMMANDS</code></td>
<td></td>
</tr>
<tr>
<td>Subscribe for <a href="protocol-twinlive.html">live events</a></td>
<td><code class="highlighter-rouge">START-SEND-LIVE-EVENTS</code></td>
<td></td>
</tr>
</tbody>
</table>
<p>Analog to the <a href="#filtering">filtering</a> the parameter is defined like an HTTP query parameter, e.g.:</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>START-SEND-EVENTS?extraFields=attributes/counter,features/ConnectionStatus
START-SEND-MESSAGES?extraFields=attributes
</code></pre></div></div>
<h3 id="filtering">Filtering</h3>
<p>In order to only consume specific events like described in <a href="basic-changenotifications.html">change notifications</a>, the
following parameters can additionally be provided when sending the WebSocket protocol messages:</p>
<table>
<thead>
<tr>
<th>Description</th>
<th>Request message</th>
<th><a href="basic-changenotifications.html#by-namespaces">Filter by namespaces</a></th>
<th><a href="basic-changenotifications.html#by-rql-expression">Filter by RQL expression</a></th>
</tr>
</thead>
<tbody>
<tr>
<td>Subscribe for <a href="basic-changenotifications.html">events/change notifications</a></td>
<td><code class="highlighter-rouge">START-SEND-EVENTS</code></td>
<td></td>
<td></td>
</tr>
<tr>
<td>Subscribe for <a href="basic-messages.html">messages</a></td>
<td><code class="highlighter-rouge">START-SEND-MESSAGES</code></td>
<td></td>
<td></td>
</tr>
<tr>
<td>Subscribe for <a href="protocol-twinlive.html">live commands</a></td>
<td><code class="highlighter-rouge">START-SEND-LIVE-COMMANDS</code></td>
<td></td>
<td></td>
</tr>
<tr>
<td>Subscribe for <a href="protocol-twinlive.html">live events</a></td>
<td><code class="highlighter-rouge">START-SEND-LIVE-EVENTS</code></td>
<td></td>
<td></td>
</tr>
</tbody>
</table>
<p>The parameters are specified similar to HTTP query parameters, the first one separated with a <code class="highlighter-rouge">?</code> and all following ones
with <code class="highlighter-rouge">&amp;</code>. You have to URL encode the filter values before using them in a configuration.</p>
<p>For example this way the WebSocket session would register for all events in the namespace <code class="highlighter-rouge">org.eclipse.ditto</code> and which
would match an attribute “counter” to be greater than 42:</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>START-SEND-EVENTS?namespaces=org.eclipse.ditto&amp;filter=gt(attributes/counter,42)
</code></pre></div></div>
<p>The filtering may be also used in combination with an <a href="#enrichment">enrichment</a>, e.g.:</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>START-SEND-EVENTS?extraFields=attributes&amp;filter=gt(attributes/counter,42)
</code></pre></div></div>
<div class="tags">
<b>Tags: </b>
<a href="tag_protocol.html" class="btn btn-default navbar-btn cursorNorm" role="button">protocol</a>
<a href="tag_http.html" class="btn btn-default navbar-btn cursorNorm" role="button">http</a>
<a href="tag_rql.html" class="btn btn-default navbar-btn cursorNorm" role="button">rql</a>
</div>
</div>
<hr class="shaded"/>
<footer>
<div class="row">
<div class="col-lg-12 footer">
<div class="logo">
<a href="https://eclipse.org"><img src="images/eclipse_foundation_logo.svg" alt="Eclipse logo"/></a>
</div>
<p class="notice">
&copy;2020 Eclipse Ditto.
Site last generated: Dec 9, 2020 <br />
</p>
<div class="quickLinks">
<a href="https://www.eclipse.org/legal/privacy.php" target="_blank">
&gt; Privacy Policy
</a>
<a href="https://www.eclipse.org/legal/termsofuse.php" target="_blank">
&gt; Terms of Use
</a>
<a href="https://www.eclipse.org/legal/copyright.php" target="_blank">
&gt; Copyright Agent
</a>
<a href="https://www.eclipse.org/legal" target="_blank">
&gt; Legal
</a>
<a href="https://www.eclipse.org/legal/epl-2.0/" target="_blank">
&gt; License
</a>
<a href="https://eclipse.org/security" target="_blank">
&gt; Report a Vulnerability
</a>
</div>
</div>
</div>
</footer>
</div>
<!-- /.row -->
</div>
<!-- /.container -->
</div>
<!-- /#main -->
</div>
</body>
</html>