The (other) APl way: Application Pleasant Interface

If you follow only one way of the API smartness, this is the way.

Design, mock, test.
Iterate until you get something pleasant.
API design mantra

An API is designed by humans to expose data to humans building applications and not for applications only. An API is an Application Programming Interface but it should also be an Application Pleasant Interface (other API acronyms) so the humans who build the application consuming this API do not need to struggle to understand it and its data.

So, whatever the type of your API, take time to design it.

Some directions for this (other) API way:

• Aim at least at level 2 of Richardson Maturity Model by using resources and HTTP protocol.
• Choose a language
• Do not expose your back-office.
• Avoid inconsistency by levelling your endpoint, resources and error handling (standardize your API).
• Try to stick to best practices like this describe in RESTful Web Services Cookbook or NARWHL.
• Avoid cryptic data, for example use human readable codes instead of puzzling integer values or at least give labels corresponding to these codes.
• Use API definition/description/modelling language like Swagger, Blueprint or RAML
• Mock your API to test it in early stage.

The RTCFM way: Read The Consumer Friendly Manual

Even if you achieve the (other) API way brilliantly, consumers will probably need a little help to use your API.

To most developers, writing API documentation is nothing short of torture. But to a few of us, it’s a fascinating area. What gets us so excited?
Kin Lane, The API Evangelist, Why we write API documentation

API documentation must be exhaustive and consumer friendly:

• Make it human readable: so people using your APIs can actually understand it.
• Make it machine readable: so people using your APIs can build clients automatically and in the future Skynet could destroy humanity applications can talk to your API without someone coding.
• Use API definition/description/modelling language like Swagger, Blueprint or RAML to help you create both human and machine readable documentation.
• Beware to include all aspects of your API. A beautiful Swagger UI or equivalent documentation is sometime not enough, there are other things to document:
  • How connect to your API.
  • Rate limits.
  • Service chaining.
• Keep it light, keep it simple. Consumers do not want to read a documentation as long and hard to understand as In search of lost time to use your API and as difficult as The Phenomenology of Spirit:
  • Use good old diagrams.
  • Write tutorials.
  • Give code snippets.
• If your documentation is In search of lost time or The Phenomenology of Spirit type, you may have missed something in the API design.

The hypster way: Hypermedia

This way is a subpath of the (other) API way.

The best definition of hypermedia

Adding hypermedia will lead your API to level 3 of Richardson Maturity Model and help consumers to know what they can do with your data on the fly.

This way could be considered experimental by some and is the subject of many debates in the API community (read, for example, Mike Stowe’s post concerning objections to HATEOAS). But you really can use it to solve concrete problems for more informations you can read my posts concerning HAMM (Hypermedia API Maturity Model) part I and part II.

The mad scientist way: Code on demand

Another subpath of the (other) API way.

The final addition to our constraint set for REST comes from the code-on-demand style of Section 3.5.3 (Figure 5-8). REST allows client functionality to be extended by downloading and executing code in the form of applets or scripts
Roy Fielding, Architectural Styles and the Design of Network-based Software Architectures

Maybe one day you’ll be confronting a problem that even a good combination of (other) API, RTFCM and Hypster ways cannot solve. This day, you should try the Konami code on level 3 of Richardson Maturity Model to gain access the the secret lost level 4: code on demand.

This way is highly experimental and I haven’t use it (yet…). You could use it for example to send a “control amount” function to the consumer to validate input on a money transfer locally and avoid some API calls.

You can read Mike Stowe’s post about his experiments on this field.

The empathic listening way

Last but not least, he empathic listening way.

One Ring Way to rule them all, One Ring Way to find them,
One Ring Way to bring them all and in the darkness brightness bind them.
J.R.R. Tolkien, The Lord of the Rings ways of API smartness

This is the alpha and omega way. Whatever the ways you choose to take, you’ll have to follow this way.

Empathic listening (also called active listening or reflective listening) is a way of listening and responding to another person that improves mutual understanding and trust.
It is an essential skill for third parties and disputants alike, as it enables the listener to receive and accurately interpret the speaker’s message, and then provide an appropriate response.
Richard Salem, The benefits of empathic listener

You must listen to consumers because everything cannot be perfect the first time. You’ll have to listen to them, learn from them and then adapt. You’ll also have to listen to you because a provider must be his first own consumer.

Another classification?

In a nutshell, the ways of API smartness are:

• The (other) API way. Design a Application Pleasant Interface for your data.
• The RTCFM way. Read The Consumer Friendly Manual. Document all aspects of your API.
• The hyptser way. Add Hypermedia to explain what you can do with the API’s data.
• The mad scientist way. Use code on demand to lend some of your business intelligence to the consumer.
• The empathic listening way. Listen, learn and adapt. The alpha and omega way.

Répertoire bibliographique universel, Paul Otlet “Mundaneum Tiräng Karteikaarten” by Zinneke - Own work. Licensed under CC BY-SA 3.0 via Wikimedia Commons.

As I was writing this post, I was wondering if these ways could be used for a sort of (meta) classification/evaluation/maturity model of API and API providers including RMM, HAMM and other things… I feel like some sort of Paul Otlet for APIs… I’ll think about it.