In my last blog I argued that API protocols can and should be based on the best choice for their purpose and audience, not all APIs are based on REST. Importantly the choice of protocol also implies a choice of fundamental API design abstraction. Or at least that is the intent. In practice though, I still see API examples where part of the interface has been defined as follows:

POST create_customer

This example in reality mixes abstractions from the world of REST (the POST verb) and the world of SOAP (the create_customer method name). To me this shows that API designers often (inappropriately) think in terms of abstractions that they know even when seemingly changing to a different protocol, in the example changing from SOAP to REST.

Entire books have been written about technical API design, providing a level of detail way beyond what this blog can offer. Yet it would seem that understanding in simple terms the fundamental difference in abstraction for each API protocol is even more important than knowing about the technical details. So, let’s consider the create customer example again from that perspective – trying not to be correct in the detailed syntax, but rather calling out the very different conceptual representation of the same single function.

SOAP interfaces are method-based. The most important aspects of the interface design are the set of supported methods and the data structures of each method. The create customer example would look like create_customer (payload). Indeed this is the type of abstraction that the API designer had in mind for my original example. Were you to create an interface to retrieve a customer record, this would look like get_customer (customer-id).

REST interfaces are resource-based. The most important aspect of the interface design is the URI structure that allows a consumer to navigate the object graph embodied by the API. Using a REST approach, the create customer example would look like POST /customers (payload). Here customers is an object collection, part of the URI structure, and the action taken on the collection is implied by the REST verb. Were you to create an interface to retrieve a customer record, this would look like GET /customers/{customer-id} with customer-id now representing a particular member of the customers collection.

MQTT interfaces are generally event-based. The most important aspects of the interface design are the set of events (emitted or received) and the associated event messages. MQTT is not as natural a protocol choice for my customer example, but were you to do it anyway, creating a customer would look something like EMIT create-customer (message) with the expectation that there is a later associated RECEIVE create-customer (message) BY create-customer-runtime-object. In an event based environment the emitter and receiver actually do not know (or talk to) each other. As I said, not as natural as the other two, but still illustrative of the difference 🙂

By deliberately removing the distraction of detailed syntax, using pseudo script instead, I have hopefully highlighted why and how the basic conceptual constructs of SOAP, REST and MQTT interfaces are fundamentally different. Your choice of protocol has implications for what a well-designed interface must look like, so take that into account when choosing the protocol in the first place

Connect with me on @ClausTorpJensen or read my earlier blogs. You can also subscribe to the blog list here

5 comments on"The basics of good API design"

  1. […] SOAP, you should find out the golden mean. One more point of view on this subject is presented in The basics of good API design, written by Claus T […]

  2. Claus, Like your other blog posts in API space, This one is also very informative and useful. We should really consider this which designing an API. After all, API’s are the face of an organization. 🙂

  3. ClausTJensen January 26, 2015

    Thanks. And yes, we absolutely should ! 🙂

  4. Frank Lino March 02, 2015

    great post. curious, what are your thoughts on leaking api version knowledge into the uri construct? to build on your prior example, post /customers/1.0(payload)

    soap is strong here with explicit namespace declarations in the descriptor while rest leaves this wide open.

Join The Discussion

Your email address will not be published. Required fields are marked *