

The Problem With APIs and a Possible Solution - ashastry
https://supportbee.com/devblog/2012/10/23/app-platforms-and-not-apis/

======
mohamedattahri
I'm sorry but your API is not what I would call RESTful nor a step in the
right direction. I have spotted 3 issues after only 30 seconds on your doc:

1) HTTP features the "Accept" header which allows the user-agent to specify
the format of the response. The "*.json" thing is not standard and breaks
HTTP.

2) "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.

3) A RESTful API needs hyperlinks. Resources must point to each other to help
the developer navigate the API tree and access every single point it contains.
The API origin (company.supportbee.com) should be the only information I need
to discover the structure of your API.

The WWW is an example to follow. It's the most RESTful "service" out there.

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

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

~~~
andyjohnson0
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?

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

------
mercurial
I think it's worthwhile pointing out that the article specifically deals with
web APIs.

Regarding the content, I'm puzzled as to why versioning a web API should be a
hard problem when you can just include the version number in the URL. Sure,
you need to maintain this code path forever afterwards, but that's true of any
platform with ambitions of backward compatibility.

~~~
prateekdayal
One issue is that many services deprecate API endpoints over time. For example
- <https://github.com/blog/1160-github-api-v2-end-of-life>

~~~
mercurial
Like I was saying, it depends on how much backward-compatible your vendor
wants to be. I just don't see how a hosted app is going to protect you from
this kind of thing. The only difference is that the hosted app is presented
with a "native" API as opposed to an RPC API, but it's just as vulnerable to
deprecation, and will remain so as long as you are a third-party.

Except that the cost in term of infrastructure and ongoing maintenance (code
review, etc) is higher, which IMHO makes it likely to be phased out sooner
than a web API.

------
andyjohnson0
Having read the article, I'm still not really sure what a 'Hosted App
Platforms' _actually_ is, or how it solves the problems listed.

I wonder if a better solution is something like Yahoo Pipes [1].

[1] <http://pipes.yahoo.com/pipes/>

------
daralthus
Does somebody know a good resource about sandboxing and running foreign code
safely?

~~~
prateekdayal
Here is one such Gem - <https://github.com/c42/secure>

