Chapter 1. Customer Integration

The main driver behind exposing an API to your customers would be to allow them to customize their experience, for your core product to closely suit their needs by allowing them to automate processes and integrate with other systems. This level of integration encourages customers to use your product more as well as increasing loyalty due to the time and effort spent integrating.

A final reason could be as an upsell driver such as how Salesforce only allows API access for Enterprise level contracts.

The audience here is clear – you’re targeting existing (as well as potential) customers. If your existing product currently provides distinct contracts or plans, you might choose to differentiate between levels of API access based on these plans. This is especially important if these contracts allow for access to different sets of functionality in your core product.

Additionally, if you’re planning to use your API as an upsell driver, you’ll want to provide trial access to all customers either with a reduced usage allowance and/or functionality.

Since you’re offering an API to your existing customers, you’ll want to ensure your API offering covers most (if not all) of your core product’s functionality as well as ways to import/export data via API and automate configuration changes. You may decide to split these different sets of functionality into multiple APIs or services to be bundled and exposed separately, or you could just offer them within a single API offering.

Now that you have a clear idea of the sort of functionality you want to make available and your audience, you’ll want to think about exactly which resources you want to expose as well as the operations you want to expose on them. As previously mentioned, this will probably be tied to any existing contracts you have with your customers.

You should also think about any usage limits that you want to enforce for your customers. Again this may be based on customer type, with higher paying customers receiving a higher usage allowance. You might also want to assess the performance of the different API calls at this point with a view to implementing different usage limits and access rights per method. Are there any methods that are computationally more expensive than others? And if so, is this something that you want to offer with the same usage limits as for other "cheaper" calls? Another alternative would be to only offer such methods to customers on higher plans.

The next thing to think about is the authentication method that you want for your API. API security tends to be a trade off between API credential security and usability of your API. Typically, more secure authentication methods tend to be a hurdle to API integration for your customers. For a customer integration use case, a good compromise between the two would be the combination of an application identifier and a secret key to secure access to your API. Ideally, applications should be able to keep a number of valid secret keys in rotation that can be easily revoked if any of them become compromised.

How you want to publicize and document your API is an important next step to think about. Even though API access will only be available to existing customers, you should still provide a public documentation portal. This will help differentiate you from your competitors, especially if they do not provide an API to enable automation of workflows.

To reduce any friction when provisioning API access for your customers, you should automatically provide API access to any new customers on signup. This will mean that API account creation and management will be maintained on your side.

As such, any customer-specific areas such as API credentials and usage statistics should be available directly from your core product. This can be done by providing single sign-on to the provided Developer Portal or by pulling in the relevant data using 3scale’s Account Management API.

Once you’re clear on all of the above, it’s important to think about what the experience is going to be like for customers integrating with your API. Part of this will be relevant when designing your APIs and choosing an authentication method, but it’s also important to document your API in a way that allows for quick and easy testing and integration by your customers.

Some of this will be covered by providing API access credentials to your customers by default as well as providing interactive documentation for customers to test out your API. If you want to encourage customers to use your API, it’s a good idea to showcase innovative integrations in a "Customer Success Stories" section on your Developer Portal.

These are all conscious decisions that should be taken upfront when deciding to expose your API, it doesn’t mean that you can’t change them later, but it’s good to have a clear idea of the above and how you are going to implement them.

SendGrid will serve as an example to see the best way to achieve this with 3scale. SendGrid provides a number of APIs that allow their customers and resellers to automate processes and integrate with their own platform and tools. You can find out more about what their APIs look like here. SendGrid maintains multiple versions of their API. The earliest version (v1) is currently deprecated, so this example will mainly be focusing on their v2 and v3 APIs. These use basic authentication for access and return JSON data responses.

Application plans can determine can determine rate limits, which methods or resources are accessible, and which features are enabled. Every application accessing your API will be associated with an application plan.

You’ll already have two application plans created by default with your 3scale account: Basic and Unlimited. Delete these and create new ones to fit in with your plans for exposing your APIs to different types of customers, depending on their existing pricing plan with SendGrid. SendGrid provides four different pricing plans – Bronze, Silver, Gold and Platinum – each with access to a different set of APIs. As such, you’ll create matching application plans in 3scale to differentiate between them.

You’ll want to give your customers access to all of the APIs available under their SendGrid plan by default when they create an account, so leave the Applications require approval checkbox unticked in every case.

In each plan, disable any metrics that are not available under that plan. Later on, you might also choose to track usage at the individual endpoint level and create methods for that.

As for the SendGrid monthly plans, you’ll only allow access to the Web APIs for the Bronze plan. So disable all other APIs in the Bronze application plan.

To begin with, you don’t really want to place any limits on customers using your API. However, you will enforce an overall throttling limit on the hits metric to ensure your API is not brought down by large numbers of requests from a rogue app or script.

That’s the initial setup you need to do. You can always come back to your application plans to add any new methods as well as to change or refine any limits later on, once your API is running in production and you have a better understanding of your customers' usage patterns. As your API program matures, you can look for ways to use your API for upsell opportunities based on your customers' usage.