(Yes, it can be done programmatically, but that's not always feasible/practical, especially if I want to keep certain customer accounts alive.)
Similarly, after deleting a customer, it takes you back to the customer list, but it's not always up-to-date. Sometimes the front-end can detect that updates have occurred in the list (i.e. something has been deleted) but it requires a manual refresh.
Meh. REST semantics really only works well when you're doing CRUD operations. They get clunky when something's modeled around actions rather than entities. That said, make sure their response codes and methods make sense.
If you expect that you might need to significantly change what you're doing in the future, having a more simple, composable model around resources that you can call as you need might save your ass down the line compared to if they model things as specific RPC use cases and you find yourself needing a particular variation they don't support out of the box.
Sigh, xml hard at work solving a problem we never seen, but creates such a bloted horrible mess where json would have been simple and better.
The downside is it has to be pretty complicated to enable the magic, so building it can be complicated, and debugging it is a nightmare. You could say the same about a lot of modern JS, and that's been somewhat solved by amazing tooling.
In my data oriented mind, the primary thing that matters is the data that is sent, the second is other semantics like idempotency.
Neither SOAP nor XML solve or helps: there might be no wsdl bindings in your language, or they are badly implemented (true in my experience).
XML make people nest structures where it could have been flatter, SOAP even more, and annotates everything whithout a need for that.
This cost for no reason but to entertain the CORBA like pipe dream, or should I say nightmare.
We just resorted to pulling out data from xml with xpath. And more or less template the response back, no wsdl and very simple.
But why inflict this pain on your API users?
please think through your API if you are to design an API, the tools will not think for you and you can fool yourself instead...
Swagger will not magically solve anything. I have seen and experienced that you can really create nonsensical but pretty and auto documented APIs using swagger in no time.
Network and system hiccups/outages cause non-trivial error rates with non-trivial load, so understanding how to recover from those errors is critical (to your ability to sleep through the night because your on-call pager stayed silent).
But it would still be reassuring to see this stated explicitly!
In the real world even bigger players such as AdWords would time out on our bulk requests to them if making >100M changes, without giving any errors back (the jobs just simply tend to disappear; or the jobs never get submitted in the first place).
Truth is, you may or may not be discussing the appeal of the REST; but the issue in this context is solved already - and it’s only a matter of professionalism and therefore, the resources required to build something that just works.
But in the real world we get stoned students writing the majority of the APIs; having read a few how-to’s.
There are (at least) three senses of "REST" in use in the development world, and none of them are important in an API.
The first is the original definition, laid out in Fielding's thesis. (Normally I call this "the correct definition".) This includes requiring HATEOS, which is far from a necessary property in a good API, and arguably a bad feature because it increases payload sizes.
The next is the definition popularized by Rails [1]. This is never precisely outlined anywhere as far as I know, but most people seem to think it requires using URLs with particular patterns (to see an example, just do `rake routes` on any Rails project that doesn't use weird custom routing in routes.rb). Also most people seem to think it requires using PUT for overwriting updates and DELETE for deletions. All of these conventions are not-bad. But they're also not particularly good; they amount to a variable naming convention that happens to be pretty reasonable. Other systems of organization are also perfectly good! But anyway, this is not an important feature in an API.
The third definition you'll see sometimes is "our API uses HTTP, therefore it's REST, we're buzzword-compliant". Fuck your buzzword compliance, no that doesn't make your API RESTful. And in some cases, these bozos can't even use HTTP correctly (for example using GETs for side-effect-ful requests). This is pretty much indefensible, but it'll still happen. So if you DO care about one of the first two definitions, don't take it on faith that someone who says "our API is RESTful" knows what that even means.
Also, the first two definitions both work in terms of "representations of resources", and all three of the above apply to HTTP [2]. It's not at all clear that either of these are good features in an API. They both have the advantage that they make implementation more predictable, so that's often (usually? almost always?) a great idea. Yay! But resource-representation is a bit bloaty, and so is HTTP, so for some situations, it's more appropriate to discard either or both of those design parameters. For example, suppose you're monitoring some terrifyingly dense IoT deployment, and you want your swarm of sensors to send updates ten times a second. Differential updates over Apache Thrift (or over Google Protobuff) is certainly not over HTTP, and you have to squint pretty hard to to see the differentials as resources. (Mind you, you'd probably also want to send some checkpoints less-frequently, and you could characterize these as resources without too much difficulty.)
In summary: REST means different things to different people, and there's a lot of good sense in those communities (I mean, not the third-listed liars, but the other two). BUT, probably you don't actually care about RESTfulness per se, in that cute conventional URI/path patterns are unimportant, and HATEOS is somewhere between nice-to-have and undesirable.
HTH
Footnote 1: I'm not claiming that authors of Rails (DHH et al) were confused about the definition of REST. As far as I can tell, when they said "make your routes RESTful", they weren't claiming that doing so necessitated using their cute method/URI convention, they were simply claiming that doing so was compatible, and that following some convention is a good idea, and here's a good convention. Yay! Well said! Unfortunately most people who wrote simplifying articles on the subject got it wrong, so now we have an industry full of semi-literates quoting non-existent scripture.
Footnote 2: Strictly speaking Fielding's thesis is about what he thinks HTTP did well, and is intended to be largely advice to designers of future protocols intended to compete with HTTP. That's why so much of the "architectural style" is about stuff that's built into HTTP, such that the designer of an HTTP API cannot fuck it up. API authors are not the primary intended audience of the thesis!
1. Do they provide an easy way to create a sandbox/staging/test/dev environment ? Good example: Stripe. Really bad example: Paypal. Why ? Well, for starters, you need to create a completely separate account just to get a sandbox env in paypal. Then there is no guarantee that sandbox is identical to production in terms of ability to build and test.
2. What are their Rate Limits ? Some APIs are well designed but have terrible rate limits.
3. Authentication mechanism and security. How do they authenticate the API access ? This can matter for building critical apps.
4. Do they use REST or not ?
5. Do they have good documentation ? Can you do a quick test using their documentation or is it required to call their support ?
6. Do they have good support ?
7. Do they version their API changes and are those changes backward compatible ?
I am sure there are more but these are some good ones to start with.