Implementing HATEOAS and API Versioning via the ACCEPT header.

[briceburg]

I am becoming a quick fan of flask, sqlalchemy, and flask-restless and want to thank all those involved in this project.

As you're probably aware, the current trend in RESTful API services is the incorporation of HATEOAS [http://en.wikipedia.org/wiki/HATEOAS]. This is an important feature for machine/client consumption of resources and I believe is baked into Tastypie.

Is HATEOAS anywhere on the roadmap for flask-restless?

Another fun feature is versioning via the Accept HTTP header - (http://barelyenough.org/blog/2008/05/versioning-rest-web-services/) e.g.
Accept: application/vnd.mycompany.myapp-v2+json

Do you think API versioning is beyond the scope of flask-restless, or that the project could provide helpful boiler plate code for augmenting/modifying the response based on requested version via a callback?

Many thanks!

~ Brice

[jfinkels]

Hi Brice,

To be honest, I know barely anything about web development, I'm totally new to this. I don't really understand what HATEOAS is, maybe you can give me an example? Tastypie looks great; I'd love to see the functionality of Tastypie ported over to the Flask/SQLAlchemy. I think it shouldn't be too difficult, it just takes time.

As for responding with different types of data, I was planning on adding that (more realistically, I was hoping someone else would supply a patch). Can you create a new (separate) issue for this, if we don't have one already. See also Flask-Mimerender, which could be useful for this purpose...

[reubano]

+1 for HATEOAS support. Here's some more info on it from the Eve package

HATEOAS

Hypermedia as the Engine of Application State (HATEOAS) is enabled by default. Each GET response includes a _links section. Links provide details on their relation relative to the resource being accessed, and a title. Relations and titles can then be used by clients to dynamically updated their UI, or to navigate the API without knowing its structure beforehand. An example:

https://someapi.com/people

{
    "_links": {
        "self": {
            "href": "/people",
            "title": "people"
        },
        "parent": {
            "href": "/",
            "title": "home"
        },
        "next": {
            "href": "/people?page=2",
            "title": "next page"
        },
        "last": {
            "href": "/people?page=10",
            "title": "last page"
        }
    }
}

A GET request to the API home page (the API entry point) will be served with a list of links to accessible resources. From there, any client could navigate the API just by following the links provided with every response.

Please note that next, previous and last items will only be included when appropriate.

[reubano]

Another example

https://someapi.com/people/50acfba938345b0978fccad7

{
    "firstname": "John",
    "lastname": "Doe",
    "born": "Thu, 27 Aug 1970 14:37:13 GMT",
    "role": ["author"],
    "location": {"city": "Auburn", "address": "422 South Gay Street"},
    "_id": "50acfba938345b0978fccad7"
    "_updated": "Wed, 21 Nov 2012 16:04:56 GMT",
    "_created": "Wed, 21 Nov 2012 16:04:56 GMT",
    "_etag": "28995829ee85d69c4c18d597a0f68ae606a266cc",
    "_links": {
        "self": {"href": "/people/50acfba938345b0978fccad7", "title": "person"},
        "parent": {"href": "/", "title": "home"},
        "collection": {"href": "/people", "title": "people"}
    }
}

[jfinkels]

Thank you @reubano (and Eve) for the explanation. This is definitely a good idea.

[malamoney]

Any update on this? Using content negotiation (Accept header for versioning) is the "right" way to version a REST API...

[depado]

Any news on this ? I'd love to see HATEOAS happen 👍

[jfinkels]

Since we now implement the JSON API protocol on the master branch, Flask-Restless has links for first, last, previous, and next pages for paginated responses, where appropriate; see http://flask-restless.readthedocs.org/en/latest/fetching.html#pagination for more info. We also include self and related links.

What specific links are required before you consider HATEOAS to be implemented?