September 10, 2019
SaaS companies should adopt an API-first strategy since API’s are the cornerstone of integrations, ecosystems, and partnerships.
Integrations are not only essential for SaaS survival, but they also open up new use cases, reduce churn and bring added value to your platform. Publishing an API is crucial for SaaS growth, however bad API design can damage your SaaS platform reputation.
When SaaS companies use Blendr.io – an embedded integration platform – to boost their native integrations offering, we often receive the question – “What is a good API”? At Blendr.io, we have been working with hundreds of API’s and compiled an API Checklist for SaaS companies. Here we go…
It goes without saying that your API endpoints need to use HTTPS as opposed to HTTP, your data needs to travel the web encrypted. Make sure your SSL certificate is not self-signed, it needs to be signed by a trusted authority. If not, certain clients will not allow making API calls. Use SSLChecker to test your certificate.
Most SaaS companies today, choose to publish a RESTful API, using JSON as data format. This is as opposed to e.g. SOAP Webservices using XML, which are much harder to consume. Great tutorial on REST API concepts: https://www.restapitutorial.com
Make sure to return the correct response codes, such as 200 for a successful API request, 401 for an unauthorized request, etc. Many clients rely on this response code to know what went wrong. If you send a 200 response with an error in the response body “Not authorized”, this is considered bad practice.
REST API’s have a limitation – clients that consume the API, typically need to make many calls to get all the data they need, and on top of that, the client typically receives more information than it requested. That’s why Facebook invented “GraphQL”, a query language definition for REST API’s.
GraphQL queries are more or less written in JSON, but there are no values, only keys in the JSON. There are only around 5% of API’s that support GraphQL, and that’s for a reason: it’s hard to implement an API which supports GraphQL queries since the incoming queries can be more complex compared to a classic REST API.
Your API will most certainly change over time, as you add new features, or perhaps fix a certain issue. However, you cannot just change the structure and behavior of your API once it is in production and used by customers and partners. Each change could break their integration. Therefore, it’s essential to implement versioning in your API from the start.
Your initial version is 1.0. Minor updates become version 1.1, 1.2 ,etc. while major updates become 2.0 and beyond. When you deploy a new version, it should not replace the older versions. Therefore, each version needs to have a unique URL (for example https://api.domain.com/v1.0/…). Alternatively, the URL’s stay the same, but the consumer requests a certain version via a parameter in the header.
You can use Swagger, Postman, Apiary, or Readme.io to automatically generate a part of your documentation. Of course, there’s more than just listing the URL’s and parameters. Your documentation should also explain concepts, interactions between certain types of data, data flows that must be followed, etc.
Here’s a checklist of things to include at a minimum in your API documentation:
You can choose between several secure authentication methods:
Basic authentication using login and password is not recommended.
Make sure to implement paging to support large amounts of data:
Make sure to include a “timestamp created” and “timestamp last update” for each record. The timestamp can e.g. be an epoch unix timestamp. This is related to incremental data retrieval, see below.
Side-loading allows to retrieve related objects as a part of a single request, e.g. when requesting a list of customers, each customer object would have a property “orders” with the actual orders of the customer. The side-loading can limit the number of API calls made.
Provide detailed error messages when things go wrong. There’s nothing worse than a 500 response without any explanation 🙂
Publish CRUD (Create, Read, Update, Delete) endpoints for each object type (e.g. Contacts, Companies, etc.). In case your SaaS platform is only a source of data, not a destination, it might make sense to publish a read-only API.
Example CRUD endpoints for one object type:
In many integration use cases, it’s useful to be able to retrieve a single object not by its id, but by another unique property.
For data synchronization, it’s very useful to be able to request new and/or updated records since a given timestamp. Such APIendpoints are useful in scheduled integrations to process new data incrementally on each run (e.g. every 5 minutes or every 30 seconds).
Example API endpoints:
Note that this can also be accomplished with webhooks, but webhooks do not allow to process historical data (a.k.a. doing a full initial sync).
The ability to request metadata through the API is very useful for various integration use cases. Examples:
Offering a Webhook capability in your platform provides value to your customers, it allows them to orchestrate certain processes efficiently without unneeded delays, and it optimizes resource usage on both platforms involved.
The Webhook configuration in your platform, should at a minimum allow customers to configure the outbound URL. Make sure to enforce HTTPS for security reasons, in other words, do not accept a Webhook URL that uses “http://”. Also, customers should be able to configure the event that triggers a Webhook call.
Make sure your Webhooks support retries (queueing) and respect rate limiting of the destination endpoint.
Ideally, your API allows to create and manage webhooks so that the creation of webhooks can be automated. Example endpoints:
Postman is a great tool to execute API calls for testing.
Your API users will have to test their integrations, so make sure to offer them a free limited license to use your SaaS platform for testing purposes. Depending on the type of platform, it might be needed to offer a so-called “Sandbox” environment, which is a testing environment where tests cannot cause any “damage”. For example, online payment platforms offer a Sandbox environment where test payments can be made, without actual money being involved.
To secure your API, it will be behind a firewall, but that’s not enough. You will also want to protect your API in terms of the maximum requests that a consumer can send per second etc. And you may want to apply some caching, keep track of usage per consumer and monitor the health of your API. This is where an API gateway comes in. An API gateway sits in between your actual API and the consumer, and it can take care of various tasks such as logging usage and limiting usage per user.
It’s essential to limit the usage of your API to reasonable levels, since API consumers are usually automated code or scripts, and they can go wrong. If your partner makes a mistake, their code might start calling your API multiple times every second. If on top of that, that same script is launched for each of their customers, you might be looking at hundreds of API calls per second coming your way.
An API gateway offers features to limit the usage of your API per end-user. Usage limiting typically consists of 2 parts:
SaaS companies should should adopt an API-first approach.
Your API will be used by customers, partners and iPaaS platforms such as Blendr.io. Blendr.io is a powerful, hyper-scalable and secure integration platform for SaaS companies. Use Blendr.io to create native integrations with the low-code visual builder, embed them into the UI of your platform and centrally manage your customer integrations.
Are you still building your API? We recommend having a look at some of the platforms with great API’s – such as Hubspot or Eventbrite – to get an idea of how they implemented and documented their API.
Did you find the API Checklist useful? Let us know!