-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathindex.html
2081 lines (1877 loc) · 85.5 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html>
<head>
<title>Web Thing Model</title>
<meta charset='utf-8'>
<script src='https://www.w3.org/Tools/respec/respec-w3c-common'
async class='remove'></script>
<script class='remove'>
var respecConfig = {
specStatus: 'Member-SUBM',
shortName: 'wot-model',
overrideCopyright: 'Copyright © 2015 EVRYTHNG. This document is available under the <a href="http://www.w3.org/Consortium/Legal/copyright-documents">W3C Document License</a>. See the <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">W3C Intellectual Rights Notice and Legal Disclaimers</a> for additional information.',
editors: [
{
name: 'Vlad Trifa',
company: 'EVRYTHNG',
companyURL: 'http://evrythng.com/'
},
{
name: 'Dominique Guinard',
company: 'EVRYTHNG',
companyURL: 'http://evrythng.com/'
},
{
name: 'David Carrera',
company: 'Barcelona Supercomputing Center',
companyURL: 'http://bsc.es/'
}
],
logos: [
{
src: 'http://www.w3.org/Icons/w3c_home',
url: 'http://www.w3.org',
alt: 'W3C',
width: 72,
height: 48
},
{
src: 'http://www.w3.org/Icons/member_subm',
url: 'http://www.w3.org/Submission/',
alt: 'W3C Member Submission',
width: 211,
height: 48
}
],
localBiblio: {
'REST': {
title: 'Architectural Styles and the Design of Network-based Software Architectures',
href: 'http://roy.gbiv.com/pubs/dissertation/top.htm',
authors: [
'Roy Thomas Fielding'
],
status: 'Doctoral Dissertation',
date: 'September 2000'
},
'QUTD': {
title: 'QUDT - Quantities, Units, Dimensions and Data Types Ontologies',
href: 'http://www.qudt.org/',
authors: [
'Ralph Hodgson',
'Paul J. Keller',
'Jack Hodges',
'Jack Spivak'
],
date: 'March 18, 2014'
},
'SI': {
title: 'International System of Units (SI)',
href: 'http://physics.nist.gov/cuu/Units/units.html'
},
'WoTBook': {
title: 'Building the Web of Things',
href: 'http://book.webofthings.io',
authors: [
'Dominique Guinard',
'Vlad Trifa'
],
date: 'May 2015'
},
'WoTPaper': {
title: 'Towards the Web of Things: Web Mashups for Embedded Devices',
href: 'http://www.vs.inf.ethz.ch/publ/bibtex.html?file=papers/dguinard_09_WOTMashups',
authors: [
'Dominique Guinard',
'Vlad Trifa'
],
status: 'WWW 2009 Conference Paper',
date: 'April 20, 2009'
}
}
};
</script>
<style type="text/css">
table {
border: 1px solid grey;
}
</style>
</head>
<body>
<section id='abstract'>
<p>
This document proposes the basis of a common model to describe the virtual counterpart of physical objects in
the Web of Things.
It defines a model and Web API for Things to be followed by anyone wanting to create a product, device, service,
or application for the Web of Things. This document considers the definition of the Web of Things (WoT) proposed
in [[WoTPaper]] and [[WoTBook]], i.e., the Application layer of the Internet of Things. The model and
protocols proposed here aim at making the interaction between Things in the Internet of Things accessible
through Web standards to facilitate the implementation of Web applications making use or retrieving data from
real-world objects.
</p>
</section>
<section id='sotd'>
<p>
This document is based on work undertaken within the
<a href="http://www.compose-project.eu/">COMPOSE</a> European project and submitted to W3C as a possible starting point for a future Working Group chartered to work on the Web of Things.
</p>
</section>
<section class='informative'>
<h2>Introduction</h2>
<p>
The following guidelines and recommendations aim at ensuring interoperability across all entities on the Web of
Things. Unlike other custom (non-Web) protocols used for machine-to-machine communications that create a
“parallel universe” to the existing Web; the Web of Things as described here is designed to be seamlessly
integrated to the existing Web so it can fully leverage its infrastructure and standards to minimize
integrations across applications and systems.
</p>
<p>
The proposal is composed of three sub-parts:
</p>
<ul>
<li>
<strong>Integration Patterns</strong>. This section discusses the way Things are integrated to the Web. It
proposes 3 different patterns, Direct Connectivity, Gateway Based Connectivity, Cloud Based Connectivity.
</li>
<li>
<strong>Web Things (WT) Requirements</strong>. This part does not introduce any specific data naming
conventions of domain-specific models. It is solely composed of multiple constraints and recommendations on
how the protocol should be implemented so that any entity on the Web of Things can easily interact with each
other. Respecting these requirements turns a Web server into a Web Thing.
</li>
<li>
<strong>Web Things Model</strong>. Once a Web Thing follows the conventions defined above, it is then
capable to read and exchange data with any other entities of the Web of Things. However, it does not mean it
can “understand” what the object is, what data or services it offers, etc. Therefore, the second component
of this specification proposes RESTful Web protocol with a set of resources, data models and payload syntax that Web Thing and applications should follow. Respecting these requirements turns a Web
Thing into an Extended Web Thing. Implementing semantic extensions (e.g., via [[JSON-LD]] and <a href="http://schema.org">schema.org</a>) turns the Extended Web Thing into a Semantic Web Thing.
</li>
</ul>
<figure id="wot-levels">
<img src="wot-levels.png"
alt="Web Thing Model levels build on top of each other, from a Web Thing that implement the requirements to the Extended Web Thing and Semantic Web Thing"
width="800"/>
<figcaption>Web Thing Model levels</figcaption>
</figure>
<p class="note">
Semantic extensions are not covered by this specification. The data model defined in this specification may benefit from alignment with the vocabulary used in <a href="http://schema.org">schema.org</a>. It should also be easy to link the type of a value (see <a href="#values"></a>) to an ontology, for instance to units defined in the [[QUTD]] ontology.
</p>
</section>
<section id='conformance'>
<p>
This specification has two classes of products:
</p>
<dl>
<dt><dfn data-lt="Web Things|Thing|Things">Web Thing</dfn></dt>
<dd>
A Web Thing (or simply Thing) is a digital representation of a physical object accessible via a RESTful Web API. Examples of
Web Things are: an Arduino board, a garage door, a bottle of soda, a building, a TV, etc. The API of the Web
Thing can be hosted on the Thing itself or on an intermediate host in the network such as a Gateway or a
Cloud service (for Things that aren't accessible through the Internet).
<p>A <a>Web Thing</a> conforms to this specification if it follows the statements defined in <a href="#web-things-requirements"></a>.</p>
</dd>
<dt><dfn data-lt="Extended Web Things">Extended Web Thing</dfn></dt>
<dd>
An <a>Extended Web Thing</a> that also supports the REST API and data model defined in this specification,
thus enabling its automatic inclusion in more complex systems.
<p>An <a>Extended Web Thing</a> conforms to this specification if it follows the statements defined in <a
href="#web-things-requirements"></a> and <a href="#web-things-model"></a>.</p>
</dd>
</dl>
</section>
<section>
<h2>Terminology</h2>
<p>
The following terms are considered in this proposal:
</p>
<dl>
<dt><dfn data-lt="Clients">Client</dfn></dt>
<dd>A <a>Client</a> refers to any physical or digital entity that can interact with a Web Thing. This can be a
mobile application, a Web browser, a proxy, a desktop application, but also another Web Things (e.g., in the
case of Machine to Machine communication).
</dd>
<dt><dfn data-lt="Properties">Property</dfn>
<dt>
<dd>A <a>Property</a> is a variable of a Web Thing. Properties represent the internal state of a <a>Web Thing</a>. Clients can
subscribe to properties to receive a notification message when specific conditions are met (e.g. value of
one or more properties changed).
</dd>
<dt><dfn data-lt="Actions">Action</dfn></dt>
<dd>An <a>Action</a> is a function offered by a <a>Web Thing</a>. A Client invokes a function on a <a>Web Thing</a> which initiates a state transition by sending it an Action. Examples of Actions are “open” or “close” for a garage door; “enable” or
“disable” for a smoke alarm; “check-in” or “scan” for a bottle of soda or a place. The direction of an
<a>Action</a> is from the <a>Client</a> to the <a>Web Thing</a>.
</dd>
</dl>
</section>
<section>
<h2>Web Things integration patterns</h2>
<p>
This part looks into the different ways of integrating physical objects to the Web to make them <a>Web Things</a>. Once a pattern has been choosen, the server of a <a>Web Thing</a> should
follow the <a href="#web-things-requirements">Web Things Requirements</a> and the resources and payloads it uses
should follow the <a href="#web-things-model">Web Things Model</a>.
</p>
<p>
Some physical entities might not expose a Web API themselves for various reasons (e.g., a ZigBee sensor node, or
an heart rate monitor accessible over Bluetooth only), in which case they are not <a>Web
Things</a> as such, but they can use another <a>Web Thing</a> as a proxy or gateway to provide a Web API for
them, therefore turning them into Web Things.
</p>
<p>
While the three integration patterns described below need to be taken into account it is worth noting that the
requirements and model apply regardless of the integration pattern of choice.
</p>
<section>
<h2><dfn>Direct</dfn> connectivity</h2>
<p>
In the most straightforward case, a <a>Web Thing</a> is simply a Web API that <a>Clients</a>
send requests to. In some cases, the <a>Client</a> and the <a>Web Thing</a> can be on the same network or on
different networks. In both cases, you are sending the same request to a <a>Web Thing</a>, the only
difference is the URL to which you are sending the request (and obviously how the lamp gets the message).
</p>
<figure>
<img src="integration-direct.png"
alt="When a Web Thing exposes a Web API, Clients can directly connect to it, potential through a local address if they are both on the same network"
width="800"/>
<figcaption>Direct connectivity between a Client and a Web Thing (source: [[WoTBook]])</figcaption>
</figure>
</section>
<section>
<h2><dfn>Gateway</dfn> proxied connectivity</h2>
<p>
Gateway based connectivity is used when a Thing cannot offer a Web API directly. In this case an
intermediate, the gateway, exposes a Web API on its behalf, therefore acting as a proxy (or gateway
depending on the complexity/layer of the translation).
</p>
<figure>
<img src="integration-gateways.png"
alt="When a Web Thing cannot expose a Web API directly, Clients connect to it through a Gateway that exposes the Web API on their behalf"
width="800"/>
<figcaption>Gateway-based connectivity between a Client and a Web Thing (source: [[WoTBook]])</figcaption>
</figure>
</section>
<section>
<h2><dfn>Cloud</dfn> proxied connectivity</h2>
<p>
This third case is similar to <a href="#gateway-proxied-connectivity"></a>. However, in this case the gateway
is a cloud service and not another device in situ.
</p>
<figure>
<img src="integration-cloud.png"
alt="A cloud service may expose the Web API of a Web Thing for Clients to connect to it" width="800"/>
<figcaption>Cloud-based connectivity between a Client and a Web Thing (source: [[WoTBook]])</figcaption>
</figure>
</section>
</section>
<section>
<h2>Web Things requirements</h2>
<p>
This part defines a set of rules for implementing <a>Web Things</a>. It assumes that an <a
href="#web-things-integration-pattern">Integration Pattern</a> was chosen.
</p>
<section>
<h2>Level 0 – MUST</h2>
<p>
This section defines the Level 0 requirements – all of which MUST be in place in any <a>Web Thing</a>
implementation, as all <a>Clients</a> will expect these constraints.
</p>
<section>
<h2>R0.1 – A <a>Web Thing</a> MUST at least be an HTTP/1.1 server</h2>
<p>
All <a>Web Things</a> MUST support communication over HTTP/1.1 [[!RFC2616]]. When
possible, <a>Web Things</a> SHOULD also support HTTP/2 [[!RFC7540]].
</p>
<p class="note">
HTTP/1.1 is the most widely spread protocol over the Web and virtually any HTTP client or server
implementation supports it, therefore it is likely that the majority of clients might not support HTTP/2
as of yet. This can be implemented directly on the <a>Web Thing</a> or can be provided via a proxy (see
Integration Patterns).
</p>
<p class="note">
As a consequence, while <a>Clients</a> should not expect support for HTTP/2,
communication with a <a>Web Thing</a> using HTTP/1.1 is always possible.
</p>
</section>
<section>
<h2>R0.2 – A <a>Web Thing</a> MUST have a root resource accessible via an HTTP URL</h2>
<p>
A <a>Web Thing</a> MUST have a so-called “root resource” identified by a HTTP URL (uses the HTTP
protocol, therefore starts with <code>http://</code> or <code>https://</code>) that acts as the entry
point for the <a>Web Thing</a> and enables the interaction with it. This root resource makes the <a>Web
Thing</a> both uniquely identifiable and addressable over a network so that <a>Clients</a> can interact with it.
</p>
<p>
If the <a>Web Thing</a> is a device connected on a LAN (e.g. a printer, a lamp, etc.), the root URL of a
<a>Web Thing</a> SHOULD be its IP address and standard HTTP port, so that, knowing only the IP address
of a networked device that is a <a>Web Thing</a>, a <a>Client</a> can send an HTTP GET request on that
IP address over the default port (80 for HTTP, 443 for HTTPS) to retrieve a representation of the Web
Thing. This feature is envisioned to facilitate discovery of devices at the network level, without
requiring an additional protocol.
</p>
<p class="note">
A <a>Web Thing</a> does not need to be publicly accessible over the Internet, as some Web of Things
scenarios might only work within a local area network (LAN) as defined above. This means a root URL does
not need to be public and can be simply the local IP address of a device. The Root URL of a Web Thing is
referred to as {wt} throughout this document.
</p>
<pre class="example" title="Valid root URLs" highlight="true">
http://gateway.api.com/devices/TV
http://kitchen-raspberry.device-lab.co.uk
https://192.168.10.10:9002
https://kitchen:3000/fridge/root
</pre>
</section>
<section>
<h2>R0.3 – A <a>Web Thing</a> MUST support <code>GET</code>, <code>POST</code>, <code>PUT</code> and <code>DELETE</code>
HTTP verbs</h2>
<p>
The Web of Things aims to maximise interoperability by exposing the services of Things using REST
[[REST]]. For this idea to come to reality, supporting certain HTTP verbs of the specification is
required. Considering that the REST paradigm is based on resources and <abbr
title="Create, Read, Update and Delete">CRUD</abbr> operations on them, a <a>Web Thing</a> MUST
support <code>GET</code> for reading operations, <code>POST</code> for creation, <code>PUT</code> for
updates and state changes, and <code>DELETE</code> for removal.
</p>
</section>
<section>
<h2>R0.4 – A <a>Web Thing</a> MUST implement HTTP status codes <code>200</code>, <code>400</code>,
<code>500</code></h2>
<p>
Proper usage of HTTP/1.1 error codes is advisable. However, considering that some devices are
restricted, only the following subset is mandatory:
</p>
<ul>
<li><strong>2XX Success</strong>. Returned for any successful action. The <a>Web Thing</a> MUST at least
support the 200 OK response.
</li>
<li><strong>4XX Client Error</strong>. This should be returned for any error due to the client that sent
the request (from a wrong URL, to invalid authentication, or incorrect parameter). The <a>Web
Thing</a> MUST at least support the 400 Bad Request error code.
</li>
<li><strong>5XX Server Error</strong>. This should be used for any error on the <a>Web Thing</a> side
when a request was valid but cannot be processed at this time for any reason, e.g. the <a>Web
Thing</a> has a server error, etc. The <a>Web Thing</a> MUST at least support the 500 Internal
Server Error error code.
</li>
</ul>
</section>
<section>
<h2>R0.5 – A <a>Web Thing</a> MUST support JSON as default representation</h2>
<p>
A <a>Web Thing</a> MUST always accept a valid JSON document [[!RFC7159]] as payload for request and
always return a JSON representation when requested. If no <code>Accept:</code> HTTP header is specified
in the request (or if the format is unknown or not supported), the <a>Web Thing</a> SHOULD return an
appropriate error code, but it also MAY return JSON as default. Fields in JSON objects should follow the camelCase convention starting with a lowerCase letter (e.g., backColor) or a special character (e.g., _customRelation).
</p>
<p>
A <a>Web Thing</a> MAY support additional formats.
</p>
<p class="note">
A consequence of supporting JSON is that UTF-8 is the default encoding for payloads (see <a
href="https://tools.ietf.org/html/rfc7159#section-8.1">Character Encoding</a> in the JSON
specification [[!RFC7159]])
</p>
</section>
<section>
<h2>R0.6 – A <a>Web Thing</a> MUST support <code>GET</code> on its root URL</h2>
<p>
Because they all have a unique root URL and sometimes it is all we know about them, <a>Web Things</a> MUST respond to HTTP <code>GET</code> requests on their root URL
with their basic representation, so that <a>Clients</a> can use and understand it.
</p>
<p class="note">
The basic representation returned by an <a>Extended Web Thing</a> is defined in <a
href="#web-things-model"></a>
</p>
</section>
</section>
<section>
<h2>Level 1 – SHOULD</h2>
<p>
Unless there are technical or practical limitations for not adhering to Level 1 constraints, <a>Web Things</a> SHOULD support the following constraints.
</p>
<section>
<h2>R1.1 – A <a>Web Thing</a> SHOULD use secure HTTP connections (HTTPS)</h2>
<p>
Ideally, <a>Web Thing</a> SHOULD support secure connections with HTTP over TLS [[!RFC5246]]. The ideal
case for security is to support only HTTP over TLS. <a>Web Thing</a> that are exposed on the Internet
MUST always implement HTTP over TLS.
</p>
<p>
<a>Web Things</a> MAY use other security mechanisms if they want to (in addition or in
place of HTTPS). In some cases, it might be impossible or impractical to implement HTTPS over TLS (for
example in pure intranet scenario), in which case using another security mechanism is still highly
recommended.
</p>
</section>
<section>
<h2>R1.2 – A <a>Web Thing</a> SHOULD implement the WebSocket Protocol</h2>
<p>
Clients SHOULD be able to subscribe to notifications from <a>Web Thing</a> using a Publish/Subscribe
(Pub/Sub) pattern implemented using the WebSocket protocol [[!RFC6455]].
</p>
</section>
<section>
<h2>R1.3 – A <a>Web Thing</a> SHOULD support the Web Things model</h2>
<p>
If possible, every <a>Web Thing</a> SHOULD implement the <a href="#web-things-model">Web Things
Model</a>. It is not essential to use it for a device to be part of the Web of Things, but implementing
it will lead to higher degree of interoperability.
</p>
<p class="note">
An <a>Extended Web Thing</a> fulfills this requirement by definition. In other words, while this
specification acknowledges the usefulness of the <a>Web Thing</a> level to accommodate legacy devices
and very restricted scenarios, implementers are encouraged to implement <a>Extended
Web Things</a>.
</p>
</section>
<section>
<h2>R1.4 – A <a>Web Thing</a> SHOULD return a 204 for all write operations</h2>
<p>
By default, all PUT, POST, and DELETE requests to a Web Thing should not return the payload of the object that was created/modified, therefore should return a <code>204 NO CONTENT</code> response and no response body.
</p>
</section>
<section>
<h2>R1.5 – A <a>Web Thing</a> SHOULD provide a default human-readable documentation</h2>
<p>
To interact with a <a>Web Thing</a>, a Client needs to know what resources are available on the Web
Thing, what they refer to (what is the type/nature of the resources), and how to interact with them. The
format of the API documentation is left to implementers, but should describe the resources offered, the
verbs they support, the payloads accepted and returned, and possible status codes that can be returned
and when.
</p>
</section>
</section>
<section>
<h2>Level 2 – MAY</h2>
<p>
A <a>Web Thing</a> MAY support these rules, but are not expected to. It depends on the capabilities of the
devices and other implementation aspects.
</p>
<section>
<h2>R2.1 – A <a>Web Thing</a> MAY support the HTTP <code>OPTIONS</code> verb for each of its resources</h2>
<p>
Any resource of a Web Thing should implement the OPTIONS verb to describe what verbs are supported by
each resource.
</p>
</section>
<section>
<h2>R2.3 – A <a>Web Thing</a> MAY provide additional representation mechanisms (RDF, XML, JSON-LD)</h2>
<p>
A <a>Web Thing</a> MAY provide additional representations of its data and descriptions. JSON being the
only mandatory representation, the rest of the formats are up to the implementers if needed for additional purposes.
</p>
<p class="note">
Further specifications should describe how to enrich the data model defined in this document with semantic annotations.
</p>
</section>
<section>
<h2>R2.4 – A <a>Web Thing</a> MAY offer a HTML-based user interface</h2>
<p>
A <a>Web Thing</a> MAY expose a <abbr
title="User Interface">UI</abbr> in HTML, CSS and JavaScript. For example, the <abbr
title="User Interface">UI</abbr> may be a HTML widget that could be used to integrate the <a>Web
Thing</a> in dashboard environments.
</p>
</section>
<section>
<h2>R2.5 – A <a>Web Thing</a> MAY provide precise information about the intended meaning of individual parts of the model</h2>
<p>
A <a>Web Thing</a> MAY provide additional meta data to precisely describe the meaning of individual building blocks of a model in a machine-understandable way.
</p>
</section>
</section>
</section>
<section>
<h2>Web Things model</h2>
<p>
This part defines the model, JSON payloads and REST API that an <a>Extended Web Thing</a> MUST implement to
allow <a>Clients</a> to discover and use its properties on an automated basis. It assumes an <a
href="#web-things-integration-pattern">Integration Pattern</a> and that the Web Thing follows the <a
href="#web-things-requirements">Web Things Requirements</a>.
</p>
<p class="note">
An <a>Extended Web Thing</a> has a root resource accessible via an HTTP URL and supports HTTP <code>GET</code>
requests on that URL (see <a href="#r0.2-a-web-thing-must-have-a-root-resource-accessible-via-an-http-url"></a>
and <a href="#r0.6-a-web-thing-must-support-get-on-its-root-url"></a>).
</p>
<p>
An <a>Extended Web Thing</a> MUST create a URL endpoint for all the resources that it exposes, including itself. The JSON representation of an extended Web Thing must contain the <code>id</code>, field with its URL as value. Relative URLs are to be resolved against the URL of the resource that includes them. Implementers are encouraged to create a logical tree structure for resources and to use relative URLs to keep JSON payloads short, for instance:
</p>
<table>
<thead>
<tr>
<th>URL</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>{wt}</code>
<td>The root resource URL</td>
</tr>
<tr>
<td><code>{wt}/model/</code>
<td>The model of a Web Thing</td>
</tr>
<tr>
<td><code>{wt}/properties/</code>
<td>The list of properties</td>
</tr>
<tr>
<td><code>{wt}/properties/{id}</code>
<td>A specific property</td>
</tr>
<tr>
<td><code>{wt}/actions/</code>
<td>The list of actions</td>
</tr>
<tr>
<td><code>{wt}/actions/{id}</code>
<td>A specific action</td>
</tr>
<tr>
<td><code>{wt}/actions/{id}/{actionId}</code>
<td>A specific execution of an action</td>
</tr>
<tr>
<td><code>{wt}/.../</code>
<td>...</td>
</tr>
<!-- TODO Visualise tree structure -->
</tbody>
</table>
<section>
<h2>Common Constructs</h2>
<p>
In response to an HTTP <code>GET</code> request on one of its resources (including the root resource), an
<a>Extended Web Thing</a> MUST return a JSON representation of that resource that follows the JSON schema
defined in the table below:
</p>
<table>
<thead>
<tr>
<th>Field name</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>id</code></td>
<td>String</td>
<td>The URL of this resource following the URI format [[!RFC3986]]. Relative URLs are resolved against
the URL of the enclosing resource.
<br/><strong>This field is required</strong>.
</td>
</tr>
<tr>
<td><code>createdAt</code></td>
<td>String</td>
<td>Timestamp when this resource was created, following the ISO8601 notation [[!ISO8601]].</td>
</tr>
<tr>
<td><code>updatedAt</code></td>
<td>String</td>
<td>Timestamp when this resource was last updated, following the ISO8601 notation [[!ISO8601]].</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>A short human-readable name for the resource.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>A human-readable description of the resource.</td>
</tr>
<tr>
<td><code>tags</code></td>
<td>[String]</td>
<td>An array of tags.</td>
</tr>
<tr>
<td><code>customFields</code></td>
<td>{"key":"value",...}</td>
<td>A JSON object with key-value pairs to store custom information about this resource.</td>
</tr>
<tr>
<td><code>links</code></td>
<td>Object</td>
<td>A JSON object that lists the sub-resources that this resource links to. See <a href="#links"></a>
for details.
</td>
</tr>
</tbody>
</table>
<pre class="example" title="Basic JSON payload">
{
"id": "myCar",
"name": "My great car",
"description": "This is such a great car.",
"createdAt": "2012-08-24T17:29:11.683Z",
"updatedAt": "2012-08-24T17:29:11.683Z",
"tags": [
"cart",
"device",
"test"
],
"customFields": {
"size": "20",
"color": "blue"
},
"links": {
"model": {
"link": "model/",
"title": "Model this Web Thing."
},
"properties": {
"link": "properties/",
"title": "Properties of this Web Thing."
},
"actions": {
"link": "actions/",
"title": "Actions of this Web Thing."
},
...
}
}
</pre>
<p>
The JSON response MAY contain additional fields, depending on the type of resource being considered, check
the <a href="#resources"></a> for details.
</p>
<h3>Pagination</h3>
Requests that on things of a gateway, on properties that store the history of value changes or on executed actions return many items will be paginated to 30 items by default. You can specify any further page to be returned using the ?page parameter. You can also set a custom page size up to 100 with the ?perPage parameter.
<code>GET {wt}/properties/acceleration?page=3&perPage=100</code>
Extra pagination data is sent in response headers.
<pre class="example" title="Extra pagination data is sent in response headers">
Result-Count: 562
Link: <http://webofthings.io/properties/acceleration?page=3&perPage=100<; rel="next",
<http://webofthings.io/properties/acceleration?page=56&perPage=100<; rel="last"
</pre>
The <code>Result-Count</code> header contains the total number of results.
The pagination info is included in the Link header.
<table>
<thead>
<tr>
<th>rel value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>next</code></td>
<td>The URL of the last page of results.</td>
</tr>
<tr>
<td><code>first</code></td>
<td>The URL of the first page of results.</td>
</tr>
<tr>
<td><code>prev</code></td>
<td>The URL of the immediate previous page of results.</td>
</tr>
</tbody>
</table>
</section>
<section>
<h2>Links</h2>
<p>
A resource may link to a number of sub-resources. To enable the discovery of these sub-resources (as
required by the <abbr title="Hypermedia as the Engine of Application State">HATEOAS</abbr> constraint of the
REST application architecture), an <a>Extended Web Thing</a> SHOULD expose the sub-resources associated with
a given resource using the HTTP <code>Link</code> header field [[!RFC5988]].
</p>
<p>
In particular, each link is defined by a <strong>relation type</strong> (the "link type"), the actual URL of the sub-resource (the "link"),
and a human-readable identifier for the relation (the "title"). <a
href="https://tools.ietf.org/html/rfc5988#section-6.2.2">Relation types</a> defined in [[!RFC5988]] may
be used to characterize the relation with the sub-resource. Additionally, the Web Things model defines the
following relation types:
</p>
<table>
<thead>
<tr>
<th>Relation name</th>
<th>Description</th>
<th>Section</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>model</code></td>
<td>A link to an <a>Extended Web Thing</a> compliant description of a resource.</td>
<td><a href="#model-resource">Model Resource</a></td>
</tr>
<tr>
<td><code>properties</code></td>
<td>The properties of this resource.</td>
<td><a href="#properties-resource">Properties Resource</a></td>
</tr>
<tr>
<td><code>actions</code></td>
<td>The actions that this resource can perform.</td>
<td><a href="#actions-resource">Actions Resource</a></td>
</tr>
<tr>
<td><code>things</code></td>
<td>The <a>Web things</a> proxied by this resource (if applicable).</td>
<td><a href="#things-resource">Things Resource</a></td>
</tr>
<tr>
<td><code>subscriptions</code></td>
<td>The endpoint to manage subscriptions to this resource.</td>
<td><a href="#subscriptions-resource">Subscriptions Resource</a></td>
</tr>
<tr>
<td><code>type</code></td>
<td>Can be used to indicate that the context
resource is an instance of the resource identified by the target
external URL.</td>
<td><a href="https://www.rfc-editor.org/rfc/rfc6903.txt"></a></td>
</tr>
<tr>
<td><code>product</code></td>
<td>A link to authoritative product information for this Web Thing.</td>
<td><a href="https://schema.org/Product">Product</a></td>
</tr>
<tr>
<td><code>help</code></td>
<td>A link to the online manual page for this Web Thing.</td>
<td><a href="http://www.w3.org/TR/html5/links.html#link-type-help">4.8.4.4 Link type "help"</a> </td>
</tr>
<tr>
<td><code>ui</code></td>
<td>A link to the HTML-based user interface for this Web Thing.</td>
<td>External Resource</td>
</tr>
<tr>
<td><code>_<customLink></code></td>
<td>A link to a custom resource.</td>
<td>Custom Resource</td>
</tr>
</tbody>
</table>
<p>
An <a>Extended Web Thing</a> MAY use custom relation types using URLs as described in [[!RFC5988]].
As a convention, custom relation types names use a underscore <code>_</code> prefix.
</p>
<p>
In addition to exposing them in the HTTP Header of each resource, links SHOULD be exposed from the
<a>Model</a> resource of a <a>Extended Web Thing</a> using the <code>links</code> field of the JSON payload.
The keys of this object represent the relation type while each value describes the actual link as illustrated below.
</p>
<pre class="example" title="Links Object JSON Model">
{
...
"links":{
"<relType>":{
"link": "<String>",
"title": "<String>"
}
"<_customRelType>":{
"link": "<String>",
"title": "<String>"
},
...
}
...
}
</pre>
<p>
The following fields define the actual link:
</p>
<table>
<thead>
<tr>
<th>Field name</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>link</code></td>
<td>String</td>
<td>The URL of the destination of the link.
<br/><strong>This field is required.</strong></td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>A human-readable label of the destination of the link.
<br/><strong>This field is required.</strong></td>
</tr>
</tbody>
</table>
<pre class="example" title="Links Object JSON Example">
{
"model": {
"link": "model/",
"title": "Model of this Web Thing."
},
"properties": {
"link": "properties/",
"title": "Properties of this Web Thing."
},
"actions": {
"link": "actions/",
"title": "Actions of this Web Thing."
},
"product": {
"link": "https://www.raspberrypi.org/products/raspberry-pi-2-model-b/",
"title": "Product this Web Thing is an instance of"
},
"type": {
"link": "http://webofthings.org/schemas/web-thing/",
"title": "External information about the instance type of this Thing"
},
"help": {
"link": "http://webofthings.org/docs/pi/",
"title": "Documentation"
},
"ui": {
"link": "ui/",
"title": "User Interface"
},
"_myCustomLinkRelType": {
"link": "custom/",
"schema": "http://webofthings.org/schemas/custom.html",
"title": "My custom resource"
},
"_..." : {"..." : {"..."}}
}
</pre>
<p>
A <code>GET</code> on any resource of a Web Thing should return the list of all related resources as "Link" HTTP headers, which allows to use the same standard model regardless of the representation chosen. This is an example of the headers returned after a <code>GET {wt}/</code> on the root URL of a Web Thing:
</p>
<pre class="example" title="Links in the HTTP Header">
Link: <model/>; rel="model"
Link: <properties/>; rel="properties"
Link: <actions/>; rel="actions"
Link: <product/>; rel="product"
Link: <type/>; rel="type"
Link: <help/>; rel="help"
Link: <ui/>; rel="ui"
</pre>
</section>
<section>
<h2>Values</h2>
<p>
Several resources support values (particularly <a>Actions</a> and <a>Properties</a>).
A <code>values</code> object contains the description of a set of values identified by their name. The
description includes the value type, unit, and possible concrete values that the value can take. A <code>values</code>
object is typically used to define the parameters a <a>Client</a> can use when it issues an <a>Action</a> or
accesses the channels of a <a>Property</a>.
</p>
<p>
The following fields MAY be used to describe a value:
</p>
<table>
<thead>
<tr>
<th>Field name</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code><valueName></code></td>
<td>String</td>
<td>The identifier of this value <br/><strong>This field is required</strong>.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>A human-readable caption for this value.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>A human-readable description of this value.</td>
</tr>
<tr>
<td><code>type</code></td>
<td>String</td>
<td>The type of this value. The supported types are <code>integer</code>, <code>float</code>, <code>boolean</code>,
<code>string</code>.
</td>
</tr>
<tr>