The Problem With APIs and a Possible Solution

#1

Post by ashastry » Tue, Oct 23, 2012, 10:29 AM UTC

The Problem With APIs and a Possible Solution
supportbee.com

Re: The Problem With APIs and a Possible Solution

#2

Post by mohamedattahri » Tue, Oct 23, 2012, 12:09 PM UTC

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.

Re: The Problem With APIs and a Possible Solution

#3

Post by prateekdayal » Tue, Oct 23, 2012, 12:24 PM UTC

mohamedattahri wrote: post #2

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 basi…

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.

Re: The Problem With APIs and a Possible Solution

#4

Post by daralthus » Tue, Oct 23, 2012, 12:42 PM UTC

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

Re: The Problem With APIs and a Possible Solution

#5

Post by RyanMcGreal » Tue, Oct 23, 2012, 12:42 PM UTC

prateekdayal wrote: post #3

mohamedattahri wrote: post #2

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 basi…

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 ve…

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

Re: The Problem With APIs and a Possible Solution

#6

Post by jasonkostempski » Tue, Oct 23, 2012, 12:53 PM UTC

prateekdayal wrote: post #3

mohamedattahri wrote: post #2

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 basi…

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 ve…

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 :)

Re: The Problem With APIs and a Possible Solution

#7

Post by mercurial » Tue, Oct 23, 2012, 12:56 PM UTC

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.

Re: The Problem With APIs and a Possible Solution

#8

Post by andyjohnson0 » Tue, Oct 23, 2012, 1:09 PM UTC

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/

Re: The Problem With APIs and a Possible Solution

#9

Post by prateekdayal » Tue, Oct 23, 2012, 1:14 PM UTC

mercurial wrote: post #7

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.

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

Re: The Problem With APIs and a Possible Solution

#10

Post by prateekdayal » Tue, Oct 23, 2012, 1:16 PM UTC

daralthus wrote: post #4

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

Here is one such Gem - https://github.com/c42/secure