BBVA API Market
Both beginners and experienced users of any type of software sometimes need to refer to the instruction guide, which explains its functioning and technical characteristics. However, as with other types of product, there are occasions in which, no matter how much they are read and reread, these documents are incomprehensible even for professionals.
Even if APIs (application programming interfaces) are not softwares in themselves, they must be accompanied by an even more detailed and exhaustive documentation so that their structure is made clear for developers and the latter can use them in a fast, efficient manner.
In addition to facilitating work, a well-documented API improves one’s experience, accelerates the integration process between systems and encourages those that have already used it to recommend it to others, thus bolstering the reputation of both the company and the service.
The process, therefore, cannot be reduced to integrating a series of HTML pages in which a description is made of how to perform the authentication, the possible environment types and the utilities of each resource. It is necessary to provide developers with a visual and interactive experience that will allow them to directly try out the various functions, for which purpose there are various options that the API managers must evaluate in order to choose the one that is best suited to one’s needs.
One of these is API Blueprint, which is based on Markdown, a simple language for marking up documents that consists in a plain text syntax which the tool converts to HTML and other formats. In this way, it is easy to understand by humans and, although it is owned by Apiary, most of its functions are open source.
Moreover, the list of possibilities includes such specifications as RAML (RESTful API Modelling Language), IO Docs and Slate. The latter tool, likewise open source and Markdown-based, offers elegant, well-structured and user-friendly results. It makes it possible to concentrate all of the documentation into one single page, placing the API description on the left and code examples for each function on the right.
The most popular, however, may be Swagger, a language designed for the documentation to evolve at the same time as the implementation, as it can be automatically generated by means of annotations in the code. It structures the user guide into a visual interface in which developers can not only find information but also try out the interaction commands and observe the results in real time.
In search of a universal language
Swagger, founded in 2010 and donated to the community by the SmartBear firm currently constitutes one of the most commonly used standards, accepted by most programming languages and maintained by a wide community of professionals.
As evidence of its success, the specification has been chosen by the recently launched Open API Initiative. This is a collaborative project of the Linxu Foundation and is backed by, among others, Google, Microsoft, PayPal and IBM to standardise the description of the programming interfaces, providing a valid pattern for any part of the world or any company and understandable by all developers.
However, other possibilities continue to appear, which improve some of Swagger’s results. Both its user interface and the open source interactive solution of LucyBot, based on Swagger 2.0, offer screens with a clear, user-friendly framework, making work easier for less experienced developers who merely seek to make use of a particular API function.
Whatever the method chose, the documents of the API must be focused on those who are going to use it, that is to say, both external developers and the very providers of the service that maintain and improve it. Attending to the needs and studying the feedback of these users will make it possible, besides, to identify those aspects that entail the most difficulty in clarifying them.
If you want to learn more about BBVA’s open platform and financial APIs, go to this site
Taking a customer through the entire buying process until it is formalized is an arduous journey and one that faces the constant possibility of the customer leaving. However, there are ways to make the buying decision happen if you are given facilities such as agile, secure financing.
In a connected world, APIs are the glue that keeps all the parts that form our day-to-day lives in place. The same way the power of glue depends on the material it is used on and the knowledge of its properties, APIs are only as useful as their documentation allows for.
There are different solutions to monitor the performance of an API, in terms of traffic, quality and speed of the answers it provides. Detecting faults in the code or quantifying the generated revenues are also some of the options offered by these useful tools.
