10 Mistakes to avoid when building your API

API development can be a frantic process. Severe deadlines, pressure from stakeholders and competitors, and millions of other factors can turn the process of building your API upside down in the blink of an eye. Oftentimes, developers dive into making an API without thoroughly planning a long-term strategy or considering potential technical bottlenecks. As a result, the API ends up working incorrectly, creates overhead on latency and bandwidth, or runs into scalability limitations.

What does an API mean?
API stands for Application Programming Interface. It is a set of protocols and tools that allow different applications to interact with each other and exchange data under predefined conditions.

To avoid mistakes when creating your own API, it is best to learn from the experience of other API developers. That’s why we’re here to tell signNow’s story. 

A few words about the signNow API to get you up to speed

airSlate acquired signNow in 2017. Having inherited the legacy API from its former devs, the new tech crew didn’t have to start API development from scratch. The team was going to optimize the existing API to improve its performance, compatibility, and scalability. But before this could be done, the engineers had to rectify the issues of the old API. 

It is one thing to know how to build an API from the ground up, and it is a completely different thing to make an existing API faster and more user-friendly. Despite many challenges, the signNow team managed to implement major improvements while also learning a great deal from the “legacy” mistakes. 

Today, we are ready to share a few insights about the development of the signNow API and reveal some of the key challenges our team had to overcome on its way to creating a robust API integration for embedded eSigning.

1. Inconsistency when following standards

Making an API requires setting a specific standard that engineers must follow throughout the entire development process. A standardized and consistent API not only makes your product look professional but also allows consumers to integrate your app with their own software more efficiently. In addition, a consistent and user-friendly API is much easier to maintain, enhance, and expand.

The signNow legacy API initially lacked consistency and standardization. Our engineers used REST as the fundamental approach for optimizing the structure and endpoints of the API. Following the best practices of API design, they managed to achieve much better consistency in the latest version of the API. 

What is REST API?
A REST API is an application programming interface that conforms to the REST architectural design. REST is a set of principles and constraints that optimize data transfers between the client and server, allowing web applications to interact with each other

2. Pushing API development instead of focusing on design

Building APIs should always start with meticulous architecture design, which implies the detailed planning of: 

• The structure of services 
• Key endpoints and the entities they administer
• Data format 
• Data model
• Method structure 
• Authentication mechanisms 
• Usage policies 
• API development tools, etc.

These aspects can (and should) be properly planned, documented, and approved before the development phase kicks off. However, API engineers often rush the design phase in attempts to come up with a functional API solution in the shortest possible timeframe.

As a result, an API that works without issue for user integrations eventually fails to provide enough flexibility on the back-end side of things. This often backfires later on due to maintenance difficulties and scalability limitations.

3. Improper API structuring

Initially, the signNow legacy API was built as a monolith that ran all the app’s processes within a single server. As a result, increasing the workload on any part (module) of the monolith could affect the performance of the entire app. 

For example, when the module responsible for document loading and post-processing was actively engaged, the performance of other modules would suffer due to the lack of server resources. This resulted in latency issues occurring in other processes such as authorization, user data management, signing sessions, etc.

To eliminate this problem, the team had to take a step back and split the monolith API into several services that could run in separate containers, scaling up or down depending on the workload. 

Currently, the signNow API is built as a layered system that consists of multiple interconnected services. It uses an API gateway as a single entry point and load balancing middleware to ensure the consistent uptime of servers.

What is an API gateway?
An API gateway is a tool that works as a mediator between the client and API backend services. Its task is to manage and route API calls and send appropriate responses back to the client.

4. Making an API in conjunction with a user interface

The architecture of the signNow legacy API was heavily influenced by the app’s UI. In other words, the features of the user interface (in most cases) dictated the development of the API. Its endpoints were built to send out large volumes of data, often bundling key requested objects with a large number of related properties.

On the one hand, this type of architecture turned out to be an efficient solution for the API’s users since the client apps would have to make a single request to obtain entire sets of data from the server. But from the back-end perspective, the API suffered from bloated responses that made data retrieval more difficult and put the entire database under severe stress.

Thus, despite the fact that the API could fully satisfy the needs of users, it was getting increasingly difficult to maintain in the long-term perspective – and this had to be addressed immediately by the new signNow team.

5. Not fine-tuning your endpoints

Returning redundant data may be nothing to worry about until your API user base grows. Once this happens, returning too much data from your endpoints will put a heavy burden on your system.

What is an endpoint?
An API endpoint is a destination where an application sends its data requests to another application. The retrieved digital resources available at a given endpoint are sent back to the client application as a response.

As mentioned above, the signNow legacy API was initially built to return large sets of data. This actually benefited some of its users. But as the number of customers increased, the database had to return more and more data, and this eventually impacted the system’s latency and bandwidth. 

The key to resolving this issue was creating endpoints that deliver smaller subsets of data or allow clients to decide whether they need an entire object returned or just some of its properties.

6. Fixing an API when it is already in use

Whenever you have to make improvements to your API, remember that many existing integrations are already relying on it. Changing or removing the resources and patterns used by your clients can critically affect the performance of some integrations. The risk is particularly high when you are trying to optimize a legacy API – as signNow did.

That is why we emphasize the importance of properly designing the architecture of your API. Don’t rush any decisions and try to focus on the long-term perspective. It is much easier to make amendments to your API while it is still in development than fix things that have already gone live.

7. Not versioning your API

If you have to upgrade or optimize an API your customers are already using, you’ll want to make sure that your improvements won’t break the existing integrations. Creating different versions of your API is the best way to avoid potential problems.

Versioning allows you to make your updated resources and features available without changing or removing your existing endpoints. Thus, your clients have a choice to direct their requests to a specific version of a resource or feature. In case your changes cause any issues, the client will be able to return to the previous version at any time. 

The latest version of the signNow API is currently available as “V2”, where many of the legacy problems were resolved. However, despite the obvious benefits, it is not always easy to convince customers to switch to the new version of your API. If the user is satisfied with how your previous API version works, they will likely have little incentive to invest time and effort in transitioning to the newest version. 

Nevertheless, make sure to convey the benefits of your updated API to your clients and actively promote it. Offer the latest version of your API to new customers and entice existing users to switch to it as soon as possible.

8. Continuously growing your technical debt

There’s a chance that a newer version of your API wouldn’t have features that were available in previous versions. Sometimes, dropping those features makes sense for the sake of better API stability, security, performance, etc. However, those obsolete features will still be present in your documentation, and new users might take an interest in them. 

Since older versions of your API are optional for users, you may find yourself in a situation where you have to maintain obsolete features for years. Although it is hard to avoid this problem when your product is constantly developing, try to maintain the overall consistency of your API versions. Otherwise, you will have to find ways to bring the missing features back, and the list of these features will steadily grow.

9. Not standardizing your rate limits

Some of your larger customers may cause unnecessary stress on your system by sending too many requests. Without limiting the number of requests, your database will quickly overload. This will result in your API response time increasing or even causing timeout errors for all of your users.

To make your system more stable and reliable, your API must be protected with proper rate limits. signNow used to have selective rate limits for some of its endpoints. But to achieve greater system stability, we finally made a decision to implement a standardized limit of 1,000 requests per hour for the entire API.

For some of your most high-polling requests (e.g., when the client frequently requests updates from your database), you may also want to consider the webhooks framework that automatically sends updated data to a client once it changes. Webhooks can significantly reduce the stress on your system.

10. Inconsistent SDKs

Currently, signNow provides SDKs in five programming languages: PHP, Java, .Net, Python, and Node.js. Our team inherited SDKs along with the API, so bringing them up to the standard was part of the job. But the problem with SDKs was that some of them were missing certain functionalities that signNow was perfectly capable of. It turned out that some features that were actually described in the documentation simply didn’t make it into the SDKs.

SDKs are essential to any API as they allow developers to save time integrating your product with their own apps. Realizing the importance of SDKs, our engineers set out to add the missing features to the development kits for all the available programming languages. The most complete was the Node.js SDK, so it was taken as a blueprint. The rest of the SDKs were eventually brought in line with it.

The bottom line

API development is a complicated, multi-stage process that requires engineers to be flexible and forward-thinking. Remember that you can avoid most mistakes if you take enough time to carefully plan everything from start to finish. Here are a few points to stick to:

• Focus on strategizing
• Polish your API architecture
• Always keep scalability in mind
• Stay consistent throughout the entire development process
• Try to fix mistakes before your API goes public

The signNow team has come a long way in bringing its API up to globally accepted standards. Today, we are ready to offer developers a feature-rich and user-friendly eSignature integration that adds value to their software products.

Take note: We’ve created a series of articles covering the essential signNow API functionalities to help you get started:

– Building vs buying eSignature API
– The ultimate guide to the signNow API
– signNow API Dashboard