Your browser doesn't support the features required by impress.js, so you are presented with a simplified version of this presentation.

For the best experience please use the latest Chrome, Safari or Firefox browser.

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.

constellationmatrix

What is an API?

Application programming interface

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

What makes a good API?

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

What makes a good API?

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

What makes a good API?

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

What makes a good API?

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

What makes a good API?

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

What makes a good API?

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

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

Software deals with entities that have data

api

In RESTspeak we call these entities "resources"

api

An API will exposes methods to read and write data

Writing data can be expressed as a state transition

api

So... Whats is a resource?

api

How do REST urls look like?

api

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 api

But they usually look like:

or

or something like

The {output_format} is important

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

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 api

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)

api

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

api

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

api

    {"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

api

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

Principle of least suprise anyone

Pure Hypemedia!

api

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...?

Discussion and analysis of navitia.io

Thank you