Widex RESTful API specification

The Widex API specification is heavily inspired by the NARWHL, and much of the text is therefor borrowed from http://www.NARHWL.com
the specification includes the following area:
  • Response format
  • Content Negotiation
  • Endpoint definitions

RESPONSE FORMAT

Widex’s response format is called WHL (Widex Hypermedia Lanugage). WHL is using the NARWHL’s basic requirements:
  • Relationships between resources must be represented by links.
  • The data specific to the request response must sit at the top level of the response, not embedded within related resources. Read more about the WHL Response format specification

CONTENT NEGOTIATION

Key feature of hypermedia is the ability for the client to request the response in a particular format and for the server to respond to that – and several other – formats as necessary. For example, a client could request the response come back formatted as XML, typically by specifying that in the “Accepts” header by using the standard XML MIME-type string “text/xml”. If the server doesn’t support XML as a response format, it should send back an HTTP error code “406 Not Acceptable”.

Widex is using the content headers which allows for more fine-grained control over the negotiation process, allowing the client to specify not just the high-level format – i.e. JSON or XML – but the actual profile that governs the layout, including the version. Widex is providing custom MIME types for each resource, for instance the products MIME type will look as below:

Application/vnd.whl.products.json+v2

Note the use both of the representational format (“json”) and the version (“v2”). This form of content negotiation allows versioning at the individual resource level, which can help keep the codebase that drives the application clean and consistent while allowing for increased flexibility to iterate. If the client application sets the Accept header to “*/*” or leaves it out completely, the API will return its preferred representational format, which will be the most recent version of the custom Product representation.

Endpoint DEFINITIONS

Every resource should be responsible for defining what can request and should expect in the response. This means that every resource should have definitions links, and is written with JSON Schemas

Requests to resources should include a Link in the response header back to the definition for the resource. For example, a call to the resource URI /products Should respond with the expected representation of the resource, but the response header should include
Link: http://products-api.widex.com/api/it01/products/definition; rel="service"

The “service” relationship is borrowed from the ATOM publishing protocol, where it serves a similar purpose.

Every related links should have the definition link inside the rel. see example below: 
data: [{
  services: [{
    _links: [
    {
      name: "shops",
      rel: "http://accounts-api.widex.com/api/global/shops/definition",
      href: "http://accounts-api.widex.com/api/global/shops",
      method: "GET"
    },
    {
      name: "hearingaids",
      rel: "http://ha-api.widex.com/api/global/hearingaids/definition",
      href: "http://ha-api.widex.com/api/global/hearingaids",
      method: "GET"
    },
    {
      name: "hearingaid images",
      rel: "http://cdnimg.widex.com/definition",
      href: "http://cdnimg.widex.com",
      method: "GET"
    }]
  }],
  _links: [
  {
    rel: "self",
    href: "http://api.widex.com/",
    method: "GET"
  }
]