Developers often forget that creating, organizing and maintaining a set of APIs also means working hard on managing the user experience. After all, your APIs will be used by other developers.
An API is only as powerful as the applications and programs it connects; and if developers find it hard to incorporate an API, this may affect its end performance. You can never go wrong if you create APIs you would like to use yourself.
It’s not complicated at all to create an API with good user/development experience. To do so, you can follow a list of rules that are somewhat abstract but that you must bear in mind at all times; otherwise, your end product will not be consistent or easy to understand by an external developer.
Understandable and intuitive
In other words, an API whose documentation is secondary reading. And whose methods clearly say what they do, how this is requested and what data are returned. Naturally, all documents must be read but doing it once should be enough.
It’s not only a matter of creating a constant naming system that follows industry standards. Developers must also be able to intuitively anticipate the returned content.
How not to do it: design methods with generic names and numeric variables based on external IDs that cannot be recognized at first glance:
/api/cargar_datos?valor_predeterminado=3
Recommendation: use descriptive methods in your names for methods and arguments.
/api/lista_de_usuarios?cantidad=10&ordenar=nombre
Extensible
By definition, an API does not exist on its own in a digital haven, living independently from all other applications. APIs are extended, changed and refactored over time based on the feedback of other developers or the project’s own needs. Extensibility is essential in two ways:
• API’s own extensibility: the API must be able to grow with new methods in the future so as to maintain the principles of intuition and clarity we mentioned above.
• Extensibility of others: the API must be designed to help other developers create better applications; it must go beyond offering a connection between two points.
In user experience, the second type of extensibility is largely achieved through callbacks, which define the execution of data returned by the API.
Make sure that the data included in the response are enough to help design more agile user interfaces that require less code and facilitate development.
How not to do it: return few fields with unrecognizable values; need for extra calls in most cases.
{ “users”: [ 2, 3, 4, 5 ] }
Recommendation: the data returned by the API must be descriptive and with the ability to extend the connected software
{ “users”: [{
“id”: 2, “name”:”Laura”, “date_registered”: “2008/09/29”},
“id”: 3, “name”:”Sara”, “date_registered”: “2008/09/29”},
“id”: 4, “name”:”Ramón”, “date_registered”: “2008/09/30”}
]}
Standard
Do not reinvent the wheel. More experienced developers with more free time will have created some kind of “good practices” for user experience in practically all fields of software; your API must follow these standards. Find out about them, learn them and enforce them.
Ask for comments from other designers and developers during the initial planning stage. It is essential to know the interface’s end needs and the target experience.
If your API is going to be added to a complicated ecosystem of connections, especially in corporate settings, our two initial tips must prevail: intuitive and extensible.
If your API’s UX is poor, you can ruin the underlying work of the entire organization and destroy any possible agreements because a competing API is better adapted to its functions, involves less development from third parties or is designed using known industry standards.
Are you interested in financial APIs? Discover all the APIs we can offer you at BBVA