4 ms·

The Problem With APIs and a Possible Solution

19 points by ashastry 14y ago

mohamedattahri 14y ago
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 14y ago
  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 14y ago
    > 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 14y ago
      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?
      - willismichael 14y ago
        I recently worked on some client code that interacts with the ReviewBoard API: http://www.reviewboard.org/docs/manual/1.6/webapi/ 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.
  - jasonkostempski 14y ago
    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 :)
  - mohamedattahri 14y ago
    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.
- nkohari 14y ago
  This is the reason I've stopped calling APIs "RESTful". Everyone has a different opinion on where in the "REST spectrum" a given API falls, and in the end, very little of what you described actually impacts whether an API is usable or not.
  - pfraze 14y ago
    I know what you mean, but I really don't want to call REST correctness a matter of opinion. The examples he just gave are well-established.
  - mohamedattahri 14y ago
    The thing is it's not a standard. It's a set of protocols and good practices. That's what makes it really difficult to limit in space. But it's easy to know you're not going in the right direction when a choice of yours contradicts or duplicates something clearly mentioned in the specifications of one of these protocols. For example, the ".json" suffix to URLs is a convention is Rails. How can a language/framework-agnostic API borrow conventions from a framework? It's not about usability. It's about consistency which will impact developers perception of simplicity. They'll just have less work to do before they can actually get started using it.
daralthus 14y ago
Does somebody know a good resource about sandboxing and running foreign code safely?
- prateekdayal 14y ago
  Here is one such Gem - https://github.com/c42/secure https://github.com/c42/secure
mercurial 14y ago
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 14y ago
  One issue is that many services deprecate API endpoints over time. For example - https://github.com/blog/1160-github-api-v2-end-of-life https://github.com/blog/1160-github-api-v2-end-of-life
  - mercurial 14y ago
    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 14y ago
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/ http://pipes.yahoo.com/pipes/

19 points by ashastry 14y ago

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 14y ago
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 14y ago
  > 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 14y ago
    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?
    - willismichael 14y ago
      I recently worked on some client code that interacts with the ReviewBoard API: http://www.reviewboard.org/docs/manual/1.6/webapi/ 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.
- jasonkostempski 14y ago
  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 :)
- mohamedattahri 14y ago
  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.
nkohari 14y ago
This is the reason I've stopped calling APIs "RESTful". Everyone has a different opinion on where in the "REST spectrum" a given API falls, and in the end, very little of what you described actually impacts whether an API is usable or not.
- pfraze 14y ago
  I know what you mean, but I really don't want to call REST correctness a matter of opinion. The examples he just gave are well-established.
- mohamedattahri 14y ago
  The thing is it's not a standard. It's a set of protocols and good practices. That's what makes it really difficult to limit in space. But it's easy to know you're not going in the right direction when a choice of yours contradicts or duplicates something clearly mentioned in the specifications of one of these protocols. For example, the ".json" suffix to URLs is a convention is Rails. How can a language/framework-agnostic API borrow conventions from a framework? It's not about usability. It's about consistency which will impact developers perception of simplicity. They'll just have less work to do before they can actually get started using it.

daralthus 14y ago

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

prateekdayal 14y ago
Here is one such Gem - https://github.com/c42/secure https://github.com/c42/secure

mercurial 14y ago

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 14y ago
One issue is that many services deprecate API endpoints over time. For example - https://github.com/blog/1160-github-api-v2-end-of-life https://github.com/blog/1160-github-api-v2-end-of-life
- mercurial 14y ago
  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 14y ago

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/ http://pipes.yahoo.com/pipes/