OCF Cloud Open API · Figures 135 136 Figure 1 – OCF Cloud Overview ..... 4 137 Figure 2 –...

CONTACT [email protected] Copyright Open Connectivity Foundation, Inc. © 2019-2020. All Rights Reserved.

OCF Cloud API for Cloud Services Gaborone-1 | March 2020

mailto:[email protected]

Copyright Open Connectivity Foundation, Inc. © 2019-2020. All rights Reserved

Legal Disclaimer 2 3

THIS IS A DRAFT SPECIFICATION DOCUMENT ONLY AND HAS NOT BEEN ADOPTED BY THE 4 OPEN CONNECTIVITY FOUNDATION. THIS DRAFT DOCUMENT MAY NOT BE RELIED UPON 5 FOR ANY PURPOSE OTHER THAN REVIEW OF THE CURRENT STATE OF THE DEVELOPMENT 6 OF THIS DRAFT DOCUMENT. THE OPEN CONNECTIVITY FOUNDATION AND ITS MEMBERS 7 RESERVE THE RIGHT WITHOUT NOTICE TO YOU TO CHANGE ANY OR ALL PORTIONS 8 HEREOF, DELETE PORTIONS HEREOF, MAKE ADDITIONS HERETO, DISCARD THIS DRAFT 9 DOCUMENT IN ITS ENTIRETY OR OTHERWISE MODIFY THIS DRAFT DOCUMENT AT ANY 10 TIME. YOU SHOULD NOT AND MAY NOT RELY UPON THIS DRAFT DOCUMENT IN ANY WAY, 11 INCLUDING BUT NOT LIMITED TO THE DEVELOPMENT OF ANY PRODUCTS OR SERVICES. 12 IMPLEMENTATION OF THIS DRAFT DOCUMENT IS DONE AT YOUR OWN RISK AMEND AND 13 IT IS NOT SUBJECT TO ANY LICENSING GRANTS OR COMMITMENTS UNDER THE OPEN 14 CONNECTIVITY FOUNDATION INTELLECTUAL PROPERTY RIGHTS POLICY OR OTHERWISE. 15 IN CONSIDERATION OF THE OPEN CONNECTIVITY FOUNDATION GRANTING YOU ACCESS 16 TO THIS DRAFT DOCUMENT, YOU DO HEREBY WAIVE ANY AND ALL CLAIMS ASSOCIATED 17 HEREWITH INCLUDING BUT NOT LIMITED TO THOSE CLAIMS DISCUSSED BELOW, AS WELL 18 AS CLAIMS OF DETRIMENTAL RELIANCE. 19

The OCF logo is a trademark of Open Connectivity Foundation, Inc. in the United States or other 20 countries. *Other names and brands may be claimed as the property of others. 21

Copyright © 2019-2020 Open Connectivity Foundation, Inc. All rights reserved. 22

Copying or other form of reproduction and/or distribution of these works are strictly prohibited. 23 24


CONTENTS 25

26

1 Scope .............................................................................................................................. 1 27

2 Normative references ...................................................................................................... 1 28

3 Terms, definitions, and abbreviated terms ....................................................................... 1 29

3.1 Terms and definitions.............................................................................................. 1 30

3.2 Abbreviated terms ................................................................................................... 2 31

4 Document conventions and organization .......................................................................... 3 32

4.1 Conventions ............................................................................................................ 3 33

4.2 Notation .................................................................................................................. 3 34

5 Overview ......................................................................................................................... 4 35

5.1 Introduction ............................................................................................................. 4 36

5.2 General OCF Cloud API for Cloud Services Elements ............................................. 4 37

5.3 Cloud to Cloud Operational Overview ..................................................................... 5 38

5.3.1 Introduction ..................................................................................................... 5 39

5.3.2 Conceptual Architecture .................................................................................. 5 40

5.3.3 Authorizing Cloud Connectivity ........................................................................ 6 41

5.3.4 Synchronization of User's set of Devices ......................................................... 6 42

5.3.5 Keeping Up-to-Date: Notifications of changes on other Clouds ........................ 6 43

5.3.6 Handling of Requests and Responses for Connected Devices ......................... 6 44

6 Authentication & Authorization ......................................................................................... 6 45

7 Account Linking API ........................................................................................................ 7 46

7.1 General ................................................................................................................... 7 47

7.2 OAuth2.0 Access Token Scopes ............................................................................. 8 48

8 Devices API ..................................................................................................................... 9 49

8.1 Introduction ............................................................................................................. 9 50

8.2 Parameters Supported in Requests ......................................................................... 9 51

8.3 Retrieve All Devices .............................................................................................. 10 52

8.3.1 Summary ....................................................................................................... 10 53

8.3.2 Request and Response Payload .................................................................... 10 54

8.3.3 Responses .................................................................................................... 11 55

8.4 Retrieve One Device ............................................................................................. 11 56

8.4.1 Summary ....................................................................................................... 11 57


8.4.3 Responses .................................................................................................... 12 59

8.5 Retrieve Specific Resource ................................................................................... 13 60

8.5.1 Summary ....................................................................................................... 13 61


8.5.3 Responses .................................................................................................... 14 63

8.6 Update a Resource on a Device ............................................................................ 14 64

8.6.1 Summary ....................................................................................................... 14 65



8.6.3 Responses .................................................................................................... 15 67

9 Events API .................................................................................................................... 16 68

9.1 Introduction ........................................................................................................... 16 69

9.2 Events Authentication ........................................................................................... 16 70

9.2.1 Create Event Signature ................................................................................. 17 71

9.2.2 Verify the Event Signature ............................................................................. 17 72

9.3 Parameters Supported .......................................................................................... 17 73

9.4 Events API subscription and notification payload definitions ................................. 18 74

9.4.1 Subscription request ...................................................................................... 18 75

9.4.2 Subscription response ................................................................................... 19 76

9.4.3 Notification request ........................................................................................ 19 77

9.5 Subscribe and unsubscribe to devices level event types ....................................... 21 78

9.5.1 Summary ....................................................................................................... 21 79


9.5.3 Responses .................................................................................................... 22 81

9.6 Subscribe and unsubscribe to device level events................................................. 22 82

9.6.1 Summary ....................................................................................................... 22 83


9.6.3 Responses .................................................................................................... 23 85

9.7 Subscribe and unsubscribe to resource level events ............................................. 23 86

9.7.1 Summary ....................................................................................................... 23 87


9.7.3 Responses .................................................................................................... 24 89

9.8 Notification of devices level events ....................................................................... 25 90

9.8.1 Summary ....................................................................................................... 25 91


9.8.3 Responses .................................................................................................... 25 93

9.9 Notification of Device level events ........................................................................ 26 94

9.9.1 Summary ....................................................................................................... 26 95


9.9.3 Responses .................................................................................................... 26 97

9.10 Notification of Resource level events .................................................................... 27 98

9.10.1 Summary ....................................................................................................... 27 99


9.10.3 Responses .................................................................................................... 27 101

Representative Flows ............................................................................................. 29 102

A.1 Introduction ........................................................................................................... 29 103

A.2 OAuth2.0 Application Registration ......................................................................... 29 104

A.3 Account Linking .................................................................................................... 29 105

A.4 Retrieval of all Devices ......................................................................................... 30 106

A.4.1 Summary ....................................................................................................... 30 107

A.4.2 Flow .............................................................................................................. 31 108

A.4.3 Flow Description ............................................................................................ 31 109

A.5 Retrieval of a single Device .................................................................................. 32 110


A.5.1 Summary ....................................................................................................... 32 111

A.5.2 Flow .............................................................................................................. 32 112

A.5.3 Flow Description ............................................................................................ 32 113

A.6 Retrieval of a single Resource .............................................................................. 33 114

A.6.1 Summary ....................................................................................................... 33 115

A.6.2 Flows ............................................................................................................. 33 116

A.7 Update of a single Resource ................................................................................. 35 117

A.7.1 Summary ....................................................................................................... 35 118

A.7.2 Flows ............................................................................................................. 35 119

A.8 Establishment of new subscription request ............................................................ 36 120

A.8.1 Summary ....................................................................................................... 36 121

A.9 Event generated for a subscription ........................................................................ 37 122

A.9.1 Summary ....................................................................................................... 37 123

A.10 Addition of new registration ................................................................................... 38 124

A.10.1 Summary ....................................................................................................... 38 125

A.11 Removal of existing device registration ................................................................. 39 126

A.11.1 Summary ....................................................................................................... 39 127

Open API Definition ................................................................................................ 41 128

B.1.1 Supported APIs ............................................................................................. 41 129

B.1.2 OpenAPI 2.0 definition ...................................... Error! Bookmark not defined. 130

131

132


133

Figures 134 135

Figure 1 – OCF Cloud Overview ............................................................................................. 4 136

Figure 2 – Conceptual Architecture ......................................................................................... 5 137

Figure 3 – Subscription Request Example ............................................................................. 19 138

Figure 4 – Subscription Response Example Payload............................................................. 19 139

Figure A.1 – Establish Business Relationship Example Flow ................................................. 29 140

Figure A.2 – Initial Association Example Flow ....................................................................... 30 141

Figure A.3 – Retrieve All Devices Example Flow ................................................................... 31 142

Figure A.4 – Retrieve Single Device Example Flow ............................................................... 32 143

Figure A.5 – Retrieve Resource (Success) Example Flow ..................................................... 33 144

Figure A.6 – Retrieve Resource (Timeout) Example Flow ..................................................... 34 145

Figure A.7 – Update Resource (Success) Example Flow ....................................................... 35 146

Figure A.8 – Update Resource (Timeout) Example Flow ....................................................... 36 147

Figure A.9 – Observe Establishment Example Flow .............................................................. 37 148

Figure A.10 – "resource_contentchanged" Event Example Flow ............................................ 38 149

Figure A.11 – Addition of new registered Device example flow .............................................. 39 150

Figure A.12 – Removal of existing registration example flow ................................................. 40 151

152

153


Tables 154 155

Table 1 – OAuth 2.0 AccessToken Scopes.............................................................................. 8 156

Table 2 – Applicable OAuth2.0 Access Token Scopes per API Endpoint ................................. 9 157

Table 3 – Parameters used in Requests in the Device API ...................................................... 9 158

Table 4 – Retrieve All Devices API Summary ........................................................................ 10 159

Table 5 – Devices API non-success path responses ............................................................. 11 160

Table 6 – Retrieve One Device API Summary ....................................................................... 12 161

Table 7 – Device API non-success path responses ............................................................... 12 162

Table 8 – Retrieve Specific Resource API Summary ............................................................. 13 163

Table 9 – Resource Retrieval API non-success path responses ............................................ 14 164

Table 10 – Update Resource API Summary .......................................................................... 14 165

Table 11 – Resource Update API non-success path responses ............................................. 15 166

Table 12 – Parameters used in the Events API ..................................................................... 17 167

Table 13 – Event types and API Endpoints ........................................................................... 18 168

Table 14 – Subscription Request Payload Properties ............................................................ 18 169

Table 15 – Subscription Response Properties ....................................................................... 19 170

Table 16 – Notification request HTTP Headers ..................................................................... 20 171

Table 17 – Event type to notification payload content ........................................................... 20 172

Table 18 – Subscription to /devices API Summary ................................................................ 21 173

Table 19 – Devices Event Subscription API non-success path responses ............................. 22 174

Table 20 – Subscription to Single Device API Summary ........................................................ 22 175

Table 21 – Device Event Subscription API non-success path responses ............................... 23 176

Table 22 – Subscription to Resource API Summary .............................................................. 24 177

Table 23 – Resource Event Subscription API non-success path responses ........................... 24 178

Table 24 – Notification of /devices API Summary .................................................................. 25 179

Table 25 – Devices Event Notification non-success path responses ...................................... 25 180

Table 26 – Notification of Single Device API Summary ......................................................... 26 181

Table 27 – Device Event Notification non-success path responses ....................................... 26 182

Table 28 – Notification of Resource API Summary ................................................................ 27 183

Table 29 – Resource Event Notification non-success path responses ................................... 27 184

Table A.1 – Retrieve all Devices Flow Summary ................................................................... 31 185

Table A.2 – Retrieve single Device Flow Summary ............................................................... 32 186

Table A.3 – Retrieve single Resource Flow Summary ........................................................... 34 187

Table A.4 – Update single Resource Flow Summary ............................................................. 35 188

189

Copyright Open Connectivity Foundation, Inc. © 2018-19. All rights Reserved 1

1 Scope 190

This document defines functional requirements for the OCF Cloud to Cloud Application 191 Programming Interface (API). 192

2 Normative references 193

The following documents are referred to in the text in such a way that some or all of their content 194 constitutes requirements of this document. For dated references, only the edition cited applies. For 195 undated references, the latest edition of the referenced document (including any amendments) 196 applies. 197

IETF RFC 2818, HTTP over TLS, May 2000 198 https://tools.ietf.org/html/rfc2818 199

IETF RFC 6749, The OAuth 2.0 Authorization Framework, October 2012 200 https://tools.ietf.org/html/rfc6749 201

IETF RFC 6750, The OAuth 2.0 Authorization Framework: Bearer Token Usage, October 2012 202 https://www.rfc-editor.org/info/rfc6750 203

ISO/IEC 30118-1:2018 Information technology -- Open Connectivity Foundation (OCF) 204 Specification -- Part 1: Core specification 205 https://www.iso.org/standard/53238.html 206 Latest version available at: https://openconnectivity.org/specs/OCF_Core_Specification.pdf 207

ISO/IEC 30118-2:2018 Information technology -- Open Connectivity Foundation (OCF) 208 Specification -- Part 2: Security specification 209 https://www.iso.org/standard/74239.html 210 Latest version available at: https://openconnectivity.org/specs/OCF_Security_Specification.pdf 211

OCF Device to Cloud Services Specification, Open Connectivity Foundation Device to Cloud 212 Services Specification, 213 Latest version available at: 214 https://openconnectivity.org/specs/OCF_Cloud_Specification.pdf 215

OCF Cloud API for Cloud Services https://github.com/openconnectivityfoundation/core-216 extensions/blob/ocfcloud-openapi/swagger2.0/oic.r.cloudopenapi.swagger.json 217

OpenAPI 2.0, fka Swagger RESTful API Documentation Specification, Version 2.0 218 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md 219

220

3 Terms, definitions, and abbreviated terms 221

3.1 Terms and definitions 222

For the purposes of this document, the terms and definitions given in ISO/IEC 30118-1:2018 and 223 ISO/IEC 30118-2:2018 and the following apply. 224

ISO and IEC maintain terminological databases for use in standardization at the following 225 addresses: 226 – ISO Online browsing platform: available at https://www.iso.org/obp 227

– IEC Electropedia: available at http://www.electropedia.org/ 228

https://www.rfc-editor.org/info/rfc6750

https://www.iso.org/standard/53238.html

https://openconnectivity.org/specs/OCF_Core_Specification.pdf

https://openconnectivity.org/specs/OCF_Core_Specification.pdf

https://www.iso.org/standard/74239.html

https://openconnectivity.org/specs/OCF_Security_Specification.pdf

https://openconnectivity.org/specs/OCF_Cloud_Specification.pdf

https://github.com/openconnectivityfoundation/core-extensions/blob/ocfcloud-openapi/swagger2.0/oic.r.cloudopenapi.swagger.json

https://github.com/openconnectivityfoundation/core-extensions/blob/ocfcloud-openapi/swagger2.0/oic.r.cloudopenapi.swagger.json

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md

https://www.iso.org/obp

http://www.electropedia.org/


229

3.1.1 230 API Endpoint 231 a defined URL to which requests defined in this document are sent 232

3.1.2 233 Bearer Token 234 an OAuth2.0 access token as defined within IETF RFC 6750 235

3.1.3 236 Origin Cloud 237 the OCF Cloud or the 3rd party Cloud through which the user works with his OCF Devices 238

3.1.4 239 Subscription ID 240 a unique identity that is associated with an instance of a subscription to an event (or events) 241

3.1.5 242 Target Cloud 243 the OCF Cloud to which OCF Servers (OCF Devices) are connected which the user wants to control 244 via the Origin Cloud (3.1.2) 245

3.2 Abbreviated terms 246

3.2.1 247 API 248 Application Programming Interface 249

3.2.2 250 HMAC 251 Hash-based Message Authentication Code 252

253


4 Document conventions and organization 254

4.1 Conventions 255

In this document a number of terms, conditions, mechanisms, sequences, parameters, events, 256 states, or similar terms are printed with the first letter of each word in uppercase and the rest 257 lowercase (e.g., Network Architecture). Any lowercase uses of these words have the normal 258 technical English meaning. 259

4.2 Notation 260

In this document, features are described as required, recommended, allowed or DEPRECATED as 261 follows: 262

Required (or shall or mandatory)(M). 263

– These basic features shall be implemented to comply with Core Architecture. The phrases "shall 264 not", and "PROHIBITED" indicate behaviour that is prohibited, i.e. that if performed means the 265 implementation is not in compliance. 266

Recommended (or should)(S). 267

– These features add functionality supported by Core Architecture and should be implemented. 268 Recommended features take advantage of the capabilities Core Architecture, usually without 269 imposing major increase of complexity. Notice that for compliance testing, if a recommended 270 feature is implemented, it shall meet the specified requirements to be in compliance with these 271 guidelines. Some recommended features could become requirements in the future. The phrase 272 "should not" indicates behaviour that is permitted but not recommended. 273

Allowed (may or allowed)(O). 274

– These features are neither required nor recommended by Core Architecture, but if the feature 275 is implemented, it shall meet the specified requirements to be in compliance with these 276 guidelines. 277

DEPRECATED. 278

– Although these features are still described in this document, they should not be implemented 279 except for backward compatibility. The occurrence of a deprecated feature during operation of 280 an implementation compliant with the current document has no effect on the implementation’s 281 operation and does not produce any error conditions. Backward compatibility may require that 282 a feature is implemented and functions as specified but it shall never be used by 283 implementations compliant with this document. 284

Conditionally allowed (CA) 285

– The definition or behaviour depends on a condition. If the specified condition is met, then the 286 definition or behaviour is allowed, otherwise it is not allowed. 287

Conditionally required (CR) 288

– The definition or behaviour depends on a condition. If the specified condition is met, then the 289 definition or behaviour is required. Otherwise the definition or behaviour is allowed as default 290 unless specifically defined as not allowed. 291

292

Strings that are to be taken literally are enclosed in "double quotes". 293

Words that are emphasized are printed in italic. 294


5 Overview 295

5.1 Introduction 296

This document defines the OCF Cloud API for Cloud Services. In this document Origin Cloud refers 297 to the OCF Cloud or the 3rd party Cloud through which the user works with his OCF Devices, Target 298 Cloud refers to the OCF Cloud to which OCF Servers (OCF Devices) are connected which the user 299 wants to control via the Origin Cloud. 300

An OCF Device is a collection of Resources, each Resource being an OpenAPI 2.0 defined object 301 that represents a physical property or characteristic of the Device (e.g. temperature sensed, light 302 colour, power on switch). The Device itself has an associated Device Type that provides an 303 indication of what the Device is, for example a Light is represented as a Device Type of "oic.d.light". 304

Please see Figure 1 for a representation of the target architecture. 305

306

Figure 1 – OCF Cloud Overview 307

The OCF Cloud API for Cloud Services supports the following cases: 308

– Account Linking API (clause 7) 309

– Initial Account Linking 310

– Removal of linked account 311

– Devices API (clause 8) 312

– Retrieval of all Devices associated with a User (clause 8.3) 313

– Retrieval of a single Device associated with a User (clause 8.4) 314

– Retrieval of a single Resource (clause 8.5) 315

– Update of a single Resource (clause 8.6) 316

– Events API (clause 9) 317

– Subscription to an event: establishment of a subscription (clause 9.4.1) 318

– Notification: event generated on an established subscription (clause 9.4.3) 319

5.2 General OCF Cloud API for Cloud Services Elements 320

The OCF Cloud API for Cloud Services is a RESTful API over HTTPS (IETF RFC 2818). The API 321 is defined using OpenAPI 2.0. 322

The Origin Cloud communicates with the Target Cloud using the domain name or URI it has 323 obtained from the initial OAuth 2.0 (IETF RFC 6749) Client Setup, covered in clause 7. 324 Communication between OCF Devices and OCF Clouds is defined in the OCF Device to Cloud 325 Services Specification. 326


All URIs presented within a "href" Link Parameter present in any payload shall be in the form 327 "/<deviceId>/<resourcehref>"; where <deviceId> is the identity of the Device as provided in the "di" 328 Property of "/oic/d" and "resourcehref" is the "href" of the Resource as provided by the Target Cloud. 329

An Origin Cloud shall obtain a Bearer Token from the Target Cloud using standard OAuth2.0 (IETF 330 RFC 6749) mechanisms. All subsequent requests from an Origin Cloud to the Target Cloud shall 331 include this Bearer Token for the user in question. 332

Any query parameters received by an Origin Cloud in a request from an OCF Client shall be passed 333 through clean (i.e. are part of the URI) in any request that is sent to a Target Cloud. 334

Each request may contain an optional HTTP Correlation-ID header, which carries a unique identifier 335 value that provides a reference to a particular transaction or event chain in the Target Cloud. 336

All requests shall include an HTTP Accept header. All requests or responses that carry content 337 shall include an HTTP Content-Type header. At a minimum media-types "application/json" and 338 "application/vnd.ocf+cbor" shall be supported. If the recipient of a request cannot provide a 339 response that is encoded according to the content of the Accept header, then a HTTP 406 (not 340 acceptable) response should be sent in accordance with IETF RFC 2818. On reception of a 406 341 response the originator of the request may re-attempt the request using an alternative Content-342 Type if supported. 343

5.3 Cloud to Cloud Operational Overview 344

5.3.1 Introduction 345

This clause provides an informative overview of the flows that are enabled by the detailed API 346 defined in clauses 6, 7, 8, and 9. Clause 5.3 provides references to the applicable clauses within 347 this document that define the API specifics. 348

5.3.2 Conceptual Architecture 349

Figure 2 describes the overall conceptual architecture. 350

D2CAPI

D2CAPI

Cloud ARD

Cloud BRD

/oic/sec/account

Cloud Information

OAuthClient

OAuthServer

Devices & Events API

Event stream

Events Webhook

API Client

/oic/sec/account

HTTPS (Cloud A authenticated)

351

Figure 2 – Conceptual Architecture 352


5.3.3 Authorizing Cloud Connectivity 353

Consider a user who has accounts on two distinct, separately owned clouds, and devices 354 associated with each of those accounts on those clouds. The user wants to have a unified view of 355 all of their devices from a single client rather than having a client per cloud. The user via the client 356 they want to use for all devices indicates to the directly connected cloud (Origin Cloud) that they 357 want to link this account with an account on the other cloud (Target Cloud). This initiates a standard 358 OAuth2.0 Authorization Code Grant Type flow, see IETF RFC 6749, clause 1.3.1. Application of 359 this flow is described in clause 7. 360

5.3.4 Synchronization of User's set of Devices 361

After completion of the Authorization Code Grant Type flow from clause 5.3.3 the Origin Cloud (that 362 is the cloud to which the user is connected) is authorized to use the Device API to obtain on behalf 363 of the user the complete list of devices hosted on the Target Cloud for which the user has access. 364 The API is described in clause 8, and the flow is further illustrated in clause A.4. 365

The result of the invocation of the Device API is a complete set of device information that may then 366 be provided in a response to a RETRIEVE on "/oic/res" from the Origin Cloud. 367

5.3.5 Keeping Up-to-Date: Notifications of changes on other Clouds 368

Once the set of devices has been obtained, the Origin Cloud can subscribe to the events to which 369 it is interested across the user's complete device set ("/devices"), or per device in that set 370 ("/devices/{deviceid}"). See clause 9 for details of the API itself. 371

The subscription to "/devices" enables the Origin Cloud to be notified whenever a new device is 372 added or an existing device removed from the Target Cloud. 373

The subscription to "/devices/{deviceid}" enables the Origin Cloud to be notified whenever there is 374 a change in the state of a device (e.g. it has de-registered). 375

When a new Device registers on the Target Cloud, and a subscription exists for that event, then a 376 notification is sent to the Origin Cloud with an event type of "devices_registered" and a payload 377 which contains the "di" of the newly registered device. The Origin Cloud may then RETRIEVE the 378 Links exposed by the newly added device using "/devices/{deviceid}" where "deviceid" was 379 provided in the payload of the notification. See clause A.10 for a flow illustrating this interaction. 380

5.3.6 Handling of Requests and Responses for Connected Devices 381

From the perspective of the client connected to the Origin Cloud there is no distinction between 382 devices and their Resources hosted by the Origin Cloud itself and devices and their resources that 383 are hosted by a Target Cloud reached via this API. 384

Thus all requests for a target resource are formed using the mechanisms described in the OCF 385 Device to Cloud Services Specification. 386

The Origin Cloud identifies the Target Cloud for the requested Resource via the "deviceid" that is 387 in the request URI which is matched to the "di" Property in "/oic/sec/account". The request is then 388 effectively proxied to the Target Cloud via the "/devices/{deviceid}/{resourcehref}" API exposed by 389 the Target Cloud (see clause 8.5 and 8.6). Any query parameters received over the device to cloud 390 connection are included in the URI unaltered. The content-type of the payload in the request or 391 response is honoured. See clauses A.6 and A.7 for illustrative flows of this mechanism for both 392 RETRIEVE and UPDATE cases. 393

6 Authentication & Authorization 394

A Target Cloud shall only expose secure endpoints; any requests received over an unsecured 395 connection (i.e. HTTP) shall be redirected to the secure equivalent of that endpoint. The Target 396


Cloud's End-Entity certificate used to secure the HTTPS connection shall contain the UUID of the 397 Cloud, available in the Common Name field. The Origin Cloud shall use the "Bearer" authentication 398 scheme inside the "Authorization" request header field to transmit the access token, as per IETF 399 RFC 6750 clause 2.1. For definition of the "Authorization" request header field, see IETF RFC 2818. 400

.0 Bearer Tokens issued by the Target Cloud shall identify the user as well as the client that is 401 sending requests on behalf of the user to the Target Cloud. 402

On the OCF Server side there is no distinction between requests forwarded from the Origin Cloud 403 and requests coming via the Target Cloud. 404

7 Account Linking API 405

7.1 General 406

The account linking API is the mechanism by which Devices hosted on behalf of a user by the 407 Target Cloud are linked with a user identity on the Origin Cloud. Account linking is established 408 solely between the Origin Cloud and the Target Cloud; an Origin Cloud shall not proxy devices 409 from the Target Cloud to another third-party Cloud. 410

The OAuth 2.0 Origin Cloud Client has to be registered with the Target Cloud as a prerequisite to 411 initiating the Authorization Code Grant Type flow, which allows the user to link his Origin Cloud 412 account with the Target Cloud. This process is named OAuth Application registration and is beyond 413 the scope of this specification. Successful registration of the OAuth 2.0 Origin Cloud Client in the 414 Target Cloud relies on the two entities establishing trust and obtaining the required client 415 parameters and OAuth2,0 Token Endpoints (e.g. client id, client secret, allowed redirect URIs). 416 See IETF RFC 6749, clause 2. 417

The linking is then achieved via the use of an OAuth2.0 Authorization Code Grant Type. Part of the 418 linking process is the end-user consent, which is very important in cross-domain identity federation, 419 ensuring that a malicious OAuth 2.0 Origin Cloud Client cannot obtain authorization without the 420 awareness and explicit consent of the resource owner (that is the user) of the Target Cloud. The 421 Target Cloud presents to the user linking the account the precise scope of authorization information 422 being requested by the Client. Details about scopes are available in clause 7.2. After the user's 423 consent and subsequent authorization code exchange, the Bearer Token and refresh tokens (see 424 IETF RFC 6749) shall be obtained from the Target Cloud by the Origin Cloud, following the format 425 and Content Type in IETF RFC 6750 clause 4. The Bearer Token identifies a user identity on the 426 Target Cloud. 427

The "state" query parameter shall be present in each authorization request, see IETF RFC 6749 428 clause 4.1.1. State is an opaque value used by the Origin Cloud Client to maintain state between 429 the request and the callback during the account linking process, see clause A.3. 430

All requests, responses, and error codes that may be sent during Account Linking shall conform to 431 those defined in RFC 6749. 432

Once such a Bearer Token has been acquired, the Origin Cloud shall link the OAuth2.0 access and 433 refresh token with its known local "userid". The user who linked his Target Cloud account with the 434 Origin Cloud account is from this moment able to request all his devices through the Origin Cloud, 435 because the Origin Cloud can make requests to the Target Cloud on behalf of the Target Cloud 436 user account. However, if an Origin Cloud makes a request that is not included in the OAuth2.0 437 Access Token Scope granted by the Bearer Token, the Target Cloud shall reply with an appropriate 438 error response. 439

When a Bearer Token is first acquired, it is recommended that the Origin Cloud use the Device API 440 to retrieve the Device details for all Devices in OAuth2.0 Access Token Scope of the Bearer Token. 441


If the Origin Cloud supports the behaviour defined in the OCF Device to Cloud Services 442 Specification, then once the Origin Cloud has the set of Devices from the Target Cloud it creates 443 an instance of "/oic/sec/account" per Device. The optional Property "cloudid" in "/oic/sec/account" 444 is set to the OCF Cloud UUID of the Target Cloud available in the Common Name field of the End-445 Entity certificate. If the Property is missing, empty, or contains the same value as the UUID of the 446 Origin Cloud, then the Device is local to the Origin Cloud. 447

The Origin Cloud may use the Events API to establish a subscription with the Device(s) on the 448 Target Cloud; such that addition or deletion of Devices on the Target Cloud can be correctly 449 reflected in the Origin Cloud. When the Device is deregistered from the Target Cloud, that Device 450 is no longer accessible via the Origin Cloud. When the Bearer Token obtained from the Target 451 Cloud expires and the refresh token is still valid, the Origin Cloud may ask for a new Bearer Token 452 through the OAuth2.0 token endpoint of the Target Cloud. Whenever the refresh token expires, is 453 not available, or the Bearer Token cannot be obtained, the Origin Cloud shall remove all 454 associations with the Devices hosted by the Target Cloud. See IETF RFC 6749 for further details. 455

It is recommended that the Origin Cloud subscribe to events of every Device that is hosted on the 456 Target Cloud by using the subscription mechanism described in clause 9.6. 457

7.2 OAuth2.0 Access Token Scopes 458

This document defines a core set of OAuth2.0 Access Token Scopes, see IETF RFC 6749. An 459 Origin Cloud may request one or more of these scopes, a vendor extension thereof, or a vendor 460 specific scope(s) as part of the account linking process. If the scope being provided by the Target 461 Cloud is different from the requested scope, then that scope shall be included in the issued Access 462 Token (see clause 5.1 of IETF RFC 6749). If the Target Cloud supports Access Token requests 463 with no scopes provided, and an Access Token request with no scopes is received from the Origin 464 Cloud, then the returned Access Token from the Target Cloud shall grant access to all of the 465 OAuth2.0 Access Token Scopes defined in Table 1. 466

The description for each of the OAuth2.0 Access Token Scopes shall be presented to the user 467 during the account linking process by the OAuth2.0 server of the Target Cloud. The Target Cloud 468 user sees a description on the consent screen and give an explicit consent that the Origin Cloud 469 requesting that the Bearer Token is authorized to act on behalf of the user in the boundary of 470 obtained OAuth2.0 Access Token Scopes. 471

Table 1 – OAuth 2.0 AccessToken Scopes 472

OAuth2.0 Access Token Scope name

OAuth2.0 Access Token Scope description "The application will be able to:"

r:* Read

w:* Update

473

Table 2 details the OAuth2.0 Access Token Scopes that are applicable per API Endpoint. All API 474 Endpoints that are listed in Table 2 shall be supported by a Target Cloud. So, for example, if an 475 Origin Cloud sends a GET request to "/api/v1/devices?content=all" API Endpoint, the Origin Cloud 476 must have a Bearer Token that contains OAuth2.0 Access Token Scope "r:*" or a vendor extension 477 thereof 478


Table 2 – Applicable OAuth2.0 Access Token Scopes per API Endpoint 479

API Endpoint HTTP Request Type

Applicable scopes

/api/v1/devices GET r:*

/api/v1/devices?content=all GET r:*

/api/v1/devices/{deviceid} GET r:*

/api/v1/devices/{deviceid}?content=all GET r:*

/api/v1/devices/{deviceid}/{resourcehref} GET r:*

POST w:*

/api/v1/devices/subscriptions POST r:*

DELETE r:*

/api/v1/devices/{deviceid}/subscriptions POST r:*

DELETE r:*

/api/v1/devices/{deviceid}/{resourcehref}/subscriptions POST r:*

DELETE r:*

A vendor may extend the list of OAuth2.0 Access Token Scopes beyond those listed in Table 2. 480 They are extended by adding additional vendor-specific information before the * in the OAuth2.0 481 Access Token Scope name (e.g. "r:xyz:*"). How these extensions work is outside the scope of the 482 OCF but they may be present in the OAuth2.0 Access Token request. Note that if the user gives 483 consent to the Origin Cloud to "w:*", consent applies also to any derived OAuth2.0 Access Token 484 Scopes (e.g. "w:xyz:*"). 485

8 Devices API 486


The Devices API supports the ability to retrieve and interact with the OCF Devices that are within 488 the scope of the provided Bearer Token. 489

8.2 Parameters Supported in Requests 490

Table 3 lists the parameters that may be provided as part of a request within the Device API. 491

Table 3 – Parameters used in Requests in the Device API 492

Friendly Name Parameter Name Location Mandatory Description

Accept Accept HTTP Header Yes An Accept request HTTP header advertises which content types, expressed as MIME types, the Origin Cloud is able to understand. The Target Cloud then selects one of the proposed content types and informs the Origin Cloud of its choice with the Content-Type response header.

Content Type Content-Type HTTP Header No The Content-Type header is used to indicate the media


type of the payload. A Content-Type header tells the recipient what the content type of the returned payload actually is.

Correlation ID Correlation-ID HTTP Header No A Correlation ID, also known as a Transit ID, is a unique identifier value that is attached to requests and messages that allows reference to a particular transaction or event chain.

Content content=[base, all]

Query String Parameter

No When set to "base" this indicates to the recipient that the response payload Links are not resolved. When set to "all" this indicates to the recipient that the response payload is the resolved (i.e. resource representation) Link and not the Link itself. If not present "base" is assumed.

493

8.3 Retrieve All Devices 494

8.3.1 Summary 495

This request is sent from the Origin Cloud to the Target Cloud in order to obtain information on all 496 the Devices that are registered for the user that are in scope as defined by the Bearer Token on 497 the Target Cloud. 498

A request to this API may be invoked by the Origin Cloud on completion of account linking. Where 499 the Cloud supports the behaviour defined in the OCF Device to Cloud Services Specification this 500 may also be invoked by reception of a RETRIEVE to "/oic/res" of the Cloud Resource Directory 501 from an OCF Client. 502

Table 4 provides a summary of the API. 503

Table 4 – Retrieve All Devices API Summary 504

HTTP Request

Type

API Endpoint Parameters Response Code Response Payload

GET /api/v1/devices content=[base, all], Correlation-ID, Accept

200 See clause B.1 - array of /definitions/Device (for content=base) and /definitions/DeviceContentAll (for content=all)

400, 401, 403, 503, 504

The response may include a diagnostic payload containing a reason string.

8.3.2 Request and Response Payload 505

There is no required payload in the request; if one is received at the Target Cloud it shall be ignored. 506 The required response payload for a request that includes "content=base" or no "content" 507 parameter shall be an array of objects; each object shall contain the Properties identified in the 508 schema provided in Annex B, a device id, device name, status Property ("status") that indicates 509 whether the Device is online or offline and an array of Links (as defined for "/oic/res") for the 510 Resources exposed by the specific Device. The minimum set of Resources that are exposed 511


depends on the OCF Device Type of the Device; this shall be the set defined in clause 6.1.3.2.1 of 512 the OCF Device to Cloud Services Specification. 513

If the request includes "content=all" (analogous to a batch retrieval of /oic/res in the proximal 514 network) then the response payload shall be as defined for "content=base" with the exception that 515 instead of an array of Links to the hosted Resources, the response payload shall include an array 516 of the representations of the Resources themselves that are exposed for each Device that is 517 available. This is illustrated in the examples provided for the Device API in Annex B. See also the 518 definition of a batch response in ISO/IEC 30118-1:2018. 519

8.3.3 Responses 520

A 200 response shall be provided in a success case. The payload shall contain information for all 521 Devices that are in the scope of the Bearer Token. 522

A non-success path response that is indicative of the type of error shall be returned by a Target 523 Cloud if an error scenario is detected. Table 5 lists possible non-success path responses and 524 possible scenarios that trigger their generation; an implementation may support additional 525 responses as defined by IETF RFC 2818. 526

Table 5 – Devices API non-success path responses 527

Response Code

Response scenario

400 Sent by the Target Cloud if the request was malformed or badly constructed

401 Sent by the Target Cloud if the request is unauthorized (e.g. an invalid or missing Bearer Token)

403 Sent by the Target Cloud if the requestor is known however the OAuth2.0 Access Token Scope of the request is forbidden

406 Sent by the Target Cloud if the media type in the received Accept header is not supported/acceptable

503 Sent by the Target Cloud if the service on the Target Cloud is unavailable

504 Sent by the Target Cloud if the target Device is registered at the Target Cloud, however the Device itself is unavailable, offline, or otherwise unreachable. The response should include a Retry-After header containing the time after which the request may be re-attempted. Additional information may be indicated in a diagnostic payload

528

8.4 Retrieve One Device 529

8.4.1 Summary 530

This request may be sent from the Origin Cloud to the Target Cloud in order to obtain information 531 on a specific Device that is registered for the user that is in scope as defined by the Bearer Token 532 on the Target Cloud. 533

A request to this API may be invoked at the Origin Cloud following reception of a notification that 534 a new Device has been added to a partner cloud, or alternatively as part of the flow following 535 account linking. Where the Origin Cloud supports the OCF Device to Cloud Services Specification, 536 a request to this API may also be invoked following reception of a RETRIEVE to "/oic/res" of the 537 Origin Cloud Resource Directory from an OCF Client with a query parameter that specifies a 538 particular "deviceid" (i.e. "?anchor=ocf://<some device id>"). 539



Table 6 – Retrieve One Device API Summary 541

HTTP Request

Type

API Endpoint Parameters Response Code

Response Payload

GET /api/v1/devices/{deviceid }

content=[base, all], Correlation-ID, Accept

200 See B.1 - /definitions/Device (for content=base) and /definitions/DeviceContentAll (for content=all)

400, 401, 403, 404, 503, 504

The response may include a diagnostic payload containing a reason string

542


There is no required payload in the request; if one is received at the Target Cloud it shall be ignored. 544

The "deviceid" in the URI of the request is the same as the "di" Property from /oic/d of the target 545 OCF device. 546

The response payload shall be an object containing the mandatory Device information as defined 547 in clause 8.3.2. 548

8.4.3 Responses 549

A 200 response shall be provided in a success case. The payload shall contain information for the 550 requested Device. 551


Table 7 – Device API non-success path responses 556

Response Code

Response scenario




404 Sent by the Target Cloud if the indicated "deviceid" is not present on the Target Cloud





557

8.5 Retrieve Specific Resource 558

8.5.1 Summary 559

This request is sent from the Origin Cloud to the Target Cloud in order to obtain information on a 560 specific Resource that is exposed by a Device that is registered for the user that is in scope as 561 defined by the Bearer Token on the Target Cloud. 562

Where the Cloud supports the OCF Device to Cloud Services Specification this may be triggered 563 by reception of a RETRIEVE to a URI exposed by a Link in the Cloud Resource Directory from an 564 OCF Client. 565


Table 8 – Retrieve Specific Resource API Summary 567

HTTP Request

Type


Response Payload

GET /api/v1/devices/{deviceid}/{resourcehref} Correlation-ID, Accept

200 Response payload as defined by OCF for the target Resource Type

400, 401, 403, 404

The response may include a diagnostic payload containing a reason string

503 The response may include a diagnostic payload containing a reason string

504 Retry-After header and optionally a diagnostic payload containing a reason string.

568


There is no required payload in the request; if one is received at the Target Cloud it shall be ignored. 570

The "deviceid" in the URI in the request is the same as the "di" Property from "/oic/d" of the target 571 OCF device. The "resourcehref" in the URI is the same as the "href" Link Parameter for the target 572 Resource instance. 573

The response payload shall be as defined by OCF for the Resource being received, or as defined 574 by the vendor if the Resource is a 3rd party Resource. 575

The content-type of the response payload received from the target server is honoured; that is the 576 content and payload as received by the Target Cloud shall be proxied unaltered in the response. 577 Thus for example in the case where the target server is an OCF Device the content type would be 578 "application/vnd.ocf+cbor". 579

An Origin Cloud shall include unaltered in the requestURI of the request sent to the Target Cloud 580 any query parameters received over the device to cloud connection. 581


8.5.3 Responses 582

A 200 response shall be provided in a success case. The payload in the response shall be as 583 defined in http://oneiota.org for the target Resource Type. 584


Table 9 – Resource Retrieval API non-success path responses 589

Response Code

Response scenario




404 Sent by the Target Cloud if the indicated "deviceid" is not present on the Target Cloud or the "resourcehref" is not found




590

8.6 Update a Resource on a Device 591

8.6.1 Summary 592

This request is sent from the Origin Cloud to the Target Cloud in order to update information 593 contained within a specific Resource exposed by a Device that is registered for the user that is in 594 scope as defined by the Bearer Token on the Target Cloud. 595

Where the Cloud supports the OCF Device to Cloud Services Specification a request to this API 596 may be triggered by reception of an UPDATE to a URI exposed by a Link in the Cloud Resource 597 Directory from an OCF Client. 598


Table 10 – Update Resource API Summary 600

HTTP Request

Type


Response Payload

POST /api/v1/devices/{deviceid}/{resourcehref} payload, 200 Optional resource representation

http://oneiota.org/


Correlation-ID, Accept, Content-Type

400, 401, 403, 404, 415

The response may include a diagnostic payload containing a reason string.

503 The response may include a diagnostic payload containing a reason string.

504 Retry-After header and optionally a diagnostic payload containing a reason string

601


The request payload shall be as defined by OCF for the Resource being updated, or as defined by 603 the vendor if the Resource is a 3rd party Resource. 604

The "deviceid" in the URI in the request is the same as the "di" Property from /oic/d of the target 605 OCF device. The "resourcehref" in the URI is the same as the "href" Link Parameter for the target 606 Resource instance. 607

The response payload shall be as defined by OCF for the Resource being received, or as defined 608 by the vendor if the Resource is a 3rd party Resource. 609

The Content-Type of the request is defined in an HTTP Content-Type header. In the case that the 610 request was initiated by another OCF Device, the CoAP content-format header value shall be 611 mapped to the HTTP Content-Type header to the Target Cloud. If the value is not present, the 612 Target Cloud shall forward the request as-is. Thus for example in the case where the origin client 613 is an OCF Device the CoAP content-format option would be "application/vnd.ocf+cbor", which is 614 passed to the Target Cloud as an HTTP Content-Type header. 615

An Origin Cloud shall include unaltered in the requestURI of the request sent to the Target Cloud 616 any query parameters received over the device to cloud connection. 617

8.6.3 Responses 618

A 200 response shall be provided in a success case. The payload may optionally contain the 619 representation of the Resource that was updated. 620


Table 11 – Resource Update API non-success path responses 625

Response Code

Response scenario





404 Sent by the Target Cloud if the indicated "deviceid" is not present on the Target Cloud or the "resourcehref" is not found


415 sent by the Target Cloud if an unsupported media type was specified in the Content-Type header



626

9 Events API 627


The Events API supports the ability for an interested party to subscribe to events and subsequently 629 receive notifications for those events. The events can be at the Resource level (like a CoAP 630 observe) or at a more system level (such as for a change in the set of known Devices). 631

The Events API makes use of a webhook mechanism whereby the Target Cloud notifies the Origin 632 Cloud when a new event has occurred on the Target Cloud or any OCF Device linked with the 633 Target Cloud. This event stream (continual series of notifications) may be started by sending an 634 initial subscription request to the Target Cloud specifying "eventTypes", "eventsUrl" (the API 635 Endpoint to which notifications are sent), and the "signingSecret", the latter to verify whether 636 requests from the Target Cloud are authentic. See clause 9.2. for details on the mechanism for 637 how the "signingSecret" is used and clause 9.4.1 for details on the subscription request. 638

A Subscription ID shall be provided in the response to an initial subscription request. The 639 Subscription ID is a unique string of type UUID, which shall be created and persisted by the Target 640 Cloud. The created ID shall be part of each notification sent to the configured "eventsUrl". The 641 Subscription ID shall also be used to DELETE this subscription. The Subscription ID is either 642 present in a response payload or within a HTTP header depending on the operation being 643 undertaken. See clauses 9.4.2 and 9.4.3 for more details. 644

After the subscription is successful, the Target Cloud shall send an initial notification to the Origin 645 Cloud "eventsUrl" (that was provided during establishment of the subscription) with the current 646 state of the items to which the subscription applies. The Target Cloud shall send further 647 notifications to the Origin Cloud whenever any changes occur (i.e. events) to the items to which 648 the subscription applies. 649

Following the Origin Cloud’s successful subscription to events of the Target Cloud, the Target 650 Cloud shall start sending notifications only after it establishes a new server-authenticated TLS1.2 651 connection to the "eventsUrl" as specified by the Target Cloud. 652

Notifications generated by the Target Cloud in response to a subscription shall only be for devices 653 and system changes the Bearer Token authorizes. 654

9.2 Events Authentication 655

Hash-based Message Authentication Code (HMAC) signatures are a way to sign the notification 656 data using the "signingSecret" that only the Origin Cloud and Target Cloud know. The 657 "signingSecret" shall be created by the Origin Cloud and sent within the subscription request as 658


defined in the clause 9.4.1. After a successful subscription, the Target Cloud shall sign each 659 notification using the HMAC-SHA256 hashing algorithm following the formula from the clause 9.2.1. 660 The calculated signature shall be attached as the "Event-Signature" header with each notification 661 request sent to the Origin Cloud. 662

The signature shall be used by the Origin Cloud to verify the legitimacy of the source and data 663 itself. When the notification is received by the Origin Cloud it shall use its stored secret and the 664 notification to generate its own HMAC-SHA256 signature using the formula from the clause 9.2.2 665 to compare with the value from the "Event-Signature" header. 666

When the signing secret and notification request are the same on both sides then the HMAC 667 signature will match. This match proves the authenticity of the request and data. 668

When the HMAC signature does not match, the Origin Cloud shall ignore the notification request 669 message. 670

Detailed overview is provided in figures A.8.2, A.9.2, A.10.2, and A.11.2. 671

9.2.1 Create Event Signature 672

1) Get the current timestamp in the Unix time format; this is used to populate the "Event-Timestamp" 673 header. 674

2) Concatenate the "Content-Type", the "Event-Type", the "Subscription-ID", the "Sequence-675 Number", the "Event-Timestamp" header values and the notification body together, using a colon 676 as a delimiter. 677

3) Hash the resulting string, using the "signingSecret" as a key using the HMAC-SHA256 hashing 678 algorithm, and taking the hex digest of the hash. 679

4) Include the resulting signature to the "Event-Signature" header of the notification and timestamp 680 to the "Event-Timestamp" header 681

9.2.2 Verify the Event Signature 682

1) Concatenate the "Content-Type", the "Event-Type", the "Subscription-ID", the "Sequence-683 Number", the "Event-Timestamp" header values and the notification body together, using a colon 684 as a delimiter. 685

2) Hash the resulting string, using the "signingSecret" as a key using the HMAC-SHA256 hashing 686 algorithm and take the hex digest of the hash. 687

3) Compare the resulting signature to the "Event-Signature" header of the received notification 688

9.3 Parameters Supported 689

Table 12 lists the parameters that may be provided within the Events API. 690

Table 12 – Parameters used in the Events API 691

Friendly Name Parameter Name

Location Mandatory Description

Accept Accept HTTP Header Yes An Accept request HTTP header advertises which content types, expressed as MIME types, the client is able to understand. The resource server then selects one of the proposal and informs the client of its choice with the Content-Type response header. Each notification sent to the defined


"eventsUrl" is then using this Accepted content type.

Correlation ID Correlation-ID HTTP Header No A Correlation ID, also known as a Transit ID, is a unique identifier value that is attached to requests and responses that allows reference to a particular transaction or notification.

Content Type Content-Type HTTP Header No The Content-Type header is used to indicate the media type of the payload. A Content-Type header tells the recipient what the content type of the returned payload actually is.

9.4 Events API subscription and notification payload definitions 692

9.4.1 Subscription request 693

A subscription request is sent by an Origin Cloud to the API Endpoint defined for the event type to 694 which the subscription is targeted. The set of event types and associated API Endpoints is provided 695 in Table 13. 696

Subscription to a "subscription_cancelled" event type is not done explicitly by an Origin Cloud; it 697 shall always be enabled at the Target Cloud whenever any other supported event type is the target 698 of a subscription. 699

Table 13 – Event types and API Endpoints 700

Event-Type API Endpoint

subscription_cancelled N/A as a subscription_cancelled event type is not explicitly subscribed to.

devices_registered

/api/v1/devices/subscriptions

devices_unregistered

/api/v1/devices/subscriptions

devices_online /api/v1/devices/subscriptions

devices_offline /api/v1/devices/subscriptions

resource_contentchanged

/api/v1/devices/{deviceid}/{resourcehref}/subscriptions

resources_published /api/v1/devices/{deviceid}/subscriptions

resources_unpublished /api/v1/devices/{deviceid}/subscriptions

701

Annex B.1.2 provides a definition of the payload contained within the subscription request. The 702 Properties that are contained in the payload are further clarified in Table 14. 703

Table 14 – Subscription Request Payload Properties 704

Payload Property Name Value type Mandatory Description

eventsUrl URI Y URI to which notifications are to be sent

eventTypes array of enum Y Event type(s) for which the subscription is targeted. See Table 13


signingSecret String of length 32 Y Secret used to create HMAC signature for each event

705

Figure 3 is an example of such a payload. 706

{ "eventsUrl": "https://mynotificationuri", "eventTypes": ["resource_contentchanged"], "signingSecret": "DVDUEBe5nciVSXU85BPxrAjSsHenTzWY" }

Figure 3 – Subscription Request Example 707

9.4.2 Subscription response 708

The definition of the response to a subscription request is in Annex B.1. The Properties that are 709 contained with the payload are further clarified in Table 15. 710

Table 15 – Subscription Response Properties 711

Payload Property Name Value type Mandatory Description

subscriptionId uuid Y Identity of the subscription (the Subscription ID). May be mapped from other protocols if a unique identifier exists. Note this cannot be mapped from a CoAP Token as the Token in CoAP is Client-local in scope (i.e. not guaranteed unique beyond the Client issuing the request).

712

Figure 4 is an example of such a payload. 713

{ "subscriptionId": "1eeb465c-5e8d-4305-a366-bbf035fff671" }

Figure 4 – Subscription Response Example Payload 714

9.4.3 Notification request 715

When a subscription is first successfully established, the Target Cloud shall send a POST request 716 to the "eventsUrl" that was provided in the subscription with the current state of the items to which 717 the subscription applies. 718

When there is a subsequent change (i.e. an event) that triggers a notification, the Target Cloud 719 shall send a POST request to the "eventsUrl" that was provided in the subscription. The Target 720 Cloud shall populate all headers defined in Table 16 in the POST that is sent to the "eventsUrl" 721 provided by the Origin Cloud together with any notification payload. 722

The Target Cloud shall send a notification to the "eventsUrl" provided by the Origin Cloud if there 723 is a cancellation of the subscription. Cancellation may be done by either the Target Cloud or the 724 Origin Cloud using a DELETE as described in clauses 9.5, 9.6, and 9.7. 725

https://mynotificationuri/


Table 16 – Notification request HTTP Headers 726

HTTP Header Value Type Mandatory Description

Correlation-ID UUID Yes A Correlation ID, also known as a Transit ID, is a unique identifier value that is attached to requests and responses that allows reference to a particular transaction or event chain.

Content-Type String Yes Indicates the media type of the notification payload

Event-Type String Yes Type of the event

Subscription-ID

UUID Yes Subscription identifier for which this notification is being sent

Sequence-Number

String encoded Integer Yes Sequence number of the notification; the first notification shall have a value of 0, this value shall be incremented by 1 (one) for all subsequent notifications

Event-Timestamp Unix time format Yes Time when the event occurred in standard Unix time format

Event-Signature String Yes HMAC-SHA256 signature proving the authenticity of the request and data. See 9.2 Events Authentication

727

The format of the payload in a notification request depends on the event type for which the 728 subscription was created. Table 17 defines the format of the payload provided in a notification per 729 "eventType" (as received in the payload of the subscription request from the Origin Cloud) that may 730 be sent by the Target Cloud. A Target Cloud shall populate the notification payload for the event 731 type being signalled in the Event-Type HTTP header as defined in Table 17. The schema definitions 732 for all payloads are provided in Annex B.1.2. 733

Table 17 – Event type to notification payload content 734

Event-Type header population

Notification payload on establishment of the

subscription

Notification payload per subsequent notification

subscription_cancelled

Not present Not applicable

devices_registered

Array of all currently registered Device IDs

Array containing Device IDs that have been registered since the previous notification was sent.

devices_unregistered

Empty array (i.e. []) Array containing Device IDs for devices that have been de-registered since the previous notification was sent

devices_online Array of all currently online Device IDs

Array containing Device IDs that have come online since the previous notification was sent.

devices_offline Array of all currently offline Device IDs

Array containing Device IDs for devices that have gone offline since the


previous notification was sent

resource_contentchanged

Empty string (i.e. "") Payload of the changed Resource as received by the Target Cloud

resources_published Array of Links of all published Resources for the Device ID in the path

Array of Links of all Resources published by the Device ID in the path since the previous notification was sent

resources_unpublished

Empty array (i.e. []) Array of Links of all Resources unpublished by the Device ID in the path since the previous notification was sent

735

9.5 Subscribe and unsubscribe to devices level event types 736

9.5.1 Summary 737

This request is sent from the Origin Cloud to the Target Cloud. An Origin Cloud may use this API 738 when it wants to receive notifications of events generated due to changes to the set of Devices that 739 are exposed. 740

Event types that may be subscribed to using this API are: devices_registered, 741 devices_unregistered, devices_online and devices_offline. 742

An Origin Cloud may establish a subscription by sending a POST request to the API Endpoint 743 shown in Table 18. To remove an existing subscription an Origin Cloud shall send a DELETE 744 request to the API Endpoint as shown in Table 13. 745


Table 18 – Subscription to /devices API Summary 747

HTTP Request

Type


Response Payload

POST /api/v1/devices/subscriptions Correlation-ID, Accept, Content-Type

201 See clause B.1 - /definitions/SubscribeResponse

400, 401, 403

DELETE /api/v1/devices/subscriptions/{subscriptionId} Correlation-ID 202

400, 401, 403, 404


The request payload for the POST shall be as defined in clause 9.4.1. 749

The "subscriptionId" in the URI for the DELETE case shall be the "subscriptionId" that was returned 750 in the response to the subscription POST request. 751

The response payload for the subscription POST request shall contain the Subscription ID in a 752 "subscriptionId" Property as defined in clause 9.4.2. 753


There is no required payload for a DELETE unsubscribe response. 754

9.5.3 Responses 755

A 201 response shall be sent by the Target Cloud in a success case. 756

A 202 response shall be sent by the Target Cloud following a DELETE request and indicates that 757 the subscription was marked for cancellation; confirmation of the cancellation of the subscription 758 shall be provided by a subsequent notification with an Event-Type of "subscription-cancelled". 759


Table 19 – Devices Event Subscription API non-success path responses 764

Response Code

Response scenario




404 Sent by the Target Cloud if the subscription was not found


765

9.6 Subscribe and unsubscribe to device level events 766

9.6.1 Summary 767

This request is sent from the Origin Cloud to the Target Cloud. This API is used when the Origin 768 Cloud wants to receive notifications for a specific Device on the Target Cloud. 769

Event types that may be subscribed to using this API are: resources_published and 770 resources_unpublished. 771



Table 20 – Subscription to Single Device API Summary 776

HTTP Request

Type


Response Payload

POST /api/v1/devices/{deviceid}/subscriptions Correlation-ID, Accept, Content-Type

201 See B.1 - /definitions/SubscribeResponse


400, 401, 403, 404

DELETE /api/v1/devices/{deviceid}/subscriptions/{subscriptionId}

Correlation-ID 202

400, 401, 403, 404



The “deviceid” in the request URI shall be the same as the "di" Property from "/oic/d" of the target 779 OCF device. 780




9.6.3 Responses 786




Table 21 – Device Event Subscription API non-success path responses 795

Response Code

Response scenario






9.7 Subscribe and unsubscribe to resource level events 796

9.7.1 Summary 797

This request is sent from the Origin Cloud to the Target Cloud. This API may be used by the Origin 798 Cloud to receive notifications from a specific observable Resource that exists on a specific Device 799 on the Target Cloud. 800

Events that may be subscribed to using this API are: resource_contentchanged. 801




Table 22 – Subscription to Resource API Summary 806

HTTP Request

Type


Response Payload

POST /api/v1/devices/{deviceid}/{resourcehref}/subscriptions

Correlation-ID, Accept, Content-Type

201 See B.1 - /definitions/SubscribeResponse

400, 401, 403, 404

DELETE /api/v1/devices/{deviceid}/{resourcehref}/subscriptions/{subscriptionId}

Correlation-ID 202

400, 401, 403, 404



The "deviceid" in the URI in the request shall be the same as the "di" Property from /oic/d of the 809 target OCF device. 810

The "resourcehref" in the URI shall be the same as the "href" Link Parameter for the target 811 Resource instance. 812




9.7.3 Responses 818




Table 23 – Resource Event Subscription API non-success path responses 827

Response Code

Response scenario







828

9.8 Notification of devices level events 829

9.8.1 Summary 830

This request is sent from the Target Cloud to the Origin Cloud whenever there is an initial 831 subscription to an event or an event for which a subscription exists occurs as defined in clause 9.5. 832


Table 24 – Notification of /devices API Summary 834

HTTP Request Type API Endpoint Parameters Response Code Response Payload

POST /{eventsUrl} Correlation-ID, Content-Type, Event-Type, Subscription-ID, Sequence-Number, Event-Signature, Event-Timestamp

200

400, 410


The “eventsUrl” in the URI shall be the value of the "eventsUrl" Property that was provided in the 836 subscription request. 837

The payload in the notification request depends on the Event-Type that is the subject of the 838 notification request; please see Table 17 for specifics and clause 9.4.3 for further information. 839

9.8.3 Responses 840

A 200 response shall be provided in a success case. 841

A non-success path response that is indicative of the type of error shall be returned by an Origin 842 Cloud if an error scenario is detected. Table 25 lists possible non-success path responses and 843 possible scenarios that trigger their generation; an implementation may support additional 844 responses as defined by IETF RFC 2818. 845

Table 25 – Devices Event Notification non-success path responses 846

Response Code

Response scenario

400 Sent by the Origin Cloud if the request was malformed or badly constructed

401 Sent by the Origin Cloud if the request is unauthorized (e.g. an invalid or missing Bearer Token)


403 Sent by the Origin Cloud if the requestor is known however the OAuth2.0 Access Token Scope of the request is forbidden

406 Sent by the Origin Cloud if the media type in the received Accept header is not supported/acceptable

410 Sent by the Origin Cloud if the subscription identified by the Subscription-ID header is no longer valid

847

9.9 Notification of Device level events 848

9.9.1 Summary 849



Table 26 – Notification of Single Device API Summary 853


POST /{eventsUrl} Correlation-ID, Content-Type Event-Type, Subscription-ID, Sequence-Number, Event-Signature, Event-Timestamp

200

400, 410




9.9.3 Responses 859



Table 27 – Device Event Notification non-success path responses 865

Response Code

Response scenario







866

9.10 Notification of Resource level events 867

9.10.1 Summary 868



Table 28 – Notification of Resource API Summary 872


POST /{eventsUrl} Correlation-ID, Content-Type Event-Type, Subscription-ID, Sequence-Number, Event-Signature, Event-Timestamp

200

400, 410




9.10.3 Responses 878



Table 29 – Resource Event Notification non-success path responses 884

Response Code

Response scenario







885


886

Representative Flows 887

A.1 Introduction 888

The flows illustrate use of the OCF Cloud API for Cloud Services using OCF Devices as the target 889 servers where applicable and OCF Clouds as the two Clouds that are invoking/acting as API 890 Endpoints. Note that this is for example use only and the API does not force this setup, which 891 means non-OCF clouds with non-OCF devices may also use the API for interworking with other 892 vendor’s clouds. 893

A.2 OAuth2.0 Application Registration 894

Figure A.1 provides an example flow showing the registration of the OAuth 2.0 Origin Cloud Client. 895

896

897

Figure A.1 – Establish Business Relationship Example Flow 898

A.3 Account Linking 899

Figure A.2 provides an example flow of the account linking for a particular user. 900


901

Figure A.2 – Initial Association Example Flow 902

A.4 Retrieval of all Devices 903

A.4.1 Summary 904

The Origin Cloud requests all Devices associated with a user (defined by the provided Bearer 905 Token). This may be invoked following account linking in order to retrieve the set of Devices for 906 the user. 907


A.4.2 Flow 908

909

Figure A.3 provides an example flow for the retrieval of all Devices. 910

911

Figure A.3 – Retrieve All Devices Example Flow 912

A.4.3 Flow Description 913

Table A.1 explains each element in the above sequence diagram 914

Table A.1 – Retrieve all Devices Flow Summary 915

Number Description

1 Cloud requests all Devices given by the scope in the Bearer Token that was obtained via OAuth.

2 Response is an array of Device information ( Properties that are defined in /oic/d that are pertinent to Cloud functionality and Device status).

3 Cloud maintains an association between the Device and the host Cloud.

916


A.5 Retrieval of a single Device 917

A.5.1 Summary 918

The Origin Cloud requests information for a single, specific Device associated with a user (defined 919 by the provided Bearer Token). This may be invoked by the Origin Cloud receiving a retrieve 920 request from a connected Client. 921

A.5.2 Flow 922

923

Figure A.4 provides an example flow for the retrieval of a single Device. 924

925

Figure A.4 – Retrieve Single Device Example Flow 926

A.5.3 Flow Description 927


Table A.2 – Retrieve single Device Flow Summary 929

Number Description

1 [OCF Device to Cloud] OCF Client role Device requests /oic/res from the Cloud for a specific anchor (device id).

2 [Assuming that the information hasn't been cached by the Cloud]


For the instance of /oic/sec/account that exists for the Device the Cloud does a GET /devices/{deviceid} to the Cloud identified by the "clouded" in "/oic/sec/account". {deviceid} is also taken from /oic/sec/account.

3 Response is the Device information as well as an array of Links. The "href" in each Link will be of the form "/deviceid/resourcehref".

4 Response payload.

A.6 Retrieval of a single Resource 930

A.6.1 Summary 931

The Origin Cloud requests information for a single, specific Resource exposed by a Device 932 associated with a user (defined by the provided Bearer Token). This may be invoked by the Origin 933 Cloud receiving a retrieve request from a connected Client. 934

A.6.2 Flows 935

A.6.2.1 Success Path 936

937

Figure A.5 provides an example flow for the retrieval of a single Resource. 938

939

Figure A.5 – Retrieve Resource (Success) Example Flow 940

A.6.2.2 Success Path Flow Description 941



Table A.3 – Retrieve single Resource Flow Summary 943

Number Description

1 [OCF Device to Cloud] OCF Client role Device requests a Resource from the Cloud using the "href" exposed in the /oic/res response. This will be of the form "/deviceid/resourcehref"

2 [Assuming that the resource representation hasn't been cached by the Cloud] Cloud identifies the host Cloud for the Resource via the instance of /oic/sec/account for the "deviceid". The request is then effectively proxied to the Target Cloud via a GET /devices/{deviceid}/{resourcehref}. Any query parameters received over CoAP are included in the URI unaltered.

3 [OCF Device to Cloud] Target Cloud identifies the TLS connection to the end Device via the {deviceid} and proxies the request.

4 Standard OCF response

5 Success path response including the response payload as received for the target Resource


A.6.2.3 Device is Temporarily Unavailable 944

945

Figure A.6 illustrates the case where the Device is temporarily unavailable. 946

947

Figure A.6 – Retrieve Resource (Timeout) Example Flow 948


A.7 Update of a single Resource 949

A.7.1 Summary 950

The Origin Cloud updates information for a single, specific Device associated with a user (defined 951 by the provided Bearer Token). This may be invoked by the Origin Cloud receiving an update 952 request from a connected Client. 953

A.7.2 Flows 954

A.7.2.1 Success Path 955

956

Figure A.7 provides an example flow for the updating of a single Resource. 957

958

Figure A.7 – Update Resource (Success) Example Flow 959

A.7.2.2 Success Path Flow Description 960


Table A.4 – Update single Resource Flow Summary 962

Number Description

1 [OCF Device to Cloud] OCF Client role Device requests a Resource from the Cloud using the "href" exposed in the /oic/res response. This will be of the form "/deviceid/resourcehref"


2 Cloud identifies the host Cloud for the Resource via the instance of /oic/sec/account for the "deviceid". The request is then effectively proxied to the Target Cloud via a POST /devices/{deviceid}/{resourcehref} including the payload from the original request. Any query parameters received over CoAP are included in the URI unaltered.

3 [OCF Device to Cloud] Target Cloud identifies the TLS connection to the end Device via the {deviceid} and proxies the request.


5 Success path response including the response payload as received for the target Resource


A.7.2.3 Device is Temporarily Unavailable 963

Figure A.8 illustrates the case where the Device is temporarily unavailable. 964

965

966

Figure A.8 – Update Resource (Timeout) Example Flow 967

A.8 Establishment of new subscription request 968

A.8.1 Summary 969

The Origin Cloud requests the establishment of an observe relationship with a single, specific 970 Resource on a Device associated with a user (defined by the provided Bearer Token). This may be 971 invoked by Origin Cloud receiving a retrieve request containing an observe option from a connected 972 Client. 973


Flows974

975

Figure A.9 provides an example flow for the establishment of a subscription to the 976 "resource_contentchanged" event for a specific Resource. 977

978

979

Figure A.9 – Observe Establishment Example Flow 980

A.9 Event generated for a subscription 981

A.9.1 Summary 982

An event occurs for a Resource with which the Origin Cloud has established a subscription/event 983 relationship. This may be invoked by the target end Device being updated. 984


Flows985

986

Figure A.10 provides an example flow for the handling of a generated "resource_contentchanged" 987 event. 988

989

Figure A.10 – "resource_contentchanged" Event Example Flow 990

A.10 Addition of new registration 991

A.10.1 Summary 992

The Origin Cloud has a priori established a subscription/event relationship with the set of Devices 993 associated with a user exposed by Target Cloud. The user then registers a new Device with Target 994 Cloud. 995


Flows996

997

Figure A.11 provides an example flow for the generation of a notification (event) when a new Device 998 is registered. 999

1000

Figure A.11 – Addition of new registered Device example flow 1001

A.11 Removal of existing device registration 1002

A.11.1 Summary 1003

The Origin Cloud has a priori established a subscription/event relationship with the set of Devices 1004 associated with a user exposed by Target Cloud. The user then removes a Device from Target 1005 Cloud. 1006


Flows1007

1008

Figure A.12 provides an example flow for the generation of a notification (event) when a Device is 1009 removed. 1010

1011

Figure A.12 – Removal of existing registration example flow 1012


1013

Open API Definition 1014

1015

B.1.1 Supported APIs 1016

B.1.1.1 /api/v1/devices 1017

Get all devices which are signed up to the OCF Cloud, either "online" or "offline". Devices which 1018 are "online" are signed in to the system and are accessible. "offline" devices are signed up to the 1019 system, but currently disconnected. 1020

B.1.1.2 /api/v1/devices/subscriptions 1021

An array of currently active subscriptions 1022

B.1.1.3 /api/v1/devices/subscriptions/{subscriptionId} 1023

Cancel subscription identified by the id returned in a response for subscription. 1024

B.1.1.4 /api/v1/devices/{deviceId} 1025

Device requested with content=all query parameter 1026

B.1.1.5 /api/v1/devices/{deviceId}/subscriptions 1027


B.1.1.6 /api/v1/devices/{deviceId}/subscriptions/{subscriptionId} 1029

Cancel subscription identified by the id returned in a response for subscription. 1030

B.1.1.7 /api/v1/devices/{deviceId}/{resourceLinkHref} 1031

Retrieve Resource Representation 1032

B.1.1.8 /api/v1/devices/{deviceId}/{resourceLinkHref}/subscriptions 1033


B.1.1.9 /api/v1/devices/{deviceId}/{resourceLinkHref}/subscriptions/{subscriptionId} 1035

Cancel subscription identified by the id returned in a response for subscription. 1036 1037

B.1.1.10 /{eventsUrl} 1038

Events endpoint provided during subscription where events specified in the subscription will be 1039 sent to as defined per event type. Confirmation of each event sent to the `eventsUrl` endpoint is 1040 required with `2xx` success code. Events you will receive based on event type you're subscribed 1041 to are: 1042 - `subscription_cancelled`: `SubscriptionCancelledEvent` 1043 - `devices_registered`: `DevicesRegisteredEvent` 1044 - `devices_unregistered`: `DevicesUnregisteredEvent` 1045 - `resources_published`: `ResourcesPublishedEvent` 1046 - `resources_unpublished`: `ResourcesUnpublishedEvent` 1047 - `devices_online`: `DevicesOnlineEvent` 1048 - `devices_offline`: `DevicesOfflineEvent` 1049 - `resource_contentchanged`: `ResourceContentChangedEvent` 1050

B.1.2 OpenAPI 2.0 definition 1051

{ 1052 "swagger": "2.0", 1053


"info": { 1054 "title": "OCF Cloud API for Cloud Services", 1055 "version": "0.0.3-20190828", 1056 "license": { 1057 "name": "Copyright 2019 Open Connectivity Foundation, Inc. All rights reserved.", 1058 "x-description": "Redistribution and use in source and binary forms, with or without 1059 modification, are permitted provided that the following conditions are met:\n 1. 1060 Redistributions of source code must retain the above copyright notice, this list of conditions and 1061 the following disclaimer.\n 2. Redistributions in binary form must reproduce the above 1062 copyright notice, this list of conditions and the following disclaimer in the documentation and/or 1063 other materials provided with the distribution.\n\n THIS SOFTWARE IS PROVIDED BY THE Open 1064 Connectivity Foundation, INC. \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 1065 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE OR 1066 WARRANTIES OF NON-INFRINGEMENT, ARE DISCLAIMED.\n IN NO EVENT SHALL THE Open Connectivity 1067 Foundation, INC. OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, 1068 OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 1069 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\n HOWEVER CAUSED AND ON 1070 ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 1071 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 1072 SUCH DAMAGE.\n" 1073 } 1074 }, 1075 "host": "api.example.com", 1076 "schemes": [ 1077 "https" 1078 ], 1079 "tags": [ 1080 { 1081 "name": "Devices", 1082 "description": "Basic information about devices" 1083 }, 1084 { 1085 "name": "Resources", 1086 "description": "Read or change the configuration of the device" 1087 }, 1088 { 1089 "name": "Events", 1090 "description": "Be notified about changes occuring on the device" 1091 } 1092 ], 1093 "paths": { 1094 "/api/v1/devices": { 1095 "parameters": [ 1096 { 1097 "$ref": "#/parameters/CorrelationId" 1098 }, 1099 { 1100 "$ref": "#/parameters/Accept" 1101 }, 1102 { 1103 "$ref": "#/parameters/BatchFormat" 1104 } 1105 ], 1106 "get": { 1107 "tags": [ 1108 "Devices" 1109 ], 1110 "summary": "Get all devices", 1111 "description": "Get all devices which are signed up to the OCF Cloud - either ònline` or 1112 òffline`. Devices which are ònline` are signed in to the system and are accessible. Offline 1113 devices are signed up to the system, but currently disconnected.\n", 1114 "produces": [ 1115 "application/json" 1116 ], 1117 "responses": { 1118 "200": { 1119 "description": "An array of devices", 1120 "schema": { 1121 "type": "array", 1122 "items": { 1123 "$ref": "#/definitions/Device" 1124


} 1125 } 1126 }, 1127 "400": { 1128 "$ref": "#/responses/BadRequest" 1129 }, 1130 "401": { 1131 "$ref": "#/responses/Unauthorized" 1132 }, 1133 "403": { 1134 "$ref": "#/responses/Forbidden" 1135 }, 1136 "503": { 1137 "description": "#/responses/ServiceUnavailable" 1138 }, 1139 "504": { 1140 "description": "#/responses/GatewayTimeout" 1141 } 1142 }, 1143 "security": [ 1144 { 1145 "oauth2": [ 1146 "r:*" 1147 ] 1148 } 1149 ] 1150 } 1151 }, 1152 "/api/v1/devices/subscriptions": { 1153 "parameters": [ 1154 { 1155 "$ref": "#/parameters/CorrelationId" 1156 }, 1157 { 1158 "$ref": "#/parameters/Accept" 1159 } 1160 ], 1161 "get": { 1162 "tags": [ 1163 "Events" 1164 ], 1165 "summary": "Get all active subscriptions created against the set of devices", 1166 "produces": [ 1167 "application/json" 1168 ], 1169 "responses": { 1170 "200": { 1171 "description": "An array of currently active subscriptions", 1172 "schema": { 1173 "type": "array", 1174 "items": { 1175 "$ref": "#/definitions/Subscription" 1176 } 1177 } 1178 }, 1179 "400": { 1180 "$ref": "#/responses/BadRequest" 1181 }, 1182 "401": { 1183 "$ref": "#/responses/Unauthorized" 1184 }, 1185 "403": { 1186 "$ref": "#/responses/Forbidden" 1187 }, 1188 "503": { 1189 "description": "#/responses/ServiceUnavailable" 1190 }, 1191 "504": { 1192 "description": "#/responses/GatewayTimeout" 1193 } 1194 }, 1195


"security": [ 1196 { 1197 "oauth2": [ 1198 "r:*" 1199 ] 1200 } 1201 ] 1202 }, 1203 "post": { 1204 "tags": [ 1205 "Events" 1206 ], 1207 "summary": "Subscribe to events against the set of devices", 1208 "description": "Subscribe to devices events by providing `eventTypes` you're interested in 1209 and `eventsUrl` endpoint where events will be sent to as defined. Successful response contains 1210 `subscriptionId` which identifies registered subscription and is part of each event. First event for 1211 each registered event type is received immediately after subscription and contains actual state of 1212 the resource, followed by new events in case of any change.\n\n**Supported events**\n- 1213 `devices_registered`\n- `devices_unregistered`\n- `devices_online`\n- `devices_offline`\n", 1214 "parameters": [ 1215 { 1216 "$ref": "#/parameters/ContentType" 1217 }, 1218 { 1219 "$ref": "#/parameters/SubscribeRequest" 1220 } 1221 ], 1222 "consumes": [ 1223 "application/json" 1224 ], 1225 "produces": [ 1226 "application/json" 1227 ], 1228 "responses": { 1229 "201": { 1230 "$ref": "#/definitions/SubscribeResponse" 1231 }, 1232 "400": { 1233 "$ref": "#/responses/BadRequest" 1234 }, 1235 "401": { 1236 "$ref": "#/responses/Unauthorized" 1237 }, 1238 "403": { 1239 "$ref": "#/responses/Forbidden" 1240 } 1241 }, 1242 "security": [ 1243 { 1244 "oauth2": [ 1245 "r:*" 1246 ] 1247 } 1248 ] 1249 } 1250 }, 1251 "/api/v1/devices/subscriptions/{subscriptionId}": { 1252 "parameters": [ 1253 { 1254 "$ref": "#/parameters/CorrelationId" 1255 }, 1256 { 1257 "$ref": "#/parameters/SubscriptionIdPath" 1258 } 1259 ], 1260 "delete": { 1261 "tags": [ 1262 "Events" 1263 ], 1264 "summary": "Unsubscribe from events against the set of devices", 1265 "description": "Cancel subscription identified by the id returned in a response for 1266


subscription.\n", 1267 "responses": { 1268 "202": { 1269 "description": "Subscription was marked for cancellation" 1270 }, 1271 "400": { 1272 "$ref": "#/responses/BadRequest" 1273 }, 1274 "401": { 1275 "$ref": "#/responses/Unauthorized" 1276 }, 1277 "403": { 1278 "$ref": "#/responses/Forbidden" 1279 }, 1280 "404": { 1281 "$ref": "#/responses/NotFound" 1282 } 1283 }, 1284 "security": [ 1285 { 1286 "oauth2": [ 1287 "r:*" 1288 ] 1289 } 1290 ] 1291 } 1292 }, 1293 "/api/v1/devices/{deviceId}": { 1294 "parameters": [ 1295 { 1296 "$ref": "#/parameters/CorrelationId" 1297 }, 1298 { 1299 "$ref": "#/parameters/Accept" 1300 }, 1301 { 1302 "$ref": "#/parameters/DeviceId" 1303 }, 1304 { 1305 "$ref": "#/parameters/BatchFormat" 1306 } 1307 ], 1308 "get": { 1309 "tags": [ 1310 "Devices" 1311 ], 1312 "summary": "Get the device by ID", 1313 "consumes": [ 1314 "application/json" 1315 ], 1316 "produces": [ 1317 "application/json" 1318 ], 1319 "responses": { 1320 "200": { 1321 "description": "Device requested with content=all query parameter", 1322 "schema": { 1323 "$ref": "#/definitions/DeviceContentAll" 1324 } 1325 }, 1326 "400": { 1327 "$ref": "#/responses/BadRequest" 1328 }, 1329 "401": { 1330 "$ref": "#/responses/Unauthorized" 1331 }, 1332 "403": { 1333 "$ref": "#/responses/Forbidden" 1334 }, 1335 "404": { 1336 "$ref": "#/responses/NotFound" 1337


}, 1338 "503": { 1339 "description": "#/responses/ServiceUnavailable" 1340 }, 1341 "504": { 1342 "description": "#/responses/GatewayTimeout" 1343 } 1344 }, 1345 "security": [ 1346 { 1347 "oauth2": [ 1348 "r:*" 1349 ] 1350 } 1351 ] 1352 } 1353 }, 1354 "/api/v1/devices/{deviceId}/subscriptions": { 1355 "parameters": [ 1356 { 1357 "$ref": "#/parameters/CorrelationId" 1358 }, 1359 { 1360 "$ref": "#/parameters/DeviceId" 1361 }, 1362 { 1363 "$ref": "#/parameters/Accept" 1364 } 1365 ], 1366 "get": { 1367 "tags": [ 1368 "Events" 1369 ], 1370 "summary": "Get all active subscriptions created against a specific device", 1371 "produces": [ 1372 "application/json" 1373 ], 1374 "responses": { 1375 "200": { 1376 "description": "An array of currently active subscriptions", 1377 "schema": { 1378 "type": "array", 1379 "items": { 1380 "$ref": "#/definitions/Subscription" 1381 } 1382 } 1383 }, 1384 "400": { 1385 "$ref": "#/responses/BadRequest" 1386 }, 1387 "401": { 1388 "$ref": "#/responses/Unauthorized" 1389 }, 1390 "403": { 1391 "$ref": "#/responses/Forbidden" 1392 }, 1393 "503": { 1394 "description": "#/responses/ServiceUnavailable" 1395 }, 1396 "504": { 1397 "description": "#/responses/GatewayTimeout" 1398 } 1399 }, 1400 "security": [ 1401 { 1402 "oauth2": [ 1403 "r:*" 1404 ] 1405 } 1406 ] 1407 }, 1408


"post": { 1409 "tags": [ 1410 "Events" 1411 ], 1412 "summary": "Subscribe to events against a specific device", 1413 "description": "Subscribe to device events by providing `eventTypes` you're interested in 1414 and `eventsUrl` API Endpoint where notifications will be sent to as defined. Successful response 1415 contains `subscriptionId` which identifies registered subscription and is part of each notification. 1416 First notification for each registered event type is received immediately after subscription and 1417 contains actual state of the resource, followed by new notifications in case of any 1418 change.\n\n**Supported events**\n- `resources_published`\n- `resources_unpublished`\n", 1419 "parameters": [ 1420 { 1421 "$ref": "#/parameters/ContentType" 1422 }, 1423 { 1424 "$ref": "#/parameters/SubscribeRequest" 1425 } 1426 ], 1427 "consumes": [ 1428 "application/json" 1429 ], 1430 "produces": [ 1431 "application/json" 1432 ], 1433 "responses": { 1434 "201": { 1435 "$ref": "#/definitions/SubscribeResponse" 1436 }, 1437 "400": { 1438 "$ref": "#/responses/BadRequest" 1439 }, 1440 "401": { 1441 "$ref": "#/responses/Unauthorized" 1442 }, 1443 "403": { 1444 "$ref": "#/responses/Forbidden" 1445 }, 1446 "404": { 1447 "$ref": "#/responses/NotFound" 1448 } 1449 }, 1450 "security": [ 1451 { 1452 "oauth2": [ 1453 "r:*" 1454 ] 1455 } 1456 ] 1457 } 1458 }, 1459 "/api/v1/devices/{deviceId}/subscriptions/{subscriptionId}": { 1460 "parameters": [ 1461 { 1462 "$ref": "#/parameters/CorrelationId" 1463 }, 1464 { 1465 "$ref": "#/parameters/DeviceId" 1466 }, 1467 { 1468 "$ref": "#/parameters/SubscriptionIdPath" 1469 } 1470 ], 1471 "delete": { 1472 "tags": [ 1473 "Events" 1474 ], 1475 "summary": "Unsubscribe from events against a specific device", 1476 "description": "Cancel subscription identified by the id returned in a response for 1477 subscription.\n", 1478 "responses": { 1479


"202": { 1480 "description": "Subscription was marked for cancellation" 1481 }, 1482 "400": { 1483 "$ref": "#/responses/BadRequest" 1484 }, 1485 "401": { 1486 "$ref": "#/responses/Unauthorized" 1487 }, 1488 "403": { 1489 "$ref": "#/responses/Forbidden" 1490 }, 1491 "404": { 1492 "$ref": "#/responses/NotFound" 1493 } 1494 }, 1495 "security": [ 1496 { 1497 "oauth2": [ 1498 "r:*" 1499 ] 1500 } 1501 ] 1502 } 1503 }, 1504 "/api/v1/devices/{deviceId}/{resourceLinkHref}": { 1505 "parameters": [ 1506 { 1507 "$ref": "#/parameters/CorrelationId" 1508 }, 1509 { 1510 "$ref": "#/parameters/DeviceId" 1511 }, 1512 { 1513 "$ref": "#/parameters/ResourceLinkHref" 1514 }, 1515 { 1516 "$ref": "#/parameters/Accept" 1517 } 1518 ], 1519 "get": { 1520 "tags": [ 1521 "Resources" 1522 ], 1523 "summary": "Retrieve resource values", 1524 "consumes": [ 1525 "application/json", 1526 "application/vnd.ocf+cbor" 1527 ], 1528 "produces": [ 1529 "application/json", 1530 "application/vnd.ocf+cbor" 1531 ], 1532 "responses": { 1533 "200": { 1534 "$ref": "#/definitions/ResourceRetrieveResponse" 1535 }, 1536 "400": { 1537 "$ref": "#/responses/BadRequest" 1538 }, 1539 "401": { 1540 "$ref": "#/responses/Unauthorized" 1541 }, 1542 "403": { 1543 "$ref": "#/responses/Forbidden" 1544 }, 1545 "404": { 1546 "$ref": "#/responses/NotFound" 1547 }, 1548 "503": { 1549 "description": "#/responses/ServiceUnavailable" 1550


}, 1551 "504": { 1552 "description": "#/responses/GatewayTimeout" 1553 } 1554 }, 1555 "security": [ 1556 { 1557 "oauth2": [ 1558 "r:*" 1559 ] 1560 } 1561 ] 1562 }, 1563 "post": { 1564 "tags": [ 1565 "Resources" 1566 ], 1567 "summary": "Update resource values", 1568 "parameters": [ 1569 { 1570 "$ref": "#/parameters/ResourceUpdateRequest" 1571 }, 1572 { 1573 "$ref": "#/parameters/ContentType" 1574 } 1575 ], 1576 "consumes": [ 1577 "application/json", 1578 "application/vnd.ocf+cbor" 1579 ], 1580 "produces": [ 1581 "application/json", 1582 "application/vnd.ocf+cbor" 1583 ], 1584 "responses": { 1585 "200": { 1586 "$ref": "#/definitions/ResourceRetrieveResponse" 1587 }, 1588 "400": { 1589 "$ref": "#/responses/BadRequest" 1590 }, 1591 "401": { 1592 "$ref": "#/responses/Unauthorized" 1593 }, 1594 "403": { 1595 "$ref": "#/responses/Forbidden" 1596 }, 1597 "404": { 1598 "$ref": "#/responses/NotFound" 1599 }, 1600 "415": { 1601 "description": "Unsupported media type specified in the Content-Type header" 1602 }, 1603 "503": { 1604 "description": "#/responses/ServiceUnavailable" 1605 }, 1606 "504": { 1607 "description": "#/responses/GatewayTimeout" 1608 } 1609 }, 1610 "security": [ 1611 { 1612 "oauth2": [ 1613 "r:*", 1614 "w:*" 1615 ] 1616 } 1617 ] 1618 } 1619 }, 1620 "/api/v1/devices/{deviceId}/{resourceLinkHref}/subscriptions": { 1621


"parameters": [ 1622 { 1623 "$ref": "#/parameters/CorrelationId" 1624 }, 1625 { 1626 "$ref": "#/parameters/DeviceId" 1627 }, 1628 { 1629 "$ref": "#/parameters/ResourceLinkHref" 1630 }, 1631 { 1632 "$ref": "#/parameters/Accept" 1633 } 1634 ], 1635 "get": { 1636 "tags": [ 1637 "Events" 1638 ], 1639 "summary": "Get all active subscriptions created against a specific resource", 1640 "produces": [ 1641 "application/json" 1642 ], 1643 "responses": { 1644 "200": { 1645 "description": "An array of currently active subscriptions", 1646 "schema": { 1647 "type": "array", 1648 "items": { 1649 "$ref": "#/definitions/Subscription" 1650 } 1651 } 1652 }, 1653 "400": { 1654 "$ref": "#/responses/BadRequest" 1655 }, 1656 "401": { 1657 "$ref": "#/responses/Unauthorized" 1658 }, 1659 "403": { 1660 "$ref": "#/responses/Forbidden" 1661 }, 1662 "503": { 1663 "description": "#/responses/ServiceUnavailable" 1664 }, 1665 "504": { 1666 "description": "#/responses/GatewayTimeout" 1667 } 1668 }, 1669 "security": [ 1670 { 1671 "oauth2": [ 1672 "r:*" 1673 ] 1674 } 1675 ] 1676 }, 1677 "post": { 1678 "tags": [ 1679 "Events" 1680 ], 1681 "summary": "Subscribe to events against a specific resource", 1682 "description": "Subscribe to resource events by providing `eventTypes` you're interested in 1683 and `eventsUrl` endpoint where events will be sent to as defined. Successful response contains 1684 `subscriptionId` which identifies registered subscription and is part of each event. First event for 1685 each registered event type is received immediately after subscription and contains actual state of 1686 the resource, followed by new events in case of any change.\n \n**Supported events**\n- 1687 `resource_contentchanged`", 1688 "parameters": [ 1689 { 1690 "$ref": "#/parameters/ContentType" 1691 }, 1692


{ 1693 "$ref": "#/parameters/SubscribeRequest" 1694 } 1695 ], 1696 "consumes": [ 1697 "application/json" 1698 ], 1699 "produces": [ 1700 "application/json" 1701 ], 1702 "responses": { 1703 "201": { 1704 "$ref": "#/definitions/SubscribeResponse" 1705 }, 1706 "400": { 1707 "$ref": "#/responses/BadRequest" 1708 }, 1709 "401": { 1710 "$ref": "#/responses/Unauthorized" 1711 }, 1712 "403": { 1713 "$ref": "#/responses/Forbidden" 1714 }, 1715 "404": { 1716 "$ref": "#/responses/NotFound" 1717 } 1718 }, 1719 "security": [ 1720 { 1721 "oauth2": [ 1722 "r:*" 1723 ] 1724 } 1725 ] 1726 } 1727 }, 1728 "/api/v1/devices/{deviceId}/{resourceLinkHref}/subscriptions/{subscriptionId}": { 1729 "parameters": [ 1730 { 1731 "$ref": "#/parameters/CorrelationId" 1732 }, 1733 { 1734 "$ref": "#/parameters/DeviceId" 1735 }, 1736 { 1737 "$ref": "#/parameters/ResourceLinkHref" 1738 }, 1739 { 1740 "$ref": "#/parameters/SubscriptionIdPath" 1741 } 1742 ], 1743 "delete": { 1744 "tags": [ 1745 "Events" 1746 ], 1747 "summary": "Unsubscribe from events against a specific resource", 1748 "description": "Cancel subscription identified by the id returned in a response for 1749 subscription.\n", 1750 "responses": { 1751 "202": { 1752 "description": "Subscription was marked for cancellation" 1753 }, 1754 "400": { 1755 "$ref": "#/responses/BadRequest" 1756 }, 1757 "401": { 1758 "$ref": "#/responses/Unauthorized" 1759 }, 1760 "403": { 1761 "$ref": "#/responses/Forbidden" 1762 }, 1763


"404": { 1764 "$ref": "#/responses/NotFound" 1765 } 1766 }, 1767 "security": [ 1768 { 1769 "oauth2": [ 1770 "r:*" 1771 ] 1772 } 1773 ] 1774 } 1775 }, 1776 "/{eventsUrl}": { 1777 "post": { 1778 "tags": [ 1779 "Events" 1780 ], 1781 "summary": "Events endpoint provided by the subscriber, where events are delivered", 1782 "description": "Events endpoint provided during subscription where events specified in the 1783 subscription will be sent to as defined per event type. Confirmation of each event sent to the 1784 `eventsUrl` endpoint is required with `2xx` success code. Events you will receive based on event 1785 type you're subscribed to are:\n - `subscription_cancelled`: `SubscriptionCancelledEvent`\n - 1786 `devices_registered`: `DevicesRegisteredEvent`\n - `devices_unregistered`: 1787 `DevicesUnregisteredEvent`\n - `resources_published`: `ResourcesPublishedEvent`\n - 1788 `resources_unpublished`: `ResourcesUnpublishedEvent`\n - `devices_online`: `DevicesOnlineEvent`\n - 1789 `devices_offline`: `DevicesOfflineEvent`\n - `resource_contentchanged`: 1790 `ResourceContentChangedEvent`", 1791 "parameters": [ 1792 { 1793 "$ref": "#/parameters/CorrelationId" 1794 }, 1795 { 1796 "$ref": "#/parameters/ContentType" 1797 }, 1798 { 1799 "$ref": "#/parameters/EventType" 1800 }, 1801 { 1802 "$ref": "#/parameters/SubscriptionId" 1803 }, 1804 { 1805 "$ref": "#/parameters/SequenceNumber" 1806 }, 1807 { 1808 "$ref": "#/parameters/EventSignature" 1809 }, 1810 { 1811 "$ref": "#/parameters/EventTimestamp" 1812 }, 1813 { 1814 "$ref": "#/parameters/EventsUrl" 1815 }, 1816 { 1817 "$ref": "#/parameters/Event" 1818 } 1819 ], 1820 "consumes": [ 1821 "application/json", 1822 "application/vnd.ocf+cbor" 1823 ], 1824 "responses": { 1825 "200": { 1826 "description": "Event successfully recieved" 1827 }, 1828 "400": { 1829 "$ref": "#/responses/BadRequest" 1830 }, 1831 "410": { 1832 "description": "The subscription identified by the Subscription-ID header is no more in 1833 demand and shall be cancelled" 1834


} 1835 } 1836 } 1837 } 1838 }, 1839 "securityDefinitions": { 1840 "oauth2": { 1841 "type": "oauth2", 1842 "flow": "accessCode", 1843 "authorizationUrl": "https://example.com/api/oauth/dialog", 1844 "tokenUrl": "https://example.com/api/oauth/token", 1845 "scopes": { 1846 "r:*": "Read device data", 1847 "w:*": "Update content of published resource" 1848 } 1849 } 1850 }, 1851 "parameters": { 1852 "CorrelationId": { 1853 "name": "Correlation-ID", 1854 "in": "header", 1855 "type": "string", 1856 "format": "uuid", 1857 "description": "A Correlation ID, also known as a Transit ID, is a unique identifier value 1858 that is attached to requests and messages that allow reference to a particular transaction or event 1859 chain.\n" 1860 }, 1861 "ContentType": { 1862 "name": "Content-Type", 1863 "in": "header", 1864 "type": "string", 1865 "enum": [ 1866 "application/json", 1867 "application/vnd.ocf+cbor" 1868 ], 1869 "required": true, 1870 "description": "The Content-Type header is used to indicate the media type of the resource. In 1871 responses, a Content-Type header tells the client what the content type of the returned content 1872 actually is. In requests, (such as POST), the client tells the server what type of data is actually 1873 sent.\n" 1874 }, 1875 "Accept": { 1876 "name": "Accept", 1877 "in": "header", 1878 "type": "string", 1879 "enum": [ 1880 "application/json", 1881 "application/vnd.ocf+cbor" 1882 ], 1883 "description": "The Accept request header can be used to specify certain media types which are 1884 acceptable for the response. Accept headers can be used to indicate that the request is specifically 1885 limited to a small set of desired types.\n" 1886 }, 1887 "SubscriptionId": { 1888 "name": "Subscription-ID", 1889 "in": "header", 1890 "description": "Unique id of the subscription", 1891 "type": "string", 1892 "format": "uuid", 1893 "required": true 1894 }, 1895 "SequenceNumber": { 1896 "name": "Sequence-Number", 1897 "in": "header", 1898 "description": "Sequence number of the event; first event starting with number 0", 1899 "type": "string", 1900 "required": true 1901 }, 1902 "EventSignature": { 1903 "name": "Event-Signature", 1904 "in": "header", 1905


"description": "The signature created by combining the `signingSecret` from the subscription 1906 request, headers and the body of the request using a stanard HMAC-SHA256 keyed hash.", 1907 "type": "string", 1908 "required": true 1909 }, 1910 "EventTimestamp": { 1911 "name": "Event-Timestamp", 1912 "in": "header", 1913 "description": "Time when the event occurred in standard Unix time format", 1914 "type": "string", 1915 "required": true 1916 }, 1917 "EventType": { 1918 "name": "Event-Type", 1919 "in": "header", 1920 "type": "string", 1921 "enum": [ 1922 "subscription_cancelled", 1923 "devices_registered", 1924 "devices_unregistered", 1925 "resource_contentchanged", 1926 "resources_published", 1927 "resources_unpublished", 1928 "devices_online", 1929 "devices_offline" 1930 ], 1931 "required": true 1932 }, 1933 "DeviceType": { 1934 "description": "Filter devices by device type", 1935 "name": "rt", 1936 "in": "query", 1937 "type": "array", 1938 "items": { 1939 "type": "string" 1940 } 1941 }, 1942 "ResourceLinkHref": { 1943 "description": "Path to resource", 1944 "name": "resourceLinkHref", 1945 "in": "path", 1946 "type": "string", 1947 "required": true 1948 }, 1949 "DeviceId": { 1950 "description": "Id of the device", 1951 "name": "deviceId", 1952 "in": "path", 1953 "type": "string", 1954 "format": "uuid", 1955 "required": true 1956 }, 1957 "SubscriptionIdPath": { 1958 "name": "subscriptionId", 1959 "in": "path", 1960 "type": "string", 1961 "format": "uuid", 1962 "required": true 1963 }, 1964 "BatchFormat": { 1965 "name": "content", 1966 "in": "query", 1967 "description": "Indicates to the recipient that the response payload shall be the resolved 1968 (i.e. resource representation) Link and not the Link itself. Default is `base`. When requesting 1969 `all`, additional scope `r:*` is required", 1970 "type": "string", 1971 "enum": [ 1972 "base", 1973 "all" 1974 ] 1975 }, 1976


"EventsUrl": { 1977 "name": "eventsUrl", 1978 "type": "string", 1979 "in": "path", 1980 "required": true 1981 }, 1982 "ResourceUpdateRequest": { 1983 "description": "Map of resource values encoded to application/vnd.ocf+cbor type", 1984 "name": "content", 1985 "in": "body", 1986 "schema": { 1987 "$ref": "#/definitions/ResourceUpdateRequest" 1988 }, 1989 "required": true 1990 }, 1991 "SubscribeRequest": { 1992 "name": "content", 1993 "in": "body", 1994 "schema": { 1995 "$ref": "#/definitions/SubscribeRequest" 1996 }, 1997 "required": true 1998 }, 1999 "Event": { 2000 "description": "Event of a specific type, based on what you are subscribed to", 2001 "name": "content", 2002 "in": "body", 2003 "schema": { 2004 "$ref": "#/definitions/ResourceContentChangedEvent" 2005 }, 2006 "required": true 2007 } 2008 }, 2009 "responses": { 2010 "Unauthorized": { 2011 "description": "Unauthorized" 2012 }, 2013 "NotFound": { 2014 "description": "Not found" 2015 }, 2016 "SubscriptionCancellationPending": { 2017 "description": "Subscription was marked for cancellation" 2018 }, 2019 "Forbidden": { 2020 "description": "Insufficient permissions" 2021 }, 2022 "BadRequest": { 2023 "description": "The request was malformed or badly constructed" 2024 }, 2025 "ServiceUnavailable": { 2026 "description": "The service on the Target Cloud is unavailable for the reason indicated in the 2027 diagnostic payload" 2028 }, 2029 "GatewayTimeout": { 2030 "description": "The target Device is registered at the target Cloud, however the Device itself 2031 is unavailable, offline, or otherwise unreachable. The response should include a Retry-After header 2032 containing the time after which the request may be re-attempted. Additional information is indicated 2033 in the diagnostic payload." 2034 } 2035 }, 2036 "definitions": { 2037 "DeviceProperties": { 2038 "properties": { 2039 "rt": { 2040 "description": "Resource Type of the Resource", 2041 "items": { 2042 "type": "string", 2043 "maxLength": 64 2044 }, 2045 "minItems": 1, 2046 "readOnly": true, 2047


"uniqueItems": true, 2048 "type": "array" 2049 }, 2050 "di": { 2051 "allOf": [ 2052 { 2053 "$ref" : "http://openconnectivityfoundation.github.io/core/schemas/oic.types-2054 schema.json#/definitions/uuid" 2055 }, 2056 { 2057 "description": "Unique identifier for the Device", 2058 "readOnly": true 2059 } 2060 ] 2061 }, 2062 "dmn": { 2063 "description": "Manufacturer Name.", 2064 "items": { 2065 "properties": { 2066 "language": { 2067 "allOf": [ 2068 { 2069 "$ref" : "http://openconnectivityfoundation.github.io/core/schemas/oic.types-2070 schema.json#/definitions/language-tag" 2071 }, 2072 { 2073 "description": "An RFC 5646 language tag.", 2074 "readOnly": true 2075 } 2076 ] 2077 }, 2078 "value": { 2079 "description": "Manufacturer name in the indicated language.", 2080 "maxLength": 64, 2081 "readOnly": true, 2082 "type": "string" 2083 } 2084 }, 2085 "type": "object" 2086 }, 2087 "minItems": 1, 2088 "readOnly": true, 2089 "type": "array" 2090 }, 2091 "n": { 2092 "$ref" : 2093 "https://openconnectivityfoundation.github.io/core/schemas/oic.common.properties.core-2094 schema.json#/definitions/n" 2095 } 2096 }, 2097 "type": "object" 2098 }, 2099 "Device": { 2100 "type": "object", 2101 "properties": { 2102 "device": { 2103 "$ref":"#/definitions/DeviceProperties" 2104 }, 2105 "status": { 2106 "$ref": "#/definitions/DeviceStatus" 2107 }, 2108 "links": { 2109 "type": "array", 2110 "items": { 2111 "$ref": 2112 "http://openconnectivityfoundation.github.io/core/swagger2.0/oic.wk.res.swagger.json#/definitions/oi2113 c.oic-link" 2114 } 2115 } 2116 }, 2117 "example": { 2118


"device": { 2119 "rt": ["oic.wk.d","oic.d.sensor"], 2120 "dmn": "Open Connectivity Foundation", 2121 "n": "Food safety sensor", 2122 "di": "53080a4f-5e3e-4291-802f-3436238232d2" 2123 }, 2124 "status": "online", 2125 "links": [ 2126 { 2127 "href": "/53080a4f-5e3e-4291-802f-3436238232d2/oic/d", 2128 "rt": [ 2129 "oic.wk.d", 2130 "oic.d.sensor" 2131 ], 2132 "if": [ 2133 "oic.if.r", 2134 "oic.if.baseline" 2135 ] 2136 }, 2137 { 2138 "href": "/53080a4f-5e3e-4291-802f-3436238232d2/oic/p", 2139 "rt": [ 2140 "oic.wk.p" 2141 ], 2142 "if": [ 2143 "oic.if.r", 2144 "oic.if.baseline" 2145 ] 2146 }, 2147 { 2148 "href": "/53080a4f-5e3e-4291-802f-3436238232d2/humidity", 2149 "rt": [ 2150 "oic.r.humidity" 2151 ], 2152 "if": [ 2153 "oic.if.s", 2154 "oic.if.baseline" 2155 ] 2156 }, 2157 { 2158 "href": "/53080a4f-5e3e-4291-802f-3436238232d2/temperature", 2159 "rt": [ 2160 "oic.r.temperature" 2161 ], 2162 "if": [ 2163 "oic.if.s", 2164 "oic.if.baseline" 2165 ] 2166 } 2167 ] 2168 } 2169 }, 2170 "DeviceContentAll": { 2171 "type": "object", 2172 "properties": { 2173 "device": { 2174 "$ref":"#/definitions/DeviceProperties" 2175 }, 2176 "status": { 2177 "$ref": "#/definitions/DeviceStatus" 2178 }, 2179 "links": { 2180 "type": "array", 2181 "items": { 2182 "type": "object", 2183 "properties": { 2184 "href": { 2185 "type": "string" 2186 }, 2187 "rep": { 2188 "type": "object" 2189


} 2190 } 2191 } 2192 } 2193 }, 2194 "example": { 2195 "device": { 2196 "rt": ["oic.wk.d","oic.d.sensor"], 2197 "dmn": "Open Connectivity Foundation", 2198 "n": "Food safety sensor", 2199 "di": "53080a4f-5e3e-4291-802f-3436238232d2" 2200 }, 2201 "status": "online", 2202 "links": [ 2203 { 2204 "href": "/53080a4f-5e3e-4291-802f-3436238232d2/oic/d", 2205 "rep": { 2206 "rt": ["oic.wk.d","oic.d.sensor"], 2207 "dmn": "Open Connectivity Foundation", 2208 "n": "Food safety sensor", 2209 "di": "53080a4f-5e3e-4291-802f-3436238232d2", 2210 "icv": "ocf.2.0.5", 2211 "dmv": "ocf.res.1.3.0, ocf.sh.1.3.0", 2212 "piid": "6F0AAC04-2BB0-468D-B57C-16570A26AE48" 2213 } 2214 }, 2215 { 2216 "href": "/53080a4f-5e3e-4291-802f-3436238232d2/oic/p", 2217 "rep": { 2218 "pi": "54919CA5-4101-4AE4-595B-353C51AA983C", 2219 "mnfv": "1.1.20" 2220 } 2221 }, 2222 { 2223 "href": "/53080a4f-5e3e-4291-802f-3436238232d2/humidity", 2224 "rep": { 2225 "humidity": 62, 2226 "desiredHumidity": 65 2227 } 2228 }, 2229 { 2230 "href": "/53080a4f-5e3e-4291-802f-3436238232d2/temperature", 2231 "rep": { 2232 "temperature": 21, 2233 "units": "C" 2234 } 2235 } 2236 ] 2237 } 2238 }, 2239 "DeviceStatus": { 2240 "description": "Device status available from the OCF Cloud, which tracks if the device has 2241 opened TCP connection and is signed in", 2242 "type": "string", 2243 "enum": [ 2244 "online", 2245 "offline" 2246 ] 2247 }, 2248 "ResourceUpdateRequest": { 2249 "type": "string", 2250 "description": "Desired content of the resource", 2251 "example": "o29kZXNpcmVkSHVtaWRpdHkYPGV0eXBlc4Fub2ljLnIuaHVtaWRpdHloaHVtaWRpdHkYKA==" 2252 }, 2253 "ResourceRetrieveResponse": { 2254 "type": "string", 2255 "description": "Content of the resource returned from the device", 2256 "example": "o29kZXNpcmVkSHVtaWRpdHkYPGV0eXBlc4Fub2ljLnIuaHVtaWRpdHloaHVtaWRpdHkYKA==" 2257 }, 2258 "EventType": { 2259 "type": "string", 2260


"enum": [ 2261 "subscription_cancelled", 2262 "devices_registered", 2263 "devices_unregistered", 2264 "resource_contentchanged", 2265 "resources_published", 2266 "resources_unpublished", 2267 "devices_online", 2268 "devices_offline" 2269 ] 2270 }, 2271 "SubscriptionId": { 2272 "description": "Unique id of the subscription", 2273 "type": "string", 2274 "format": "uuid" 2275 }, 2276 "SubscribeRequest": { 2277 "type": "object", 2278 "properties": { 2279 "eventsUrl": { 2280 "$ref": "#/definitions/EventsUrl" 2281 }, 2282 "eventTypes": { 2283 "type": "array", 2284 "items": { 2285 "$ref": "#/definitions/EventType" 2286 } 2287 }, 2288 "signingSecret": { 2289 "type": "string", 2290 "maxLength": 32, 2291 "minLength": 32 2292 } 2293 }, 2294 "required": [ 2295 "eventsUrl", 2296 "eventTypes", 2297 "signingSecret" 2298 ], 2299 "example": { 2300 "eventsUrl": "https://events.example.com/", 2301 "eventTypes": [ 2302 "devices_registered", 2303 "devices_unregistered" 2304 ], 2305 "signingSecret": "3BZ6oI9xbRJzOUvUoRb5RgaZjPqHrmql" 2306 } 2307 }, 2308 "SubscribeResponse": { 2309 "description": "Subscription was registered, waiting for verification", 2310 "type": "object", 2311 "properties": { 2312 "subscriptionId": { 2313 "$ref": "#/definitions/SubscriptionId" 2314 } 2315 }, 2316 "required": [ 2317 "subscriptionId" 2318 ], 2319 "example": { 2320 "subscriptionId": "1eeb465c-5e8d-4305-a366-bbf035fff671" 2321 } 2322 }, 2323 "Subscription": { 2324 "type": "object", 2325 "properties": { 2326 "id": { 2327 "$ref": "#/definitions/SubscriptionId" 2328 } 2329 }, 2330 "required": [ 2331


"id" 2332 ], 2333 "example": { 2334 "id": "1eeb465c-5e8d-4305-a366-bbf035fff671" 2335 } 2336 }, 2337 "EventsUrl": { 2338 "type": "string", 2339 "format": "url", 2340 "example": "https://events.example.com/" 2341 }, 2342 "SubscriptionCancelledEvent": { 2343 "type": "object", 2344 "description": "Subscription with provided id was cancelled" 2345 }, 2346 "DevicesRegisteredEvent": { 2347 "description": "Device was successfully signed up to the OCF Cloud, as defined in the 2348 `oic.sec.account`", 2349 "type": "object", 2350 "properties": { 2351 "content": { 2352 "type": "array", 2353 "items": { 2354 "properties": { 2355 "di": { 2356 "type": "string", 2357 "format": "uuid" 2358 } 2359 } 2360 } 2361 } 2362 } 2363 }, 2364 "DevicesUnregisteredEvent": { 2365 "description": "Device was successfully signed off from the OCF Cloud, as defined in the 2366 `oic.sec.account`", 2367 "type": "object", 2368 "properties": { 2369 "content": { 2370 "type": "array", 2371 "items": { 2372 "properties": { 2373 "di": { 2374 "type": "string", 2375 "format": "uuid" 2376 } 2377 } 2378 } 2379 } 2380 } 2381 }, 2382 "ResourcesPublishedEvent": { 2383 "type": "object", 2384 "properties": { 2385 "content": { 2386 "type": "array", 2387 "items": { 2388 "$ref": 2389 "http://openconnectivityfoundation.github.io/core/swagger2.0/oic.wk.res.swagger.json#/definitions/oi2390 c.oic-link" 2391 } 2392 } 2393 } 2394 }, 2395 "ResourcesUnpublishedEvent": { 2396 "type": "object", 2397 "properties": { 2398 "content": { 2399 "type": "array", 2400 "items": { 2401 "$ref": 2402


"http://openconnectivityfoundation.github.io/core/swagger2.0/oic.wk.res.swagger.json#/definitions/oi2403 c.oic-link" 2404 } 2405 } 2406 } 2407 }, 2408 "DevicesOnlineEvent": { 2409 "type": "object", 2410 "properties": { 2411 "content": { 2412 "type": "array", 2413 "items": { 2414 "properties": { 2415 "di": { 2416 "type": "string", 2417 "format": "uuid" 2418 } 2419 } 2420 } 2421 } 2422 } 2423 }, 2424 "DevicesOfflineEvent": { 2425 "type": "object", 2426 "properties": { 2427 "content": { 2428 "type": "array", 2429 "items": { 2430 "properties": { 2431 "di": { 2432 "type": "string", 2433 "format": "uuid" 2434 } 2435 } 2436 } 2437 } 2438 } 2439 }, 2440 "ResourceContentChangedEvent": { 2441 "type": "string", 2442 "description": "New Content of the resource returned from the device", 2443 "example": "o29kZXNpcmVkSHVtaWRpdHkYPGV0eXBlc4Fub2ljLnIuaHVtaWRpdHloaHVtaWRpdHkYKA==" 2444 } 2445 } 2446 } 2447 2448

2449

OCF Cloud Open API · Figures 135 136 Figure 1 – OCF Cloud Overview ..... 4 137 Figure 2 –...

Documents

Transcript of OCF Cloud Open API · Figures 135 136 Figure 1 – OCF Cloud Overview ..... 4 137 Figure 2 –...