Hypermedia

The Wurl API implements a Hypermedia API. What is Hypermedia and why should I care? We explain below.

HATEOAS

HATEOAS (Hypermedia As The Engine Of Application State) is a rather powerful concept. Quoting the wikipedia description:

The principle is that a client interacts with a network application entirely through hypermedia provided dynamically by application servers. A REST client needs no prior knowledge about how to interact with any particular application or server beyond a generic understanding of hypermedia.

What this means is that when both the server and client respect the constraints of Hypermedia, both can evolve independently without breaking every time either one changes. The Wurl API enables this by providing URLs for you.

Use provided URLs

Your client should not construct URLs. The only URL your client needs to know about is the Root URL for the API, https://api.wurl.com/api. Any further URL's you will need to interact with the API will be provided in the API responses.

For example, let's start with the Root URL:

$ curl https://api.wurl.com/api
{
 "links": [
  {
   "rel": ["self"],
   "href": "https://api.wurl.com/api"
  },
  {
   "rel": ["urn:x-resource:name:me"],
   "href": "https://api.wurl.com/api/users/me"
  }
 ]
}

The Root URL provides a number of links to the resources you have available to you. Each link has a named rel (urn:x-resource:name). The named rel is the Wurl API's contract with its clients. When you look up the resource with rel urn:x-resource:name:me then you are guaranteed to lookup the resource for your user account. Similarly, the Wurl API is free to change the URL to https://api.wurl.com/api/users/3423 in the future without breaking your client because you 'find' the URL by rel instead of manually constructing the URL in your client.

Hypermedia

The Wurl API implements a Hypermedia API. What is Hypermedia and why should I care? We explain below.

HATEOAS

HATEOAS (Hypermedia As The Engine Of Application State) is a rather powerful concept. Quoting the wikipedia description:

The principle is that a client interacts with a network application entirely through hypermedia provided dynamically by application servers. A REST client needs no prior knowledge about how to interact with any particular application or server beyond a generic understanding of hypermedia.

What this means is that when both the server and client respect the constraints of Hypermedia, both can evolve independently without breaking every time either one changes. The Wurl API enables this by providing URLs for you.

Use provided URLs

Your client should not construct URLs. The only URL your client needs to know about is the Root URL for the API, https://api.wurl.com/api. Any further URL's you will need to interact with the API will be provided in the API responses.

For example, let's start with the Root URL:

$ curl https://api.wurl.com/api
{
 "links": [
  {
   "rel": ["self"],
   "href": "https://api.wurl.com/api"
  },
  {
   "rel": ["urn:x-resource:name:me"],
   "href": "https://api.wurl.com/api/users/me"
  }
 ]
}

The Root URL provides a number of links to the resources you have available to you. Each link has a named rel (urn:x-resource:name). The named rel is the Wurl API's contract with its clients. When you look up the resource with rel urn:x-resource:name:me then you are guaranteed to lookup the resource for your user account. Similarly, the Wurl API is free to change the URL to https://api.wurl.com/api/users/3423 in the future without breaking your client because you 'find' the URL by rel instead of manually constructing the URL in your client.