Building a Rest API from the ground up — Part I
This article will be the first from a series of posts about the process of building a new REST API from the ground up. Our focus here will be on the why and a little about the what of the new API. Later, we’ll explain how. The project was developed by the Squad Integrations at Nmbrs, comprised by Adrian Ilie, João Carmo, Manuel Jerónimo, and me.
Importance of our API
The public API is a critical part of Nmbrs strategy. We believe in the best of breed approach and that the customers will be better served by choosing which software they want to work with. By choosing their solutions, they can streamline their processes and better serve their employees. Being a product leadership company, we care about having the best possible solutions to solve our users’ needs, and that’s where this project started.
Currently, we have a SOAP API that is heavily used by multiple users, with more than 7 million calls per day and more than 100 integration partners connected. You can find this on appstore.nmbrs.com. At Nmbrs, we want to make sure that our partner can easily connect and that our customers can easily activate applications. However, we felt that it was not serving our integration partners and Nmbrs customers as well as it should. Based on this perception, our Squad began an analysis to understand where changes would be needed.
Discovery phase
We started with many assumptions and hypotheses of what we believed should be improved. However, creating a project with as much impact as this solely based on our assumptions is not the right approach. We do this for our customers. So we firmly believe that involving them in the research process is critical to deeply understand their problems and what solutions will bring the most value to them.
Our mission was to first, understand the problems users faced with the current API and then, based on the feedback, create a plan of action. Finally, we would then execute this plan. We used a lot of inspiration from the following books: Enterprise API Management, The Design of Web APIs, and APIs: A Strategy Guide. It helped us ensure we were building a solid and scalable strategy for the API. All of the books emphasize the importance of knowing the real business value of an API and focusing the design thinking on the user and the organization’s needs.
- To begin, we carried out an online survey with partners to gather quantitative data on the overall feeling and perception of the API.
- Then, we went for one-on-one interviews with some partners to understand their problems in more depth. We also analysed the support tickets that were coming to us, specifically related to our API. It helped us to understand if there were issues that appeared frequently and what were the customers struggling with.
- Finally, we did log analysis using Loggly (our logging provider), to understand the current behaviour of partners and how they interact with our current API.
What we found was that the current API has problems for both partners and customers. For the integration partner, there is a lack of consistency throughout calls and unclear error handling which makes it harder for the developers to navigate and use the calls. Also, there is poor documentation with no clarity on default and mandatory fields, confusing instructions and broken links. For the Nmbrs customer, it’s confusing to issue tokens and manage permissions. At the moment, the customer has to log into Nmbrs to manually retrieve a token and copy and paste this token into another application. This requires them to know about APIs and tokens and manually manage the permissions of what the partners can access. The permission management can be time-consuming and confusing for the customer as it has to be done call per call, and if the partner needs to have more access, it has to be changed manually.
All of those problems create a lot of friction when partners and customers have to use the API and its integrations, which is exactly what we wanted to solve — making it easier for them and providing them with a better experience.
Prioritization
Based on all we found on the discovery phase, we started an analysis of what would be the impact vs the difficulty of solving each of the problems and based on that we used the MoSCoW analysis to identify ‘must-haves’, ‘should-haves’, ‘could-haves’ and ‘won’t-haves’. This gave us a clear direction of where we wanted to go.
Furthermore, as we want to be a global company, it doesn’t help that we have a different API for every country we are in as this isn’t scalable — an API is crucial for product expansion. For instance, if you have an international recruitment company, it’s better if they can connect to a global API for data that isn’t payroll related. Otherwise, they have to set everything up in a new country separately, which can be time-consuming, inefficient and costly.
The outcome of the discovery phase was a clear goal on what we wanted to achieve: “Provide a self-service easy-to-use API that is easily activated by users and supports the expansion of Nmbrs to new countries”. Based on all the research done, we realized that we could not solve the problems while using the current API. We concluded that it makes more sense to start a new one in a technology that supports the resolution of those problems, and that will drive the business value needed. We’ll deep dive into the technology in later articles.
Measure
After having a clear goal and an understanding of the problems we are trying to solve, we needed to define how to measure success during and after the development phase. Measures are critical to be able to check if we are achieving the desired outcomes. Only by setting measurable objectives, we can confirm this initiative was successful.
We decided to keep track of the following measures:
- reduce support tickets related to the API;
- reduce the average time to connect;
- increase NPS;
- reduce infrastructure costs.
As a whole, this project shows the innovation that is constant at Nmbrs. We had a lot of liberty to explore all of our options, think of the API design ourselves, and talk to customers to see how they would like to see this data. There’s a lot of autonomy and trust that as employees, we’ll make the right decisions, and we’re always in contact with the main stakeholders inside the company to guide us along the way.
In our next article, we will focus on the technical part of building the API.
About Gabriela
As Product Owner of Squad Integrations at Nmbrs, Gabriela makes sure that the integration partners can easily connect via the Nmbrs Public API and guarantees a seamless experience for users. Originally from Brazil and living in The Netherlands for the past two years, Gabriela has a computer science background and previous work experience as a QA Engineer.
