UX for APIs

It is common knowledge that user experience (UX) is a core aspect of contemporary product design. This is particularly true of software applications geared for the customers that use them. However, it is not a common practice when developing technology products that are NOT oriented around end-users. Specifically, I am referring to application programmer interfaces (APIs).

In my prior life as a developer, I did much coding for my products to interact with a well known social media website. These coding efforts were usually more involved than I would have liked because the UX of its API by its developers was not well thought out. Many times I tested calls to the API that hung perpetually, returning neither the desired information nor an error code explaining what the issue was so that I could work around it. This usually turned my development experience into a rather horrendous one as it left me in the dark as to whether the issue was with the parameters that I was testing or an issue in the API. In addition to that, they occasionally deployed changes to the API with no warning. My code using that call would break, leaving me to sort out the issue from scratch.

Good UX entails the experience being a delightful one. In this case, it comes down to it being effortless to accomplish one’s objectives. In my case, I wanted to deduce what the errors were in the calls that I was testing quickly, easily, and reliably. This was for setting up contingency functionality if a parameter was malformed for the first attempt at the call. After that, I wanted error codes explaining how the system was responding to my calls when the parameters were valid but the system still couldn’t return the desired result. On top of this, I would have preferred some advance notice before a change was deployed in the API.

I would like to see UX design for APIs considered as a standard practice for them. The following is an outline of what I consider to be key components of good UX for an API.

  1. SDK – There should be a clear and well written SDK for API developers to reference as they need to. It could be included on the API provider’s website and/or returned by a stock API call. It should be kept up to date, which I don’t see as requiring much effort.

  2. Sufficient notice for changes – Clients subscribing to APIs will need ample time to prepare for them. This could include deciding how to use them. This would entail messaging geared towards the developers who integrate them into their IT systems, as well as the executives who benefit from the data provided by the services and pay for them. It would not work for either group if the API development group deployed them willy-nilly.

  3. Timely error codes – whenever an API call does anything other than what the developer wants it to, it should return a timely error code that clearly explains what went wrong. This is necessary for determining which contingency functionality to run. (Plan B.) A clear delineation of error codes should be part of the SDK for that API.

    For each API call made, the requesting functionality should receive either the data that it wants or a code indicating the reason why not.

  4. Parameter validation – The first step the API should execute after receiving a call is to validate the parameters that it receives. If any of them is invalid, incomplete, or improperly formatted, it should return an error code explaining that. This would be useful if the parameters are generated programmatically dynamically and pull bad data from a database.

  5. Diagnostic validation – The second step of the API call would be to validate that its full functionality is available. The idea is to preempt the process if the call is not able to function as desired and return an apt error code. This will allow the calling code to trigger its contingency functionality. (Again, for plan B.)

    While this should never happen, Murphy’s law does play out once in a while. It could be that information that the call needs to run is not available and running it without it will cause a malfunction. Or perhaps an additional server that is necessary to the running of the call is down. Anything that is pre-requisite to a sophisticated call running its process.

    This Boolean should be maintained proactively by the API itself and represent the real-time status of it. If there is reason to believe that the process will hang, abort it rather than commence with it.

  6. Core functionality – The third and final step of the API call would be to run its core functionality and return the object of the call. At any time that the desired information cannot be returned, a helpful error code should be returned in its stead.

  7. Testing mode – Enable the simulation of errors in the API processing so that corresponding errors codes can be caused to be returned to the requesting functionality. This will benefit the testing of contingency functionality for when actual calls fail.

A product manager of a real estate data service recently shared with me that her clients use their APIs to obtain data for extremely high-value decision making. Her group needs to be very careful about how it deploys changes to its APIs so that the integrity of the paid-for data does not waver. Any of her clients could lose confidence in it after a single faulty API call and discontinue using it.

If APIs managed as full products in and of themselves are designed along these lines, that is great. I believe that an open commitment to the UX of them would increase their marketability. If not, I posit that these steps would be a welcome change for those subscribers who need to use them. If you have any questions about my proposal or would like to suggest a change to it, please reach out to me and let me know.