Re:Microsoft REST API Guidelines
by travisjungroth on Friday November 22, 2019 @08:34PM
(#21611829)
“SDK” is a much less useful hard boundary than “Web API” for where I stop providing service. Should I provide an SDK in every language a client might use? If they want to access my service in a language I don’t support, should I tell them to piss off? I could offer for them to just hit the API themselves, but then we’re back where we started.
On the other hand, if I offer a web service and some someone asks “but what if I can’t make HTTP requests?” I’m _perfectly_ happy to tell them to piss off.
Re:Microsoft REST API Guidelines
by journalctl on Friday November 22, 2019 @10:06PM
(#21612178)
That’s what Evernote did: binary protocol and implementations in a bunch of languages. Their API was apparently easier to develop this way.
Re:Microsoft REST API Guidelines
by kevin_thibedeau on Friday November 22, 2019 @04:54PM
(#21610520)
A human should know because it affects user agent behavior. Over use of POST where it is not needed causes pointless friction with confirmation dialogs that could be avoided with PUT.
I feel like, if we're not writing data-interfacing applications with PUT and POST as specifically different actions in mind, we're doing something wrong.
People think in ambiguity; adding a new item or replacing an existing item, as in this example, shouldn't be something an application needs to guess at.
How could someone use an API correctly without understanding it?
The client SDK exposes just the actual API and not the web API which is typically much more complex.
I really don’t want to worry about setting http headers to make an add-if-not-exists call for example. The API in a client library with a method “TryAdd(...)” is understandable as an API, and the setting of headers and 4XX code you might receive on a duplicate is just returned as false.
People have being using banks for centuries.
POST /my-account/charge is not an abstraction, it's pretty much exactly what people do and have done.
When this happens, it’s usually meant as a RPC endpoint, yes. However, it can be an abstraction, especially if you call it “POST /my-account/charges”, in plural form: you’re sending a new object to the “charges” resource (this architectural technique is usually called reification)
EDIT: Since I didn't make my case well enough, here's an example. Let's say you want to charge a credit card. Are you doing a `POST /charge`? Or would it be better to say `card.charge(500)`? My point isn't that there shouldn't be a proper REST API below it, but rather that we should offer abstractions so normal semi-technical people can use APIs and don't have to think too much like a computer.