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
Businesses, from self-employed to SMEs and large companies, need financing solutions that suit their needs. Leasing is a method that can optimize the use of resources and which combines business liquidity (or lack of) with the use of assets. What is leasing and how does it work? Leasing is a financing method by which a […]
An API is a very useful mechanism that connects two pieces of software equipment to exchange messages or data in a standard format such as XML or JSON. Thus, it becomes an instrument that can be used to search for revenue, open the doors to talent or innovate and automate processes.
There are companies that collect and store bank data: information on accounts, transactions, credit-card operations, loans, investments... These companies' APIs give entities access to new markets and new customers.
