Hypermedia, makes APIs better

3rd Meetup API Paris

18th April 2013

But first introductions and 101

Who's talking?

Hello my name is Ori Pekelman. I am OriPekelman everywhere (twitter/github/linked-in).

My blog is on http://blog.constellationmatrix.com

I am an independent software architect and I made myself a nice logo.

What is an API?

Application programming interface

It is a system that allows a program to expose functionality and data to another program.

What makes a good API?

1. it is abstract: requires minimal knowledge about the implementation of the program exposed

What makes a good API?

1. it is standard: imposes the absolute minimum client side dependencies

What makes a good API?

1. it is general: it makes minimal assumptions on the way it is going to be used

What makes a good API?

1. it is simple: it allows to implement very quickly the most common use-cases (sometimes orthogonal to generality)

What makes a good API?

1. it is self-describing: it requires only minimal documentation

What makes a good API?

1. it is predictable: it does not surprise the user and it adheres to common patterns and conventions

• REST is a pragamtic style for making APIs
• That promotes "good APIs"

Applying a style is what we call the "design process"

Software deals with entities that have data

In RESTspeak we call these entities "resources"

An API will exposes methods to read and write data

Writing data can be expressed as a state transition

So... Whats is a resource?

• Something that can be uniquely addressed.
• Something that can be addressed, can be addressed by a url.

How do REST urls look like?

REST urls look like just normal urls

http://www.w3.org is a good one. Also http://pekelman.com/time or http://pekelman.com/time.json or https://github.com/OriPekelman/paris-rb-grape-talk/commits/master

I will get back to this

But they usually look like:

• http://api.example.com/{resource_type}/{resource_id}.{output_format}?{filters..and..api_key..as..arguments}

or

• http://api.example.com/{collection}/{item}/{collection}/{item}/{sub_resource}

or something like

• http://api.example.com/{ver}/{lang}/{resource_type}/{resource_id}.{output_format}

The {output_format} is important

Still we won't go into details this time...

• And it is basically present twice (headers + extension). It has to do with two important concepts "Media types" and "representations".

So what is hypermedia?

We have seen that "REST urls are just urls" well a hypermedia API is just a REST API with links. And even more down to earth.. a REST api with elements that have a "href" can be considered hypermedia

LET'S first prove Hypermedia APIs are great!

http://almostobsolete.net/talks/hypermedia/#8

(edit: so if you weren't there, please click on the link.. see slides 8--21 then use the back button of your browser)

Interoperable presentation software!

I am using impress.js he is using reveal.js or something. I don't even need to know.

Hypermedia APIs are great because the web is

We got back to where we were. Because we had a URL! We are only doing idempotent stuff so we are at the same state.

BTW the bit of presentation you saw was by Thomas Parslow

A look at what a REST api could look like

If we have for example http://pekelman.com/time

calling http://pekelman.com/time.json

{
  "message": "This Document is http://pekelman.com/time/ and it is about what http://pekelman.com/ knows  to do with time.",
  "status": "clockrunning",
  "links": [
    {"rel": "self", "href": " http://pekelman.com/time/" },
    {"rel": "zone", "href": "zone/" },
    {"rel": "current", "href": "now/", value:"Thu Apr 18, 2013 17:34 pm "}
    {"rel": "reset", "title": "RAZ", "verb": "DELETE", "href": "."}
    ],
}

Some kung-fu here

    {"rel": "current", "href": "now/", value:"Thu Apr 18, 2013 17:34 pm "}

Remember the part about making the simple use-cases accessible..

    {"rel": "reset", "title": "RAZ", "verb": "DELETE", "href": "."}

Principle of least suprise anyone ?

Probably this is better

    {"rel": "reset", "title": "Reset server time", "verb": "POST", "href": "."}

Principle of least suprise anyone

Pure Hypemedia!

Well that simply doesn't make any sense does it? A pure Hypermedia API is like a "pure" REST api. We don't want to be pure we want to be simple, general, abstract and prgamatic! Still, if all the methods of your api are discoverable through the api. If you replace internal opaque ids by links. If for chaining methods all you need is the first response well, your Hypermedia is damn pure.

Ok some use cases...?

• Collection/Item
• Pagination
• Search / Facetted Search
• Rights
• Future resistant versionning !

Discussion and analysis of navitia.io

Thank you