undefined | Better HN

0 pointsRyanMcGreal13y ago0 comments

> I agree. However at this point it just seems a lot more work

It's a lot more work for the end user to have to assemble URLs themselves instead of you providing them in the response.

Let's say someone does a GET request on /tickets. The response should include URLs for each ticket that gets returned, e.g. something like:

    {
        "tickets": [
            {
                "ticket_id": 1337,
                "url": "/tickets/1337"
            },
            {
                "ticket_id": 1336,
                "url": "/tickets/1336"
            }
        ]
    }

Again, the analogy of the WWW itself is instructive. When you browse to the home page of a website, that page has links to the other pages on the site.

Similarly, the home page of a REST web service should have links to the other resources on the web service, e.g.

    {
        "resources": [
            {
                "resource_name": "Foos",
                "url": "/foos"
            },
            {
                "resource_name": "Bars",
                "url": "/bars"
            },
            {
                "resource_name": "Tickets",
                "url": "/tickets"
            }            
        ]
    }

That is simple, predictable, discoverable and self documenting for the end user.

{ "tickets": [ { "ticket_id": 1337, "url": "/tickets/1337" }, { "ticket_id": 1336, "url": "/tickets/1336" } ] }

{ "resources": [ { "resource_name": "Foos", "url": "/foos" }, { "resource_name": "Bars", "url": "/bars" }, { "resource_name": "Tickets", "url": "/tickets" } ] }

0 comments

3 comments · 1 top-level

andyjohnson013y ago· 2 in thread

Thank you for explaining this simply and concisely. I was aware of "Hypermedia as the Engine of Application State", but I'm not sure I fully understood it until now.

A question about resource discovery using links. In practice, does anyone write web service clients that use, and are driven by, link discovery? It seems to me that in a b2b scenario, an organisation that is going to be investing time and money in developing a client for an api will probably want some documentation to work against.

Also, is there a standard way to make discoverable the http methods that can be applied to a resource?

loungin13y ago

> Also, is there a standard way to make discoverable the http methods that can be applied to a resource?

HTTP OPTIONS method is exactly that. Mind your response headers, they can convey plenty of information about your resources: allowable methods, request and response types mime-types (you can rank type preference as well).

> In practice, does anyone write web service clients that use, and are driven by, link discovery? ...

Documentation is always useful. But HTTP can almost be self documenting for well thought out and linked resources. For link discovery, maybe a standard like HAL (http://stateless.co/hal_specification.html) or similar would be of interest. There is another proposed way as well, I can't think of it at the moment but will add an edit if/when it comes to me.

EDIT: I had poor wording, there are several 'json hypermedia specifications'. Another would be (Collection+JSON http://www.amundsen.com/media-types/collection/). Hope that helps.

willismichael13y ago

I recently worked on some client code that interacts with the ReviewBoard API:

http://www.reviewboard.org/docs/manual/1.6/webapi/

I won't claim to be a REST expert by any means, but this API is one of the best examples of "Real REST" that I have worked with. Something that I found quite nice about it is that my client code didn't really have to know about URLs for the most part. If I remember right, it only had to know the URL for the root resource, after which all URLs were obtained from the previous response from the web service.

j / k navigate · click thread line to collapse