It is nothing new the enormous importance of APIs for the development of a company’s business. So much so that an ad hoc name has been created for it: the API economy. So promoting a culture of good practices in app design and programming interfaces is a must for companies and developers. The advice is to create useful, reusable and open products.
Like almost all development products, the code and the correct use of the programming language is a particularly complex issue. Patches are often needed to improve the way they work, and this means that while the API resolves problems up front, it also becomes a dirtier product that’s more complex and less practical to use. This is intended as a code of good practices for API developers.
An API that’s easy to use and learn
If an API isn’t easy to use and if it can’t be intuitively adopted by a developer, it won’t be fulfilling its purpose –namely capturing customers and expanding the influence of a company beyond the four walls of the office. There’s no sense in developing an API that’s doesn’t act as a tentacle, an extension of the values and the talent, in order to provide service and generate income. Under this approach, the first goal is for the developer to be able to deploy a basic implementation of the API as soon as possible.
● The API is an instrument, it’s not a goal in itself: it’s preferable to use familiar and habitual formats like JSON than to reinvent the wheel, and to follow more logical steps when developing an API REST or SOAP.
● Provide support to correct errors: developers can report faults and possible improvements in an API if there’s a space available for feedback. This enables the API to be improved, and at the same time, generates community.
If it’s not stable, we’ve got a problem
One of the worst nightmares for a developer is an API that’s constantly changing. Improvements are good, but they sometimes run the risk of interfering with the actual stability of the service, and particularly if there is no possibility of maintaining the previous versions of the API unchanged. This was why in 2011 Facebook’s app programming interface was rated the worst on the market by the developer community. One of the reasons was the continuous unannounced changes in the tool.
To avoid these problems, it can be considered good practice to use a version control in the API on most occasions –usually by creating different URLs in each process of incorporating new features and their impact on third-party apps. This also generates a list of versions with the date and the new developments in each case, something that occurs, for example such as Microsoft Azure and Amazon Web Services.
Facebook has been working along the same lines since 2011, introducing a more reasonable version control system for the developer community. With this procedure, each developer knows beforehand that there will be changes in the API every two years, and the dates are already announced: version 2.3 was published on 25 March 2015 and is due to expire in August 2017. The following table is an example of the version process for Facebook’s APIs and SDKs:
There’s nothing like security
The issue of security is always complex. So much so that here at BBVAOpen4U we’ve already highlighted its importance and the role of the OAuth and OAuth2 protocols in the need to develop APIs that are secure when used by third parties. The authentication processes must offer the maximum guarantees without overly hindering access to the service by other companies.
The API documentation is key
When someone develops an app, the target public is the average user. The product must be clear, simple and intuitive to use. When someone designs an API, however, the target public is a programmer, a professional with technical knowledge. Even so, the quality of the final interface not only depends on the product, but also on the documentation that explains how best to use it. Although the end user may have technical knowledge, it’s still crucial to have good documentation.
One of the most highly rated APIs around today is Stripe, an online payment gateway that’s competing in the market with PayPal and Braintree, to give just a couple of examples. The main reason Stripe is so popular with developers is its app development interface. And one of its strong point is its documentation, which is based on two key pillars:
● Each API method is documented in several languages and uses plain and simple instructions without too much technical jargon, to make it totally accessible.
● It not only contains information on API specifications, but also well-documented practical tutorials on how to tackle each job.
Follow us on @BBVAAPIMarket