Following real-time API design

Originally published on DZone, 7th July, 2012, by Mark O’Neill, CTO – Vordel

Following real-time API design

It’s fascinating this morning to read Steve Chamber’s real-time notes on the design of his API. In particular, I was interested in the section on which authentication model to use. It’s such a common question: which authentication scheme to use for APIs. Unfortunately, all too often, the answer has been to throw some standards at the problem, without really thinking about whether they make sense. This always reminds me of the world of SOAP Web Services, five years ago, when seemingly everyone wanted to use SAML for authentication of SOAP, when in actual fact SAML is not used to do direct authentication at all. SAML was just the cool technology du jour.

What Steve Chambers has done is to list out the options for API authentication and settled on (my emphasis added) Token Keys with Request Signing.

Authentication

  • HTTP Basic Authentication is ruled out (why: SSL, Logout, Client retains auth info)
  • HTTP Digest Authentication is ruled out (why: SSL)
  • Public Key Authentication is ruled out (why: complexity)
  • Credentials in Request is ruled out (why: creeds should not be passed in each Request)
  • Token Keys with Request Signing (of all headers and payload for zero collisions) are selected. 

http://viewyonder.com/apis/team-api-development/

When I saw this I thought “Yes!”. That’s because I remember a similar exercise two years ago which also ended in Token Keys (called API Keys in that case) being selected. In that case also, a facade pattern (using a Gateway) was employed in order to separate the API delivery and definition from the back-end infrastructure. It’s interesting that in that case we also allowed SSL with HTTP Digest Auth for (as Steve calls them) “pesky humans with a browser” but the Gateway takes note of how the authentication is performed and that is taken into account in policies (the “authentication context”).

The other aspect I enjoyed reading about is the REST design constraint. Steve writes:

This API is resource-based, not service-based, as per the REST design constraint.

Again I thought “Yes!” because this goes back to one of my original bugbears about (firstly) heavyweight Web Services and (now) APIs. Back in the world of Web Services, initially it was seen as part of Distributed Computing and it was all about RPC. Then, Document-Literal SOAP was rightly seen as the best option, and we moved to to that model. That was a good thing. It made overlaying REST on SOAP a bit easier.

Even further back, at the risk of seeming like an old codger, this always reminds me of my early days working as a programmer for an EDI VAN in Dublin moving EDI processes to the new-fangled Internet. EDI was (and is) all about moving documents (resources) around, and updating the status of those resources (purchase orders are approved, etc). At the time in Dublin, it seemed like every other programmer was working in distributed computing (CORBA) at Iona (which I initially encountered as a campus company). That is a different world. It’s the difference between doing a POST (aargh) on a method called “approve_purchase_order()” and using PUT to update the status of the purchase order resource. Much of REST is centered on the old ideas which worked, and still work, for EDI. There, I sound like an old codger now.

I’ll be following Steve’s notes with interest…