5 ms·

I agree REST APIs should be built this way, however I disagree any end user should ever have to think about APIs this way. I think a good SDK should hide most o

I agree REST APIs should be built this way, however I disagree any end user should ever have to think about APIs this way. I think a good SDK should hide most of this complexity away, and no real human should ever have to know the difference between a PUT or a POST. APIs should think more like people; people shouldn't have to think more like APIs. 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.

mattlutze 7y ago
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.
jmull 7y ago
How could someone use an API correctly without understanding it?
- alkonaut 7y ago
  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.
kevin_thibedeau 7y ago
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.
travisjungroth 7y ago
“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.
- journalctl 7y ago
  That’s what Evernote did: binary protocol and implementations in a bunch of languages. Their API was apparently easier to develop this way.
rswail 7y ago
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.
- ralmeida 7y ago
  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)

mattlutze 7y ago

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.

jmull 7y ago

How could someone use an API correctly without understanding it?

alkonaut 7y ago
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.

kevin_thibedeau 7y ago

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.

travisjungroth 7y ago

“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.

journalctl 7y ago
That’s what Evernote did: binary protocol and implementations in a bunch of languages. Their API was apparently easier to develop this way.

rswail 7y ago

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.

ralmeida 7y ago
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)