BBVA API Market
One of the basic pieces which determine a developer’s user experience when making use of the services offered by an API (application programming interface) goes beyond the website format or the authentication process.
We are referring to an interactive instruction booklet that shows those accessing the platform its structure and organisation in order to make work easier for them, so that they do not have to spend time investigating the functions or engaged in unproductive tests. And like any self-respecting manual, it must meet certain requirements that differentiate a good framework from the simple compendium of undecipherable pages.
The documentation of an API must not merely constitute a list of the various devices in which the contents may be displayed–smartphones, tablets, smart TVs, consoles, etc.− and their corresponding techniques and procedures. Ideally, it must reflect the full content ecosystem to explain the user how to interact with the interface.
A good example of all this is the documentation of the API of Stripe, one of the most popular online payment services as well as an alternative that is drawing many customers away from PayPal, which has decided to improve the image of its own API (and its documentation) due to the competition.
The first step consists in choosing the tool with which to generate the documents in the event of not having a software of one’s own. There are different options in this respect, although some of the best-known are RAML (RESTful API modelling language), Slate and Swagger. The latter constitutes one of the most widely used standards (also by PayPal) and has been chosen by the Open API Initiative as a model. In the case of Stripe, they have adapted the documentation format and style of the API of CoffeeScript, but have created their own software to produce the documentation.
Whatever the choice, the organisation of the interactive index must be based on the various tasks and differentiate the subjects by categories in order to present the information clearly and legibly. However, one must not exaggerate the number of tabs or pages but rather, optimise the space and place the related themes close.
Following this initial sketch, one must include a series of essential concepts. One of them consists in a list with all the functions that developers can obtain from the API. This includes all the data types it offers for third-party applications and the specifications each function requires.
Another important aspect lies in the guides, which serve as a complement for the above. They expand the register of functions with a text to explain each section in greater detail, always using a comprehensible language, without acquiring too specialized or technical a tone, as not all developers have the same experience.
Moreover, one can add tutorials that act as a manual to show developers certain functions as well as specific examples of what they can do with the API. One example is this Stripe tutorial for constructing a customised payment form. In each demonstration, one must add the code required for calling the interface from the application and examples of the type of answer one would obtain.
Likewise, one must also point out the various programming languages accepted by the interface and even give the examples in each one of them. One possibility is that of allowing users to choose the language they prefer from the very start, as is the case of the Stripe API documentation, which offers a choice between Curl, Ruby, Python, PHP, Java, Node and Go.
Another resource developers might find useful is the complementary list of the different formats and devices that can make requests to the API, and examples of the types of function they can use. This allows them to access the information via an alternative path instead of searching by subject. There is also the possibility of adding a kind of “fast start button” so that API users can try out some basic function with one single click. Such is the way in which Stripe does this:
Although the APIs act as an abstraction layer – serving to conceal certain details of the operations being executed− what is best, so as not to confuse developers, is precisely to avoid abstractions in the documentation. In other words: filling this instruction booklet with examples which show the interactions and the results of each one of them in an understandable language and with the associated code.
If you want to learn more about BBVA’s open platform and financial APIs, go to this site
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.
QR code payment is an alternative form of mobile payment that requires no card chip or NFC technology: just a camera and an internet connection Payments with a QR code are increasingly popular among younger consumers and tourists, as well as one of the most demanded forms of payment, especially by Chinese visitors to Spain. […]
If you want to finance a car, you must analyze all the options: how does financing work, and when should it be done? How to finance a car is a very frequent question both from individuals with mobility needs and from companies that need a vehicle to use. Is it better to make a conventional […]
