Widex Hypermedia Language

Widex Hypermedia Language (whl) is a Widex standard which establishes conventions for expressing hypermedia controls, such as links, with JSON.

WHL is a generic media type with which Web APIs can be developed and exposed as series of links. Clients of these APIs can select links by their link relation type and traverse them in order to progress through the application.

WHL Documents

A WHL Document has the media type "application/vnd.whl.{ressource-name}.json+{version}".
an example of a shops ressource would be application/vnd.whl.shops.json+v1

The Resource Object could look like this: 
GET /shops/filter-country/US HTTP/1.1
Host: accounts-api.widex.com
Accept: application/vnd.whl.shops.json+v1
HTTP/1.1 200 OK
Content-Type: application/vnd.whl.shops.json+v1

{
shops: [
  {
    id: "758E2CE6-91E9-E411-8103-C4346BADA21C",
    priority: 0,
    title: "HEAR-WELL CENTER - LONG BEACH",
    latitude: 338226907,
    longitude: -1181895396,
    addressLine1: "3605 LONG BEACH BLVD, SUITE 110",
    postalCode: "90807",
    city: "LONG BEACH",
    state: "CA",
    country: "US",
    _links: [
    {
      rel: "http://accounts-api.widex.com/api/global/shop/definition",
      href: "http://accounts-api.widex.com/api/global/shops/758E2CE6-91E9-E411-8103-C4346BADA21C",
      type: "application/vnd.whl.shop.json+v1"
      method: "GET"
    }
    ]
  }],
  _links: [
    {
      rel: "self",
      href: "http://accounts-api.widex.com/api/global/shops/filter-country/US",
      type: "application/vnd.whl.shops.json+v1"
      method: "GET"
    },
    {
      rel: "next",
      href: "http://accounts-api.widex.com/api/global/shops/filter-country/{country}",
      method: "GET",
      parameters: {
        limit: "10"
      }
    },
    {
      name: "shops-filter-country",
      rel: "/api/global/shops/definition#filter-country",
      href: "/api/global/shops/filter-country/{country}",
      method: "GET"
    },
    {
      name: "shops-filter-city",
      rel: "/api/global/shops/definition#filter-city",
      href: "/api/global/shops/filter-city/{city}",
      method: "GET"
    },
    {
      name: "shops-filter-postalcode",
      rel: "/api/global/shops/defintition#filter-postalcode",
      href: "/api/global/shops/filter-postalcode/{postalcode}",
      method: "GET"
    }
  ]
}
Here, we have a WHL shops document representing shops resource filtered by US with the URI "/shops/filter-country/US". It has "shops-filter-country", "shops-filter-city", "shops-filter-postalcode" links, and its own state in the form of collection of shops.

Resource Objects

A Resource Object represents a resource. It has two reserved properties:
  • "_links": contains links to other resources.
  • "_embeds": contains embedded resources.
All other properties MUST be valid JSON, and represent the current state of the resource.

Reserved Properties


_links
is an object whose property names are link relation types and values are either a Link Object or an array of Link Objects. The subject resource of these links is the Resource Object of which the containing "_links" object is a property.

_embeds
Is an object whose property names are link relation types and values are either a Resource Object or an array of Resource Objects. Embedded Resources MAY be a full, partial, or inconsistent version of the representation served from the target URI.

Link Objects

A Link Object represents a hyperlink from the containing resource to a URI. It has the following properties:

href
The "href" value is an URI and the property is REQUIRED.

type
The "type" property is OPTIONAL. Its value is a string used as a hint to indicate the media type expected when dereferencing the target resource.