BBVA API_MarketAPI WorldAPIs are everywhere, but… what about their documentation?

APIs are everywhere, but… what about their documentation?

3 min reading
Development / 19 February 2020
APIs are everywhere, but… what about their documentation?
APIs are everywhere, but… what about their documentation?

BBVA API Market

Download PDF

Share in:

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.

However, API documentation goes beyond usefulness. It explains the reasons why it was developed, serves as a primary channel of communication between developers at both ends of the service, helps to discover new capabilities and is directly responsible for the popularity and implementation of the API.

In other words, a similar or slightly inferior API, or a capable API with a large volume of documentation will be more successful than another API with documentation that is scarce, poorly organized or difficult to understand. Despite the fact that developers are accustomed to working with multiple logical problems day after day, few things are more pleasant for a programmer than to implement user-friendly methods in an API or a service that helps them do their work.

High-quality documentation not only helps understand the various methods and possibilities of an API, but also guides developer thinking toward new previously unknown opportunities that improve their applications. More developers working on an API traditionally amounts to more available resources, given the larger input capacity of the same and may even result in expanding the development team.

Elements that are essential

Using BBVA API Payments as an example, we are going to list the factors that cannot be missing from excellent documentation, so developers can work comfortably, understand our proposals and expand the functions of their software to provide new features.

1. A table of contents that makes sense

Links to references for each method and an explanation of the changes log so veteran developers can see what has been changed at a glance.

 

2. A description of each method

A detailed explanation of all their arguments, with specific examples of each.

3. Responses for each method

It is not only a matter of showing what has to be introduced, but what to expect. A specific description of method returns, both correct and possible errors, with their corresponding solutions.

4. Sandbox

This is a safe and fast way to give developers a good idea about each method, which does not require any settings, requests for access passwords, registration or making a formal commitment.

How to draft high-quality documentation

  1. The first step is to plan the documentation while planning the API. It should be written step-by-step at the same time as the API, so an internal reference is compiled during development. This will make it easier to convert it into documentation for third parties.
  2. It should have an opening page that includes a general description of the API, as well as links to the possibilities and capacities of the API, so the reader can begin to become familiar with it. It is also essential to have a search function and clear URLs that can be referred to at a later time.
  3. Each method must be explained clearly and concisely. It is key to maintain a descriptive name policy of resources and methods. After the initial description, the method’s input arguments and expected returns should be specified.
  4. As regards the arguments, their format and accepted restrictions should be specified at all times, distinguishing between those that are necessary and those that are optional. Their names have to be easily understood by other developers and the order in which they appear should be logical. Grouping arguments according to their direct relationship and their mandatory presence is an easy and common way to do this.
  5. Outputs or returns may be more complicated. This requires explaining which are to be expected if everything goes as planned and also explaining the type of errors that may occur. The errors must be specified, as well as their detailed solutions.
  6. Lastly, multiple examples of how to use each method have to be provided; these should cover a sufficiently wide range to represent the most common uses. If they can be provided in several of the most common programming languages, so much the better. Otherwise, a single case should be provided with the most common programming language or the only language available to use the API, or even a pseudocode that follows common logic pathways to other real languages.

 

If you want to know more about BBVA’s financial APIs, visit this website.

See more about:

Development

It may interest you

If you want to know more

You may be interested in