As a backend engineer, we face many decisions when building APIs, some of them are easy to make and some others are not that easy because of the several existent solutions for a specific problem, deciding which one is the best fit can become a nightmare if you do not assess it correctly. In this article, we'll cover three common topics: handling webhooks, file uploading, and API versioning, and for each one I'll describe few facts we can identify to help us easily make the correct decision.
Webhooks: One Endpoint or Many?
Webhooks are a way for your API to notify other services or get notified of events that occur. When designing your webhook system, one question that often arises is whether to use a single endpoint to handle all possible events or to create separate endpoints for each event.
The advantage of a single endpoint is that it simplifies the codebase and reduces maintenance overhead. All webhook payloads can be parsed and processed in one place, this is great! However, this can become unwieldy as the number of events grows, leading to complex branching logic, hard to debug or track, and potential performance issues, this is not so great...
On the other hand, having separate endpoints for each type of event allows for more fine-grained control and easier scaling. Nonetheless, this approach can lead to a bloated codebase and increased maintenance overhead, a way to reduce that overhead is to have an adequate separation of concerns in your endpoints. Always aim to separate or group your endpoints by business logic, example:
- If you have an integration with a payment gateway, you can separate and group your endpoints by specific models: payments, invoices, subscriptions, etc.
Ultimately, the decision depends on your specific use case, but if we could write a quick rule of thumb, it would be the next:
- If you have a small number of events and don't anticipate many more, a single endpoint may be the simpler solution.
- If you have many events or anticipate adding more in the future, consider using separate endpoints for each event.
So, basically it just depends on the number of webhook events that you are handling.
File Uploading: Synchronous vs. Asynchronous
When it comes to file uploading, there are different ways to do it, each with its own advantages and disadvantages. One common decision is whether to upload files synchronously or asynchronously, should we upload files before submission or wait until the submit buttons is clicked?
Synchronous file uploading means the file is uploaded when the form is submitted. This approach is simpler to implement, as it doesn't require additional background processing. However, it can lead to slow response times if the file is large, as the user has to wait for the file to finish uploading before getting a response.
Asynchronous file uploading means the file is uploaded in the background, even before the form is submitted. This approach allows for faster response times and a better user experience. The user does not have to wait until the file is uploaded to see the new page. However, it requires additional background processing and can be more complex to implement.
When deciding which approach to use, consider the size of the files being uploaded and the user experience you want to provide.
- If you expect large files, asynchronous uploading may be the better choice. You can upload the files even before the form is submitted, this would give the user a great experience.
- If you want to provide a simple and straightforward user experience and make a quick implementation, then synchronous uploading may be the better option, just take in mind that the file upload time depends on the bandwidth of the connection and can sometimes take long, some users can try clicking somewhere else or reloading the page because they believe that there is a problem with the webpage, and then mess everything up.
API Versioning: Why and How
API versioning is the practice of creating new versions of your API as it evolves over time. This allows you to add new features, fix bugs, and make breaking changes without affecting existing clients. Even when your API is private and it serves only your own client, these practices may be needed.
Note that is a good practice to follow a versioning schema like semver.
There are different approaches to API versioning, but the most common ones are adding version numbers to the endpoint or using custom headers to indicate the version. Adding version numbers to the endpoint makes it easy for clients to switch between versions, but can lead to cluttered code and bloated APIs. Using custom headers can provide a cleaner API, but may require more work on the client side to switch between versions.
When deciding how to version your API, consider the tradeoffs between simplicity and flexibility.
- Adding version numbers to the endpoint is a simpler approach, but can lead to cluttered code. More code, more work.
- Using custom headers can provide a cleaner API, but may require more work on the client side.
In conclusion, easy decisions can become great enemies because we tend to overthink them. As a backend engineer, you'll face many decisions when building APIs. Whether it's handling webhooks, file uploading, or API versioning, there are advantages and disadvantages to each approach. By considering your specific use case and the tradeoffs involved, you can make informed decisions that lead to better APIs.
Top comments (0)