Design Your APIs with a UX Mindset

The ushering in of the app era has resulted in an increased focus on User Experience (UX) in practically every product, including those, like (say) networking products, that were traditionally considered as too technical to be simplified.  The “Consumerisation” of IT has led users, who are used to intuitive, simple and beautiful experiences in the apps that they use in their personal lives, demanding those same capabilities in their enterprise applications.  Indeed, simplicity, ease of use, supportability and manageability are increasingly being touted as competitive differentiators even for the most complex products.

UX is an area that is typically associated with the Graphical User Interfaces (GUIs) that are presented to the end user of an application.  It consists of three disciplines:

1. Information architecture: This deals with what information is presented to the user.  Information is typically composed of an aggregation of one or more data elements that represent the objects in the domain.
2. Interaction design: How objects interact with each other and how to navigate from one object to another.  In the context of a GUI, this usually translates to mouse clicks to navigate from one screen to another to accomplish a particular task; and
3. Visual Design: How elements appear visually on a GUI screen.  Usually done by a visual designer who is experienced in visual aesthetics.  It involves selection of color palettes, fonts, element spacing etc.

 

Focus on User Needs…Hide the Complexity

The key to good UX design is a deep understanding of the user persona that the application is intended for.  This includes, amongst other things, the use cases that the application is intending to address, and the skill and knowledge possessed by the user of the application.  The key to good UX is to keep the focus of the application on the user and their needs while hiding the technical complexities of the product from them.

While it is easy to understand UX in the context of a GUI, it is often ignored when the product being developed is a REST API.  The end result of this is that many REST APIs that are designed today are nothing more than object browsers delivering internal representations of the domain/business objects over HTTP/S as a transport layer.  While this may be appropriate for some use cases (e.g. using a REST API to configure a network device),  in many instances this approach makes the APIs very difficult to consume by developers intending to build applications on the programmable platform.

All too often, I see many products approaching the design of API from the perspective of the developer who creates the APIs rather than the developer who consumes it. Bringing principles of good UX design to APIs can make their consumption pleasurable to the users who they’re intended for.  To that end I will identify some guidelines for a well designed REST API. (It must be noted that visual design is typically not relevant to a REST API since REST APIs typically just present the model (data) of the server.)  These should be definitely considered as necessary but not sufficient from a design perspective.

Guidelines for a Well Designed REST API

1. An API is primarily intended to be consumed by a programmer.  In contrast to a GUI where there are a relatively smaller number of media on which the application is consumed (browser, mobile devices, or tablets) an API is consumed in many different ways each of which have widely varying characteristics.  For instance, an API can be consumed by a programmer developing applications using the API in Python, JavaScript, Typescript, Java, or Go.  Each language has its own unique needs and characteristics that must all be taken into account in designing an API (more precisely the request and response formats).
2. An API fundamentally exposes a programming model expressed in the language of REST API requests and responses that is used by developers to build applications.  As such programming constructs that all languages express must be present in the REST API programming language as well.  In particular, consistency of method names (URLs), return types (API response data types), and return formats (API response formats – json/xml, schema consistency, and scalability).
3. One of the fundamental tenets of a REST API is that the API response is supposed to capture the state of the system exposing that API.  In particular the HATEOAS (Hypermedia as the Engine of Application State) is used to express navigation from one response state to another.  The UX principles of interaction design are relevant when considering what links are exposed in the response using the HATEOAS principle.
4. An API evolves over time just like any software.  API versioning is a complex topic with many practiced solutions, each with its own pros and cons.  Versioning an API must be considered in conjunction with the client SDKs in various language bindings that make the API more easily accessible to the developer. Since clients and servers can evolve independently it is important that a well defined versioning model is used for the API in order to make the developer’s experiencing of using an API an enjoyable one.

 

Lets Make This a Conversation

As with anything in life, making things simple and easy to use by others is probably one of the most difficult outcomes to achieve, and REST APIs are no exception.  It is equal part art and science with the choices often being not so much between right and wrong as it is good versus better.   There are many considerations that go into a well designed API and I hope to share my thoughts on these topics, and hear yours, via these blogs. In the next blog, I will dive into more details on what makes for a good Developer Experience (DX) including the areas of URI and Document design, HATEOAS principles and REST API documentation.

I welcome your thoughts, feedback, criticism, agreements and disagreements on these topics. I am sure I will learn from the interactions I have with the broader community via these blogs.