Selfdescribing RESTful api

Question

I am building a (RESTful) api (using HTTP) that I want to use with javascript.

I find my self writing stuff in javascript like

function getPost(id)
{
    $.getJSON("/api/post/" + id, function(data){
        // Success!
    });
}

There must be a smarter way than hardcoding the api in javascript, maybe something like querying the api itself for how the getPost url should look like?

function getApiPostUrl()
{
    $.getJSON("/api/getpost/");
}

returning something like

url: "/api/post/:id"

Which can be parsed by javascript to obtain the url for actually getting the post with id=:id. I like this approach.

Is a standard way of doing this? I am looking for a good approach so I don't have to invent it all, if there already exists a good solution.

Answer 1

Well, per definition, a RESTful API shall contain the full URI - a Resource Identifier, and not only the resource's path. Thus your question is more a question on how you're designing your whole API.

So, for example, your API could contain a http://fqdn/api/posts that contains a list of all the posts within your site, e.g.:

[ "http://fqdn/api/posts/1",
  "http://fqdn/api/posts/2",
  "http://fqdn/api/posts/3" ]

and then your javascript only iterates over the values within the list, never needing to craft the path for each resource. You only need to have one known entry point. This is the HATEOAS concept, that uses hyperlinks as API to identifies states of an application.

All in all, it's a good idea to thoroughly think your application (you can use UML tools like the state machine or sequence diagrams..) so that you can cover all your use cases with a simple yet efficient set of sequences defining your API. Then for each sequence, it's a good idea to have a single first state, and you can have a single first step linking to all the sequences.

• Resources:
  • ACM Article
  • Restful API Design Second Edition Slides
  • Restful API design blog

Answer 2

Yes, there are quite a few standard ways of doing this. What you want to look for is "hypermedia APIs" - that is, APIs with embedded hypermedia elements such as link templates like yours, but also plain links and even more advanced actions (forms for APIs).

Here is an example representation using Mason to embed a link template in a response:

{
  id: 1234,
  title: "This is issue no. 1",
  "@link-templates": {
    "is:issue-query": {
      "template": "http://issue-tracker.org/mason-demo/issues-query?text={text}&severity={severity}&project={pid}",
      "title": "Search for issues",
      "description": "This is a simple search that do not check attachments.",
      "parameters": [
        {
          "name": "text",
          "description": "Substring search for text in title and description"
        },
        {
          "name": "severity",
          "description": "Issue severity (exact value, 1..5)"
        },
        {
          "name": "pid",
          "description": "Project ID"
        }
      ]
    }
  }
}

The URL template format is standardized in RFC 6570.

Mason is not the only available media type for hypermedia APIs. There is also HAL, Sirene, Collection-JSON and Hydra.

And here is a discussion about the benefits of hypermedia.

Answer 3

Your code clearly violates the self-descriptive messages and the hypermedia as the engine of application state (abbr. HATEOAS) of the uniform interface constraint of REST.

According to HATEOAS you should send back hyperlinks, and the client should follow them, so it won't break by changes of the API. A hyperlink does not equal with an URL. It contains an URL, a HTTP method, maybe the content-type of the body, possibly input fields, etc...

According to self-descriptive messages you should add semantics to the data, the links, the input fields, etc... The client should understand that semantics and behave accordingly. So for example you can add a "create-post" API specific link relation to your hyperlink so the client will understand that it is for creation of posts. Your client should always use these kind of semantics instead of parsing the URLs.

URLs are always API specific, semantics not necessarily, so these constraints decouple the client from the API. After that the client won't break by URL changes or not even data structure changes, because it will use a standard hypermedia format (for example HAL, JSON-LD, ATOM or even HTML) and semantics (probably RDF) to parse the response body.