71–80 of 94 posts
It's a shame there isn't some simple standard (de-facto or otherwise) way of documenting REST APIs such that an idiomatic client library for each language could be generated automatically. The OPTIONS method is a really underused part of HTTP and would be great for this purpose: http://zacstewart.com/2012/04/14/http-options-method.html
Earlier quoted context omitted.
>It's a pattern that comes with a lot of really useful benefits. Sure, but people can implement that pattern without buying into the whole clumsy REST edifice. For example, a strict reading of REST (and RESTers support such readings!) would tell me that if I have an API that takes two cities and returns the distance between them, then I must expose a URI pointing to every combination of cities . See here: http://roy.…
Not true. GET /distance?cities=San+Francisco,Los+Angeles would suffice. city1=modesto&city2=fresno might be preferred if you wanted to support form submissions, too. Query strings are perfectly restful.
I agree that it's much more convenient to have well-defined fill-in-the-blank. I disagree that it matches the requirements of REST, whose proponents always tell me "If you document the URIs or how to build them, you're doing it wrong."
http://stackoverflow.com/questions/1164154/is-that-rest-api-...
Braintree have made an interesting choice in keeping their REST API private and requiring customers use their client libraries. I think they could both have client libraries that they promote as well as a public REST API. Breaking down their reasons: Security - agree with them on this, the more they can help their users make their systems secure the better. Not sure if it should preclude a public REST API but certain…
I'm a developer at Braintree. The challenge with maintaining backwards compatibility on the server side is handling the wide variety of possible inputs into the system. It's hard to write tests that account for all of them. I've seen a couple of cases where backwards compatibility can be broken in unexpected ways. For one application that we built at Braintree, we had a client that was sending us an application/x-www…
That said, these are some of the things that I've done to help with backwards compatibility through only the serverside API:
* Track production requests and use them as test cases
* Build a large suite of test cases against the API
* Build the API in a statically typed language (yeah, I know, contentious, I love Rails but there's something about an externally facing API that makes me want to use a statically typed language).
* And then the ultimate -- build the API as an app that talks back to the business logic... essentially, it's your 'client library' but deployed on the server between the actual code and the client. Then, never change the part of it that faces the client, only the mappings on the the real business logic.
Earlier quoted context omitted.
The thesis lays out in detail what REST provides: "REST provides a set of architectural constraints that, when applied as a whole, emphasizes scalability of component interactions, generality of interfaces, independent deployment of components, and intermediary components to reduce interaction latency, enforce security, and encapsulate legacy systems." The existence of these properties should be fairly evident when y…
That tagline may explain the benefits of REST, but it doesn't really explain at all which problems REST is well-suited for and which not. I've found that REST design is great for problems where the most visible abstraction is a document or an object (with operations or functions as secondary). It doesn't really fit problems where the most common abstraction is a function call (with the arguments a secondary concern).
You're talking about wire formats and structures that feel natural to use for particular kinds of calculations. I'm talking about recognizing properties that we might need a particular system to have (ease of use being only one of them), and ensuring them.
The line I quoted tells us exactly which problems (in the sense that I'm talking about) REST is suited for: the ones where those benefits are needed (and where the tradeoffs aren't to costly).
Earlier quoted context omitted.
Not true. GET /distance?cities=San+Francisco,Los+Angeles would suffice. city1=modesto&city2=fresno might be preferred if you wanted to support form submissions, too. Query strings are perfectly restful.
That just shows it's HTTPful, not RESTful. In this case, that protocol involves being told how to construct a URI rather than it being presented from a menu of choices discovered by following URIs in the API. I agree that it's much more convenient to have well-defined fill-in-the-blank. I disagree that it matches the requirements of REST, whose proponents always tell me "If you document the URIs or how to build them,…
The crucial thing that you're missing is that it's being told how to construct that URI in-band. Not in a piece of documentation that has to be hard-coded into the client.
It's a shame there isn't some simple standard (de-facto or otherwise) way of documenting REST APIs such that an idiomatic client library for each language could be generated automatically. The OPTIONS method is a really underused part of HTTP and would be great for this purpose: http://zacstewart.com/2012/04/14/http-options-method.html
Yes, there should be a WSDL for REST APIs.
We (Zapier) are in a particularly good place to comment on this. We have implemented about 70 very diverse web APIs in-house. Early on, we used client libraries because they were easy and convenient. That decision bit us, hard. (Most) client libraries are un-maintained, opaque, and difficult to extend. We spent many months ripping every client library out down to the raw requests. We are in a unique position because…
Is there a good book/resource on learning REST API ideas? I'm looking for a beginner's resource for someone who doesn't really grok the ideas behind REST and the motivation for REST. But also something that gets technical very quickly - I've been programming for long enough that I pick ideas up very quickly.
The biggest question I wish the various tutorials would address is: why is REST a good idea? Why is this particular way of doing things better than others?
And here's one thing I believe is true, that I have literally never seen in a REST tutorial: sometimes REST is not the best way to go. Sometimes an RPC architecture is better.
Earlier quoted context omitted.
Not true. GET /distance?cities=San+Francisco,Los+Angeles would suffice. city1=modesto&city2=fresno might be preferred if you wanted to support form submissions, too. Query strings are perfectly restful.
That just shows it's HTTPful, not RESTful. In this case, that protocol involves being told how to construct a URI rather than it being presented from a menu of choices discovered by following URIs in the API. I agree that it's much more convenient to have well-defined fill-in-the-blank. I disagree that it matches the requirements of REST, whose proponents always tell me "If you document the URIs or how to build them,…
We (Zapier) are in a particularly good place to comment on this. We have implemented about 70 very diverse web APIs in-house. Early on, we used client libraries because they were easy and convenient. That decision bit us, hard. (Most) client libraries are un-maintained, opaque, and difficult to extend. We spent many months ripping every client library out down to the raw requests. We are in a unique position because…
Is there a good book/resource on learning REST API ideas? I'm looking for a beginner's resource for someone who doesn't really grok the ideas behind REST and the motivation for REST. But also something that gets technical very quickly - I've been programming for long enough that I pick ideas up very quickly.
It's amazing, really. It's not just a recipies list, it explains a lot of very important REST cases, and also when to use or not to use REST.