The Ultimate API Checklist for SaaS companies

September 10, 2019

The Ultimate API Checklist for SaaS companies

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…

The Ultimate API checklist

Use HTTPS and a signed SSL Certificate

Publish a RESTful API

Correct response codes

Nice to have: GraphQL

Implement versioning

Document your API

Use secure authentication

Paginate results for easier data handling

Add timestamps

Enable side-loading

Error handling

Publish CRUD endpoints

Get objects by other fields

Add incremental endpoints

Include metadata

Offer Webhooks

Test your API

Offer a sandbox

A gateway to protect your API

Set a usage limit

✓ Use HTTPS and a signed SSL Certificate

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.

✓ Publish a RESTful API

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

✓ Correct response codes

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.

✓ Nice to have: GraphQL

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.

✓ Implement Versioning

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.

✓ Document your API

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:

    • Authentication
    • Base URL for test, production, etc.
    • General concepts
    • Paging, filtering, data structures
    • Response codes (errors etc.)
    • Usage limits (rate limits, max. requests per second/day/month, etc.)
    • A list of all endpoints (URL’s), and per endpoint:
    • A description, the method (GET, POST…) and the URL
      • The headers and body structure
        The parameters, and per parameter:
        • Description
        • Type (integer, string…)
        • Required or optional
        • Example value
        • An example call: how to call this endpoint from the command line using curl, and how to call it in various programming languages such as JS, PHP, Python, .NET etc.

✓ Use secure authentication

You can choose between several secure authentication methods:

        • oAuth2
        • JWT web tokens
        • API tokens or keys

Basic authentication using login and password is not recommended.

✓ Paginate results for easier handling

Make sure to implement paging to support large amounts of data:

        • Cursor based: your API returns a cursor or URL with each response to get the next page
        • Paging parameters: your API has parameters such as limit and page

✓ Add timestamps

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.

✓ Enable side-loading

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.

✓ Error handling

Provide detailed error messages when things go wrong. There’s nothing worse than a 500 response without any explanation 🙂

✓ Publish CRUD endpoints

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:

        • List: returns a full list
        • Search: returns a filtered list
        • Get: returns one record (one object)
        • Create: creates a new object
        • Update: updates an existing object
        • Delete: deletes an object

✓ Get objects by other fields

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.

Examples:

        • Get contact by email
        • Get company by VAT number
        • Get company by domain

✓ Add incremental endpoints

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:

        • Get new contacts created since timestamp X (timestamp_created >= X, where X is a unix epoch timestamp)
        • Get new and updated contacts since timestamp X (timestamp_lastupdate >= Y)

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).

✓ Include metadata

The ability to request metadata through the API is very useful for various integration use cases. Examples:

        • List object types (useful for platforms that support custom objects)
        • List fields of object type (useful for platforms that support custom fields)

✓ Offer Webhooks

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:

        • Add webhook
        • Remove webhook
        • List webhooks (from one account)

✓ Test your API

Postman is a great tool to execute API calls for testing.

✓ Offer a sandbox

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.

✓ A gateway to protect your API

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.

Examples:

✓ Set a usage limit

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:

        • Request limiting: a maximum number of API calls per hour/day/month.
        • Rate limiting: a maximum of e.g. 10 calls per second, to limit “bursts”, or a maximum of e.g. 100 calls per 60-second sliding window.

Conclusion

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!

Do you want to add another checkpoint to this API Checklist? Let us know!

Blog categories

All

Artificial intelligence

Event Tech

GDPR compliance

Marketing automation

Product updates

SaaS companies