Techniques for specifying services

From Web of Things Community Group
Revision as of 16:07, 3 October 2013 by Dsr (talk | contribs)

This section covers techniques that can be used to specify the protocol or API for accessing services for the Web of Things. This includes the use of WebIDL for APIs, XML and JSON for structured data, Web Services and RESTful HTTP.

Web IDL

Web IDL is an interface definition language that is commonly used in W3C specifications for JavaScript APIs exposed by web browsers. It includes a suite of pre-defined data types including numbers, strings, arrays, as well as support for enumerations, unions and call backs. The Web IDL specification includes a binding to JavaScript (formally known as ECMAScript), but bindings to other languages are possible.

Here is an example of a Web IDL fragment: 

exception GraphicsException {
  DOMString reason;
};

interface Paint { };

interface SolidColor : Paint {
  attribute float red;
  attribute float green;
  attribute float blue;
};

interface Pattern : Paint {
  attribute DOMString imageURL;
};

[Constructor]
interface GraphicalWindow {
  readonly attribute unsigned long width;
  readonly attribute unsigned long height;

  attribute Paint currentPaint;

  void drawRectangle(float x, float y, float width, float height);

  void drawText(float x, float y, DOMString text);
};

XML

The Extensible Markup Language (XML) is a simple and flexible text format derived from SGML (ISO 8879). Angle brackets are used to introduce mark-up tags into a text stream. The permitted structure of an XML document can be constrained to match a formal grammar, e.g. using the XML Schema language. XML is frequently used for representing structured data and as such can be used for messages as part of protocol used for accessing a service. XML is defined by a suite of standards produced by the W3C.

Here is a small example of a part of an XML document: 

<part number="1976">
  <name>Windscreen Wiper</name>
  <description>The Windscreen wiper
    automatically removes rain
    from your windscreen, if it
    should happen to splash there.
    It has a rubber <ref part="1977">blade</ref>
    which can be ordered separately
    if you need to replace it.
  </description>
</part>

JSON

The JavaScript Object Notation (JSON) is a popular lightweight syntax for data exchange. It includes collections of name/value pairs, and a set of built-in data types, e.g. numbers, booleans, strings and arrays. JSON can be readily parsed into the native data types for languages such as JavaScript and Java.

Here is an example: 

{"menu":
  {
    "id": "file",
    "value": "File",
    "popup":
    {
      "menuitem": [
        {"value": "New", "onclick": "CreateNewDoc()"},
        {"value": "Open", "onclick": "OpenDoc()"},
        {"value": "Close", "onclick": "CloseDoc()"}
      ]
    }
  }
}

JSON has been extended to support pointers, linked data and schemas:

JSON Pointer

JSON Pointer defines a syntax for identifying a specific value within a JSON document.

The following examples illustrate the use of JSON pointers in URI fragments for a JSON text document located at http://example.com/example.json 

{
  "foo": {
    "bar": [ "element0", "element1" ],
    "inner object": {
      "baz": "qux"
    }
  }
}

http://example.com/example.json#
   Resolves to the object value at the root of the JSON text
   document.

http://example.com/example.json#/foo
   Resolves to the object value of the "foo" member in the root object.

http://example.com/example.json#/foo/inner%20object/baz
   Resolves to the string value "qux", which is the value of the
   "baz" member in the "inner object" member in the "foo" member in
   the root object.

http://example.com/example.json#/foo/bar/0
   Resolves to the string value "element0", which is the first value
   in the "bar" array in the "foo" member in the root object.

with thanks for the examples to Paul C. Bryan.

JSON-RPC

JSON-RPC is a framework for remote procedure calls expressed using JSON. An identifier is used to associate each response with its request. JSON-RPC is often used in conjunction with WebSockets.

Here is an example for a service that adds one to the integer passed to it: 

--> { "method": "increment", "params": [65], "id": 7}
<-- { "result": 66, "error": null, "id": 7}

JSON Linked Data

JSON-LD is a set of conventions for representing linked data in JSON. Linked data provides a way to create a network of standards-based, machine-readable data across Web sites. For the Web of Things JSON-LD offers a way of exchanging rich metadata about things and services based upon them.

Here is a small example: 

{
  "http://schema.org/name": "Manu Sporny",
  "http://schema.org/url": { "@id": "http://manu.sporny.org/" },
  "http://schema.org/image": { "@id": "http://manu.sporny.org/images/manu.png" }
}

This is equivalent to the following JSON: 

{
  "name": "Manu Sporny",
  "homepage": "http://manu.sporny.org/",
  "image": "http://manu.sporny.org/images/manu.png"
}

JSON-LD uses IRIs to identify the name space for each name. @id is a predefined term that indicates that the value is an IRI (essentially a variant of web addresses that allows for non-western characters).

JSON Schema

JSON Schema can be used to define the structure of JSON data for the purposes of validation, documentation, and interaction control.

Here is a small example of a schema: 

{
  "title": "Example Schema",
  "type": "object",
  "properties": {
    "givenName": {
      "type": "string"
    },
    "familyName": {
      "type": "string"
    },
    "age": {
      "description": "Age in years",
      "type": "integer",
      "minimum": 0
    }
  },
  "required": ["firstName", "lastName"]
}

and here is an example of a JSON document that conforms to it: 

{
  "givenName": "John,
  "familyName": "Smith",
  "age": 42
}

Web Services

This term generally refers the the use of XML for services based upon the Simple Object Access Protocol (SOAP). Services can be specified using the Web Services Description Language (WSDL).

The W3C Web Services Activity page provides links to a suite of Web Services specifications.

Here is an example message: 

POST /InStock HTTP/1.1
Host: www.example.org
Content-Type: application/soap+xml; charset=utf-8
Content-Length: 299
SOAPAction: "http://www.w3.org/2003/05/soap-envelope"
 
<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
  <soap:Header>
  </soap:Header>
  <soap:Body>
    <m:GetStockPrice xmlns:m="http://www.example.org/stock">
      <m:StockName>IBM</m:StockName>
    </m:GetStockPrice>
  </soap:Body>
</soap:Envelope>

Web Services have been widely used for enterprise applications, but in recent years its popularity on the public Internet has declined in favour of RESTful HTTP together with JSON.

RESTful HTTP

HTTP provides a popular means for accessing services. In some cases, a device can integrate sensors, actuators and an HTTP server, or a device can act as a gateway, e.g. using ZigBee to communicate with sensors, and exposing their data via HTTP. In many cases, devices will be isolated behind security firewalls. In this situation, services can be exposed by servers in the cloud that hide the details of the communication with the sensors and actuators.

HTTP is a request/response protocol that can be used to implement remote procedure calls. The term representational state transfer (REST) was introduced and defined in 2000 by Roy Fielding, one of the principal authors of the HTTP specification. REST is essentially an architectural style for using HTTP in a scalable way.

The request specifies an HTTP method, and the appropriate choice of method depends on the nature of the service that is invoked. Here are the methods used for RESTful services:

GET
Is used for services that are side effect free, as this allows the response to be cached.
POST
Is used for services that aren't side effect free, e.g. operating an actuator.
PUT
Is used to store a specified resource, e.g. saving an image passed in the request.
PATCH
Is used to make a partial modification to the specified resource.
DELETE
Is used to delete the specified resource.

PUT and DELETE are idempotent, i.e. multiple identical requests should have the same effect as a single request.

HTTP requests and responses consist of a set of named headers and a body. If the body is present, its type is indicated by the Content-Type header. Responses also include a status code, e.g. "200 Okay" or "404 Not found". To specify HTTP based services, it is therefore necessary to define the data passed in the request, the method used, the data returned in the response and the response code.

Some services will result in asynchronous notifications or events. There are several approaches to implementing this with HTTP. One is to pass an HTTP URL to the service for where to deliver the notification. Another is to poll the service (using POST) to see what new notifications are available. A refinement is to have an extended HTTP response where the connection to the client is kept open, and the body is sent as a sequence of messages. The first approach won't work if the recipient for notifications is hidden behind a firewall, as in the firewall will block the incoming connection unless the firewall has been specifically configured to allow it. The latter two approaches are often used for pushing notifications to web page scripts executing in browsers. Service definitions need to specify the details for the approach used for notifications.

Retrieved from "https://www.w3.org/community/wot/wiki/index.php?title=Techniques_for_specifying_services&oldid=310"