Chapter 1. APIs As A Business
In the "APIs as a business" use case, your APIs themselves are your product, either creating a new business model based solely on your API or creating a new channel for an existing model.
Twilio is one of the best examples of a company that successfully sells their APIs directly as their core product. They provide APIs for text messaging, VoIP and voice in the cloud, allowing customers to easily build communication-enabled apps.
What does it take for a company to successfully expose an API as product in its own right?
1.1. API requirements
The first thing to do is review your requirements for the API before even thinking about the setup:
When looking to expose an API as a product in its own right, your intention will most likely be to turn it into a primary revenue channel. An API-driven business model may not always be apparent from the get-go, but it may become an obvious next step to open up new business opportunities. As such, you’ll need a business model for your API. This will most likely be based on number of transactions made, amount of data returned, functionality offered, and any other measures related to API traffic.
The FlightStats API is a prime example of this. While FlightStats initially offered only a set of highly popular web and mobile applications, the data powering them was so valuable that they enabled FlightStats to build new opportunities. They then spun the API off as a separate product.
Another example is the Google Maps API. Although the maps are a product in themselves and the API is free for end users, it’s widely used to add maps to a large number of third-party websites and applications.
When your API is your product, your audience is your potential and existing customers. They could be hobbyists, independent application developers, or even large organizations looking to use your API. These different sets of consumers will have different data volume needs and SLAs, which you should try to cater to.
Someone that is playing around with your API for their own personal use will probably not be prepared to pay for access. However, they won’t be a very heavy use of your API either, and they may build a cool product that showcases the potential uses for your API. You should not necessarily exclude them from experimenting with your API. On the other hand, someone who uses your API to sell an application should probably be charged for access, but they will also be a heavier user of it too.
The Google Maps API provides different "editions" based on whether the end application is publicly and freely accessible to end users or whether the application charges for usage. Other APIs will have a free or trial plan to allow potential customers to try out a limited number of calls on the API before they commit to a paid subscription with larger usage volumes.
Once you’re clear on the business model for your API and the audiences you are targeting, the next important thing to think about is the actual functionality your API is going to provide for consumers. Since it will be a product in its own right, you’ll want to make sure that the offering is as complete and attractive as possible, especially since you’ll likely be charging for access.
A good way to think about this this is in terms of the resources you want to expose and the operations you want to allow on those resources. It could be anything from airports as in the FlightStats API or nutritional data as in the Nutritionix API. Whatever the resources or functionality you’re exposing, you should group it in a way that makes sense for your business. This could be by having an API per resource type as FullContact does it, or a single API to encompass all resources offered.
1.1.4. Access control and security
The next step after you’ve decided which resources and methods to expose will be to think about the conditions under which you’ll make them available. This includes implementing some usage limits as well as potentially limiting access to some of the resources you expose, based on the customer type and their subscription plan to your API.
Yummly, the recipe search site, provides access to their recipe API under different contracts, each including a number of free calls and different functionality. For example, local caching of recipes is only available on the Prix Fixe menu.
Another example of a business model based on transaction volumes is the FullContact API, which provides contact information for people based on their email addresses or social media handles. Once customers use up the free calls included in their plan, there is an extra cost per call. Their business model is based mainly on call volume but includes a mixture of both a pre-pay model and pay-per-use.
It’s also important to think about the authentication mode you will implement for your API. Developer experience is extremely important, especially if your API is a product. As such, you’ll want to make it as secure as possible, yet painless for your developers to use. In this case, we recommend a 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, which can be revoked easily if any of them become compromised.
As your API is your product, you’ll want to publicize it as much as possible to ensure people can find out about it, are encouraged to play around with, and eventually use it. As such, a really excellent Developer Portal is a must to showcase your API.
Another important factor is providing clear, useful documentation with plenty of examples of how to use your API. Interactive documentation is a very important part of this, so your customers can try out the API without needing to write a single line of code.
You’ll also want to make signup as easy and painless as possible for any potential customers, so they can get started using your API right away. When exposing an API as a product, reducing any barriers to entry should be your primary goal.
These are all conscious decisions, which should be made up front when deciding to expose your API. That doesn’t mean you can’t change them later, but it’s good to have a clear idea of the factors mentioned above and how you’re going to implement them.
The Algolia API will serve as an example of the best way to achieve these goals with 3scale. It’s a hosted search API, which allows anyone to easily integrate search into their website or application. In this example, you’ll see how to integrate their REST API with 3scale. The API uses a combination of an application identifier with an API key to authorize requests. The response format for all requests is a JSON object. For the purpose of this example, pretend that this API currently has no authentication mechanisms in place and is completely unsecured and open for anyone to use.
1.2. Defining the API in 3scale
The first thing to do, after creating a 3scale account of course, is to define all of the existing endpoints for your API and set these up within 3scale. Set this up within the API service which is created by default with your 3scale account by going to the Integration > Methods & Metrics view in your API space.
You’ll now create all of the endpoints that you want to expose and track as methods under an application plan. Methods are the means by which 3scale tracks usage of your APIs. You can set up a method for each of the HTTP methods available on the API endpoints for your API. On the Algolia API, these are known as operations, so you can rename the hits metric to reflect this.
You also want to track how many records your API users have added to their index, as these are included and charged for as part of their plan. You’ll add a new metric called "records" to track these.
1.3. Integrating the API with 3scale
Now that you’ve created all of the endpoints you want to expose and track in 3scale and have defined how your customers will access your API, you need to set up the API gateway to easily integrate with 3scale. For this, you’re first going to use the APIcast Cloud Gateway. It’s a hosted API gateway based on NGINX that 3scale provides to test-run API integrations with 3scale in a staging environment. It will allow you to confirm that your setup is correct so far and that the endpoints you’ve entered will be tracked correctly in 3scale.
Go ahead and set up the staging cloud gateway by navigating to the Integration page. The first thing to do there is to enter your API base URL, including the port number such as 80 for HTTP and 443 for HTTPS. This will be your private API backend, which will only be accessible through the API gateway. This would typically be an internal address for the API backend. The next field specifies the APIcast Cloud Gateway location. Your calls to the API backend will go to through this host, and this will be what you hit during your tests instead of calling the private API backend directly.
The next step is to map your actual API endpoints or paths to the metrics you just defined in the application plan. Since there are many actions available on these API endpoints, you’ll create a rule for all the HTTP methods available on the API paths.
Once the setup is done, you can test the integration with the staging APIcast Cloud Gateway to ensure the setup will work in production. If all is well, you should get a green line showing a correct test integration between 3scale and your API backend.
Now that you’ve tested the integration, the final step is to set up the authentication mode that your customers will use to access the API. The Algolia REST API uses a pair of credentials, application ID and API key, to authenticate an API call which maps to the app_id/app_key authentication mode in 3scale. These parameters are sent as the X-Algolia-API-Key and X-Algolia-Application-Id headers. You can change to this auth mode by changing the integration settings and the name of the headers in the API gateway setup.
1.4. Manage API access
Now that you have the gateway set up, you can start creating application plans to allow different types of access to your API. You’ll want to look at any limits you want to enforce on the different application plans, as well as any additional pricing rules for when developers go above their plan limits.
1.4.1. Application plans
Application plans 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.
There are already two application plans created by default in the 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 users, depending on their predicted usage volumes. Algolia provides four different pricing plans – starter, growth, pro and enterprise – each with different usage limits. You’ll create matching application plans in 3scale to differentiate between them.
You want to make getting started with the API as quick and smooth as possible, so leave the Applications require approval checkbox unticked in every case. Additionally, although all of the plans charge for access, you’ll offer a 14-day free trial period, which you can configure under each plan.
1.4.2. Limits and pricing rules
To begin with, you’ll implement a limit of 1,000,000 operations per month on the starter plan and a limit of 100,000 records per month.
Additionally, for every set of 1,000 extra operations, you will charge 0.08 USD. For each 1,000 extra records, you will charge 0.80 USD, as per the current Algolia pricing plans. You’ll implement this by adding multiple pricing rules, so once you go over the call limit, call 1,000,001 will be charged at 0.08USD, while the next 1,000 calls will be free, and so on.
- From 1,000,001 - 1,000,001 operations: 0.08 USD
- From 1,000,002 - 1,001,000 operations: 0 USD
- From 1,001,001 - 1,001,000 operations: 0.08 USD
Similarly, you’ll implement similar pricing rules for the records metric.
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 change or refine any limits later on.
1.5. Engage developers
Now that you’ve set up some limits, the next step is to set up your Developer Portal, so customers can find out more about the API, get their API credentials, and monitor their usage.
The final things to set up on your 3scale account are all around customizing the Developer Portal to fit your particular needs and so that it conforms to the look and feel of your product branding.
You can do this through:
- Setting up a custom domain for your Developer Portal such as developer.algolia.com.
- Setting up an API contact email such as firstname.lastname@example.org for emails from your 3scale account to your API consumers.
- Customizing the Developer Portal so that it matches the look and feel of your brand.
- Edit the email templates to tailor the messages you want to send to your customers.
- Using liquids to control the information that gets shown to different customers.
- Adding a favicon
For the favicon, the path has to be different than the standard /favicon.ico, as this is already taken by the default 3scale one.
You need to upload your favicon into the 3scale CMS by creating a new file. In this, place it in the images folder and call it icon.ico. You’ll then refer to it from the main layout with the following snippet placed in the head element, as below:
<!-- Favicon --> <link rel="shortcut icon" href="/images/icon.ico" type="image/x-icon" />
You’ll also want to set up some interactive documentation (ActiveDocs) so your customers can explore the API without needing to write any code. If you already have a Swagger spec for your API, navigate to the API service you want to work on and go to the ActiveDocs section, create a new spec and paste your Swagger spec in.
1.6. Exposing the API
Now that you have integrated the API and customized the Developer Portal, start thinking about attracting users to the API. Orgainizing a hackathon can be a good idea to create some buzz around your API and potentially surface some interesting use cases that you may not have thought of. It can also give you an opportunity to gather direct feedback from potential users of your API about its functionality and usability.
Other than that, from a 3scale setup point of view, you just need to ensure that users are able to sign up to your API freely and can get up and running right away. As such, you’ll need to ensure developers are allowed to sign themselves up and that there is no account approval required (the default settings in 3scale).
You’ll also need to make your Developer Portal public by removing the access code.
That’s all regarding the integration and setup of your 3scale account. However that’s by no means all that 3scale provides. Once your API has been up and running for a while, the analytics module can help give some insight into the usage patterns for your API, which of our customers are most engaged, as well as which are the busiest hours and days for the API. You can read all about how to make the most of the 3scale Analytics here and here.
What are you waiting for? If you haven’t already done so, create your own free account now and give it a go.