No, no, no. I disagree strongly that APIs should be vague about what they provide.<p>An API designer who deliberately leaves out documentation of important features (like pagination, sorting, etc), and fails to specify the format of what comes back any further than "this will be what you intended", hasn't designed an API at all.<p>APIs are well-defined interfaces that other programmers can rely on. If there is no well-specified contract, there is no API.<p>Defining such an interface so that it's reasonably future-proof? Yup, that's hard. And you're not an API designer until you take on that challenge. If you instead punt on all that responsibility, and provide the user few or no guarantees about how your service works, you've taken the cowardly way out.<p>The essence of software architecture is isolating and tackling complexity. Isolate it in the API, don't push it out to every one of your users.<p>I don't argue that an API needs to specify <i>absolutely everything</i> about its operation, but obscuring and removing features from an API without changing the version number is foul play. That is fragility.
The author is basically advocating moving application logic inside of the API. This is counter to the entire purpose of an API.<p>Moving application logic inside the API will indeed protect you from having problems where the API changes in ways that make it incompatible with the Application, but that's because the API is now part of your Application and you're just going to solve those same issues within the API.<p>An API which provides every relevant data field is not "a programmer's API", it's an actual API.
The recommendations of this document are definitely at odds with the design of the API my team is currently working on.<p>We are trying to build a data access API that can provide a functional and flexible view into data where we know some of the requirements and expectations of the initial users, but we don't know how it will be extended and transformed in the future.<p>If we don't provide things such as customization of the returned fields, desired date ranges, and ordering, then I believe we would have to rely on waiting for feedback from users/devs that we did not satisfy and attempt to build new end-points to correct that deficiency. That seems to be almost guaranteed to get us off to the wrong start for a large portion of users and they might just decide it isn't worth asking us to make changes since we didn't appear to be catering to them in the first place. I understand that we can't meet all the unknown needs, but if we can build features into the API to meet general classes of needs, that seems better than ignoring them until the specifics become known and then supplying further endpoints that answer only those specifics.<p>How would you extend this philosophy to a large data portal such as data.gov?<p>Even in the FBI example, if there is no extensibility or transform-ability in the API, how are the unmet needs of users handled? Do you have a system that gathers complaints from users about the data they suspect is possible but not available and then build new endpoints for each distinct need? Do you just ignore the potential transformative uses that aren't directly applicable to the needs of the customers to which you are paying attention?
I'm not sure this works once other people start building on top of your API though. I would rather bump the API version than break API compatibility by adding/removing/renaming fields.<p>Github (which you used in your example of good design) do change fields returned in their API responses but only between API version not inside of versions. The link you gave [1] is to Version 3 of their API which is different to Version 2 and will be different to Version 4. I don't really want to be programming against APIs where identical requests can return varying responses based on supposed intent.<p>1. <a href="http://developer.github.com/v3/repos/statuses/" rel="nofollow">http://developer.github.com/v3/repos/statuses/</a>
Artificially constrained APIs are annoying as hell. It's maddening when you want to build something that doesn't fit the scenarios the API builder had in mind, and you know the data is just below the surface, but you can't because the builder didn't expose it.<p>It's great to include simplified APIs like "/wanted/most" but I also want the more powerful version.
Intent-driven API gels with a talk from Netflix that came out just a few days ago:
<a href="http://www.infoq.com/presentations/API-Revolution" rel="nofollow">http://www.infoq.com/presentations/API-Revolution</a><p>His argument is that we're in the middle of a switch from RESTful resource-oriented APIs to what he calls "Experience-Driven APIs". He explains how Netflix has made this shift with its PS3 app. They effectively introduced a new facade layer inside the server and that's what the PS3 talks to.<p>The main thing about this talk is that this whole question constantly repeats itself with the pendulum swinging back and forth. There's really no right answer and it depends a lot on the reason for providing the API in the first place.<p>And that gets back to another reason we are probably seeing the trend, which is that companies like Twitter are becoming more protective of their APIs. While the OP is mostly arguing this from the perspective of technical efficiency, this commercial argument could sway companies even further towards intent-driven APIs.<p>I imagine we will end up in a dichotomy, where companies who provide their own UI and services will typically support intent-style APIs, while companies who specifically have a business model of charging for their API will continue to offer the more precise resource-style API.
TL;DR If you remove features from an API then there will be less to break.<p>But the article just assumes that those features you removed weren't needed. Seems a bit dubious to me.
How is the simpler API more "fragile"? It may lack some virtues (e.g. a paging interface) but how could it be more robust?<p>Also note that it exemplifies many of the virtues cited (ease of pre-generation, ease of caching, etc.) over the more complex option. Indeed, I'd suggest many API designers would prefer to offload busywork such as sorting to the client for anything other than very large datasets (you four core 3.2GHz CPU (a) is running idle, and (b) costs me, the API designer, nothing).<p>Consider that the simpler API is:
a) simpler to document
b) simpler to implement
c) simpler to consume
d) scales better<p>Note that every time the user changes sort order the complex API gets hit. The simpler API is out getting coffee and scoring with the sexy APIs from across the street.<p>How is it worse?
I agree webapis need to be less fragile but I definitely would n't advocate following this approach. To be honest I'm actually surprised how well the original followed good REST principles. Hateoas is a good way to make your api less fragile to change btw.
I don't think you are making a convincing argument for your point.
Most likely it will be a developer interpreting the api and generally speaking they are likely to want some flexibility in how you query a resource.<p>I would say your proposed suggestion is much more limiting, you have basically removed the query string and changed the name.<p>So your proposed version returns all the data, in most notorious order, that could be tonne of data. You are going to need query strings for paging and filtering and sorting..this is perfectly good api design.<p>I would recommend odata.org for a read.
I would also recommend apigee.com white paper on good api design.<p>Also with versioning in mind, you may wish too include api/v1.x/mostwanted
well, vague on details is a bit tricky - what happens when the data set becomes huge and they need to include pagenation? sometimes the intent-based api will start to include payloads in the body of the request to specify things like page number etc. Is this less fragile? Or have we just moved the complexity into a different place?