Retrieve a Web Thing

In response to an HTTP GET request on the root URL of a Thing, an Extended Web Thing MUST return an object that its representation.

            --> REQUEST
            GET {wt}
 
            <-- RESPONSE
            200 OK
            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"
            Link: <_myCustomLinkRelType/>; rel="_myCustomLinkRelType"

            {
              "id": "myCar",
              "name": "My super great car",
              "description": "This is such a great car.",
              "createdAd": "2012-08-24T17:29:11.683Z",
              "updatedAd": "2012-08-24T17:29:11.683Z",
              "tags":["cart", "device", "test"],
              "customFields":{
                  "size": "20",
                  "color":"blue"
              }
            }
            

Update a Web Thing

In response to an HTTP PUT request on a Web Thing URL with a Web Thing object as request body, an Extended Web Thing MUST either reject the request with the appropriate status code (e.g. because the Client is unauthenticated or because the Thing is read-only) or store the provided value(s) by updating the Web Thing. Partial updates are authorized and result in updating the fields that were provided in the request body.

            --> REQUEST
            PUT {wt}
    
            {
              "name":"My really super great car"
            }

            <-- RESPONSE
            204 NO CONTENT
            

Retrieve the model of a Thing

In response to an HTTP GET request on the destination URL of a model link, an Extended Web Thing MUST return an object containing the model of the Thing.

                --> REQUEST
                GET {wt}/model

                <-- RESPONSE
                200 OK

{
  "id": "pi",
  "name": "My WoT Raspberry PI",
  "description": "A simple WoT-connected Raspberry PI for the WoT Label.",
  "tags": [
    "raspberry",
    "pi",
    "WoT"
  ],
  "customFields" : {
    "port" : 8484
  },
  "links": {
    "product": {
      "link": "https://www.raspberrypi.org/products/raspberry-pi-2-model-b/",
      "title": "Product this Web Thing is based on"
    },
    "properties": {
      "link": "/properties",
      "title": "List of Properties",
      "resources": {
        "temperature": {
          "name": "Temperature Sensor",
          "description": "An ambient temperature sensor.",
          "values": {
            "temp": {
              "name": "Temperature sensor",
              "description": "The temperature in celsius",
              "unit": "celsius",
              "customFields": {
                "gpio": 21
              }
            }
          },
          "tags": [
            "sensor",
            "public",
            "indoors"
          ]
        },
        "humidity": {
          "name": "Humidity Sensor",
          "description": "An ambient humidity sensor.",
          "values": {
            "h": {
              "name": "Humidity",
              "description": "Percentage of Humidity",
              "unit": "percent",
              "customFields": {
                "gpio": 21
              }
            }
          },
          "tags": [
            "sensor",
            "public"
          ]
        },
        "pir": {
          "name": "Passive Infrared",
          "description": "A passive infrared sensor.",
          "values": {
            "p": {
              "name": "Presence",
              "description": "Current sensor value (true=motion detected)",
              "type": "boolean",
              "customFields": {
                "gpio": 20
              }
            }
          },
          "tags": [
            "sensor",
            "public"
          ]
        },
        "leds": {
          "name": "LEDs",
          "description": "The LEDs of this device.",
          "values": {
            "1": {
              "name": "LED 1",
              "customFields": {
                "gpio": 17
              }
            },
            "2": {
              "name": "LED 2",
              "customFields": {
                "gpio": 19
              }
            }
          },
          "tags": [
            "sensor",
            "public"
          ]
        }
      }
    },
    "actions": {
      "link": "/actions",
      "title": "Actions of this Web Thing",
      "resources": {
        "ledState": {
          "values": {
            "ledId": {
              "type": "string",
              "required": true
            },
            "state": {
              "type": "boolean",
              "required" : true
            }
          }
        }
      }
    },
    "type": {
      "link": "http://w3c.org/schemas/webthing/",
      "title": "Instance type of the Pi"
    },
    "help": {
      "link": "http://webofthings.org/docs/pi/",
      "title": "Documentation"
    },
    "ui": {
      "link": "/ui",
      "title": "User Interface"
    }
  }
}
            

Update the model of a Thing

In response to an HTTP PUT request on a Model URL with a Model object as request body, an Extended Web Thing MUST either reject the request with the appropriate status code (e.g. because the Client is unauthenticated or because the Model is read-only) or store the provided value(s) by updating the Model. Partial updates are authorized and result in updating the fields that were provided in the request body.

Usually, the model will be hardcoded in the device and generally cannot be altered by clients. If the Web Thing is hosted on a cloud service, the model can be updated by sending an HTTP PUT request to the same URL, with the new model document in the request body.

Retrieve a list of properties

In response to an HTTP GET request on the destination URL of a properties link, an Extended Web Thing MUST return an array of Property that the initial resource contains.

              --> REQUEST
              GET {wt}/properties


              <-- RESPONSE
              200 OK
              Link: <http://webofthings.io/properties>; rel="type"

              [
                {
                  "id":"temperature",
                  "name":"Kitchen Temperature Sensor",
                  "values":{
                    "temp":22,
                    "timestamp":"2015-06-14T14:30:00.000Z"
                  }
                },
                {
                  "id":"status",
                  "name":"Device Status",
                  "values":{
                    "status":"OK",
                    "timestamp":"2015-06-14T14:30:00.000Z"
                  }
                },
                {
                  "id":"acceleration",
                  "name":"Acceleration",
                  "values":{
                    "x":22,
                    "y":22.56,
                    "z":1.4,
                    "timestamp":"2015-06-14T14:30:00.000Z"
                  }
                },
                {
                  "id":"engineAngle",
                  "name":"Engine Angle",
                  "values":{
                    "theta":2,
                    "rho":-0.1,
                    "timestamp":"2015-06-14T14:30:00.000Z"
                  }
                }
              ]
            

Retrieve the value of a property

In response to an HTTP GET request on a Property URL, an Extended Web Thing MUST return an array that lists recent values of that Property.

Some Web Things might not store the history of sensor readings but only the most recent value of a given property, in which case the array will always contain one object. However, Web Things on clouds and gateway are likely to store many past values of the property, in which case they can be retrieved using pagination.

              --> REQUEST
              GET {wt}/properties/acceleration

              <-- RESPONSE
              200 OK
              Link <model/>; rel="model"

              [
                {
                  "x":11,
                  "y":1,
                  "z":-4.4,
                  "timestamp":"2015-06-14T14:30:00.000Z"
                },
                {
                  "x":3.4,
                  "y":-1,
                  "z":-4.6,
                  "timestamp":"2015-06-14T14:00:00.000Z"
                }
              ]
            

Update a specific property

In response to an HTTP PUT request on a Property URL with an array of values as request body, an Extended Web Thing MUST either reject the request with the appropriate status code (e.g. because the Client is unauthenticated or because the Property is read-only) or store the provided value(s) as new values for the Property. The body of the request SHOULD always be an array of values (at least one), which allows to send several property value updates within a single request.

              --> REQUEST
              PUT {wt}/properties/temperature/

              [
                {
                  "temp":24
                }
              ]


              <-- RESPONSE
              204 NO CONTENT
              Location: {wt}/properties/temperature/
            

A Property URL is always a collection of resources, therefore its representation is an array of individual values with different timestamps. The individual values are not adressable individually, therefore the Location: header in response to a successful property update request SHOULD always be the Property URL itself.

Update multiple properties at once

In response to an HTTP POST request on the destination URL of a properties link, an Extended Web Thing MUST either reject the request with the appropriate status code or store the provided values as new values for each of the provided Properties.

              --> REQUEST
              PUT {wt}/properties/

              [
                {
                  "id":"temperature",
                  "value":{
                    "temp":24,
                    "timestamp":"2015-06-14T14:30:00.000Z"
                  }
                },
                {
                  "id":"acceleration",
                  "value":{
                    "x":-22,
                    "y":2.1,
                    "z":3,
                  }
                }
              ]

              <-- RESPONSE
              204 NO CONTENT
              Location: {wt}/properties/
            

Retrieve a list of actions

In response to an HTTP GET request on the destination URL of an actions link exposed by a resource, an Extended Web Thing MUST return an array of Action descriptions that the initial resource may perform.

              --> REQUEST
              GET {wt}/actions


              <-- RESPONSE
              200 OK
              Link: <http://webofthings.org/actions/upgradefirmware>; rel="type"

              [
                {
                  "id":"upgradeFirmware",
                  "name":"Upgrade Device Firmware"  
                },
                {
                  "id":"reboot",
                  "name":"Reboot"  
                }
              ]
            

Retrieve recent executions of a specific action

In response to an HTTP GET request on an Action URL, an Extended Web Thing MUST return an array that lists the recent executions of a specific Action.

On top of , the JSON representation used to describe the execution of an Action includes the following fields:

              --> REQUEST
              GET {wt}/actions/upgradefirmware

              <-- RESPONSE
              200 OK
              Link: <http://webofthings.org/actions/upgradefirmware>; rel="type"
              Link: <model/>; rel="model"

              [
                {
                  "id":"223",
                  "value":{
                    "delay":30,
                    "mode":"SOFT"
                  },
                  "status":"executing"
                  "timestamp":"2015-06-14T18:33:25.938Z"
                },
                {
                  "id":"222",
                  "value":{
                    "delay":60,
                    "mode":"FORCE"
                  },
                  "status":"completed"
                  "timestamp":"2015-06-14T14:22:23.233Z"
                }
              ]
            

Execute an action

In response to an HTTP POST request on an Action URL with valid parameters as request body, an Extended Web Thing MUST either reject the request with the appropriate status code or queue a task to run the action and return the status of that action in a 201 Created response. The action may not run immediately. The Location HTTP header identifies the URL to use to retrieve the most recent update on the action's status.

This is how a Client sends a command to a device.

              --> REQUEST
              POST {wt}/actions/reboot

              {
                "delay":50,
                "mode":"debug"
              }

              <-- RESPONSE
              204 NO RESPONSE
              Location: {wt}/actions/reboot/233
            

Retrieve the status of an action

In response to an HTTP GET request on the URL targeted by the Location HTTP header returned in response to the request to execute an action, an Extended Web Thing MUST return the status of this action or a 404 Not Found status code if the action's status is no longer available.

                      --> REQUEST
                      GET {wt}/actions/reboot/233

                      <-- RESPONSE
                      200 OK

                      {
                        "id":"233",
                        "value":{
                          "delay":50,
                          "mode":"debug"
                        },
                        "status":"executing",
                        "timestamp":"2015-06-14T14:30:00.000Z"
                      }
                    

Retrieve a list of Web Things

In response to an HTTP GET request on the destination URL of a things link, an Extended Web Thing MUST return an array of things descriptions.

                    --> REQUEST
                    GET {wt}/things
                                
                    <-- RESPONSE
                    200 OK

                    [
                      {
                        "id":"982tjqogeih",
                        "name":"Shopping Cart"
                      },  
                      {
                        "id":"2398h87wt489foz",
                        "name":"Shopping Cart",
                        "rootUrl":"/pi",
                        "description":"Shopping Cart that updates its location as it moves"
                      },  
                      {
                        "id":"p9qrnc89w48oh",
                        "name":"Shopping Cart",
                        "rootUrl":"https://192.168.0.6/",
                        "description":"LAN-connected gateway to Lamp #4."
                      }
                    ]
                    

The id can be interpreted as a URL, but if a Web Thing can be directly accessed without the proxy, the rootUrl can be used to provide a different Root URL.

Add a Web Thing to a gateway

Clients can add new Things to be proxied by a Web Thing (especially for gateways/cloud) using an HTTP POST request on the Thing URL of a Web Thing and by sending in the request body the root resource representation of the Thing to be proxied.

                    --> REQUEST
                    POST {wt}/things

                    {
                      "id":"p9qrnc89w48oh",
                      "name":"Shopping Cart",
                      "rootUrl":"https://192.168.0.6/",
                      "description":"LAN-connected gateway to Lamp #4."
                    }
                                
                    <-- RESPONSE
                    204 NO CONTENT
                    Location: {wt}/things/p9qrnc89w48oh
                    

Create a subscription

An Extended Web Thing SHOULD support subscriptions via the WebSocket [[!RFC6455]] protocol and MAY support subscriptions via WebHooks (HTTP callbacks). Subscriptions are enabled via the HTTP protocol upgrade mechanism [[!RFC2616]] as shown below.

To subscribe to a resource the following HTTP headers should be provided via a GET request (e.g., on /properties/temp).

In response to a HTTP GET request on the destination URL of a resource, an Extended Web Thing MUST either reject the request with an appropriate status code or MUST return a 101 Switching Protocol response for a subscription via Websocket or a 200 OK for a subscription via Webhook. It SHOULD then create a record for the subscription that can be retrieved via the /subscriptions URL. For both Websockets and Webhooks subscriptions the following headers must be returned (on top of the protocol specific headers):

Retrieve a list of subscriptions

In response to an HTTP GET request on the destination URL of a subscriptions link, an Extended Web Thing MUST return the array of subscriptions to the underlying resource.

            [
              {
                "id":"2349",
                "type":"webhook",
                "resource":"/properties/temperature",
                "callbackUrl":"http://www.compose-project.eu/so/ServiceObject-123213213/callback"
              },
              {
                "id":"2350",
                "subscriberId":"ServiceObject-123213213",
                "type":"websocket",
                "resource":"/properties/location"
              }
            ]
            

The Subscription URL is the result of resolving the id returned in a Subscription resource description against the destination URL of the subscriptions link that gave birth to it.

Retrieve information about a specific subscription

In response to an HTTP GET request on a Subscription URL, an Extended Web Thing MUST return a JSON representation of the subscription. The JSON representation should be the same as the one returned for that subscription in .

              {
                "id":"2349",
                "type":"webhook",
                "resource":"/properties/temperature",
                "callbackUrl":"http://www.compose-project.eu/so/ServiceObject-123213213/callback"
              }
            

Delete a subscription

In response to an HTTP DELETE request on the destination URL of a subscriptions an Extended Web Thing MUST either reject the request with an appropriate status code or remove (unsubscribe) the subscription and return a 200 OK status code.