Hacker News Reader

Comment by prateekdayal | Hacker News Reader

Thanks for your feedback. A Few questions/comments.

> The "*.json" thing is not standard and breaks HTTP. It's more of a Rails convention and so we just followed it in the docs. Everything works fine without .json using the HTTP Accept header.

> "tickets/search" endpoint is not a resource. It's a different projection of the "tickets" collection. It's basic filtering. Rule of thumb is whenever you're about to use a verb to name an API endpoint, you can guess you're probably about to do something wrong.

Interesting. How would you approach it? Extend the /tickets endpoint to include some search parameters?

> A RESTful API needs hyperlinks.

I agree. However at this point it just seems a lot more work and also I have never really seen anyone use it (except for a few often quoted examples). We should change our documentation to use the word RESTlike.

Thanks once again for your feedback. We will improve the documentation soon.

View on HN

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

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?

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.

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

I'm not a REST expert by any means. I'm sharing my experience as someone who designed and consumed several REST APIs over the past 4 years.

> Interesting. How would you approach it? Extend the /tickets endpoint to include some search parameters?

Exactly. I would do something like /tickets?q=somefilter.

As for the rest, I have nothing to add to the previous reply.

Just call it an API or Service, prefix 'Web' if necessary, then you can implement it however you see fit and no one will complain :)

Reply on news.ycombinator.com