Dynamic Generation of Documentation, Code, and Tests for a Digital Marketing Platform's API

Introduction

Nowadays, there is a great need to automate processes to achieve increased productivity. This necessity leads many companies to publish part of their internal services on the web, making them available to their clients through Application Programming Interfaces (APIs) (Abelló Gamazo, et al., 2017). Thus, automation is essential for many businesses, like digital marketing, making APIs a core component, since clients often need to automate and customize marketing processes.

However, web API are often black-boxes to its users, since its code is not publicly accessible (Schwichtenberg, 2017). Developers working on their applications rapidly integrate third-party software to build distributed software systems but learning how to use an API properly is not a trivial task (Meng, 2017).

Thereby, one of the most important characteristics of an Application Programming Interface is its technical documentation, which exists to facilitate communication between users and the API. To make an API easy to use it is essential to assure that its documentation is always correct and updated, and it provides clear examples of its usage (Uddin, 2015; Sohan, Anslow, & Maurer, 2015; De, 2017). In fact, the documentation can be very important to understand how to use libraries and frameworks developed by other teams and whose functionalities are easily accessible through APIs (Robillard, 2011).

Still, API documentation is frequently created manually and needs to be updated whenever the API evolves, otherwise it will become obsolete (Abelló Gamazo, et al., 2017), which is a common problem. This often brings maintenance costs to the developers every time a service is created or updated. Therefore, rather than focusing on automating what's easy, focus on automating the boring parts (unlike you, computers love repetition), the difficult parts (reduce error-prone steps), and the parts that need to happen when you would rather be asleep. As a human, you are better than computers at improvisation and being flexible, exercising judgment, and coping with variations (Limoncelli, 2018).

Such as for any software, API testing is essential to improve its quality and reduce the costs of developing an application (Tassey, 2002). Yet, sometimes, developing software tests can be even more expensive than building the product itself (Tassey, 2002).

Thus, to maintain an API, including not only its code but also its documentation and software tests, can be a very costly and painful process. Fortunately, some of these maintenance costs can be reduced using an API specification. An API specification establishes a contract and describes the API through a document readable by both humans and machines (Open API Initiative, 2018), allowing the generation of documentation dynamically through that contract. The API is forced to follow the contract defined by its specification, so it is possible to generate client and server code, documentation and tests.

In this chapter, it will be provided examples on E-goi’s public API. E-goi is a digital marketing platform with more than three hundred thousand clients in more than fifty countries (although E-goi’s center of attention is in Brazilian, Portuguese, Spanish and Colombian market). As a digital marketing platform, this software allows its clients to create marketing campaigns for different channels, including email, Short Message Service (SMS), voice messages, fax, web push and mobile push. After creating a contact list and filling it with relevant contacts, the list can be divided in different segments, ready to receive different sorts of campaigns. E-goi also provides its users with tools like automation workflows, forms and landing pages that, like campaigns, can be created from scratch, edited from many templates (either E-goi templates or already existing templates previously created by clients).