Across my various clients, I see a common trend – private APIs outnumber public APIs at least 10-to-1. Some private APIs are for internal use within the corporate firewall. Others are exposed to the world but only for private use from mobile and web applications.
Over time, some of these APIs become candidates for partner or public APIs. But, we shouldn’t assume our private APIs are ready to be made public. Let’s explore the 5 key things we must do before taking our private APIs outside the firewall.
1. Perform a thorough security review
I get it. Time is limited. Designs for internal APIs have to be accelerated, often at the expense of a thorough design and security review. Once we go public, however, the absolute first thing we must do is to revisit our API designs and see where we need to make some key changes.
Tinder learned this the hard way. Forbes provides a great overview of what happened when Tinder made their private mobile API available for public developers:
Unfortunately, two of the aspects responsible for the high quality of its user experience also potentially put its users at risk for stalking by predators with a modicum of hacking ability. First, the location processing takes place on the client side, so actual location data for matched users in a 25 mile radius is delivered directly to the user’s device, unmediated by the Tinder servers. Second, that data is incredibly accurate, within 100 ft. or less.
In short, Tinder failed to review the data returned in their API payload. Instead of the API sending approximate location data to the front-end mobile app, the mobile app received exact latitude/longitude coordinates for matched users from the API. When the API was made public, this was never adjusted, thereby exposing matched users returned by the API to a multitude of risks. This security flaw has since been resolved.
Summary: Don’t assume your API was designed to be used outside of the original use case. Take the time to review every endpoint to ensure that the data being returned is appropriate for developers outside of the organisation.
2. Improve your API documentation
When APIs are private, many of the details are transferred by word-of-mouth. Do you have a question about how one of your private APIs work? Just walk over and ask one of the team members. Developers are nearby, either in the same office or on the same internal message channels. When taking a private API public, this is no longer the case. Better API documentation is required.
A few of the questions that your documentation needs to answer include:
- What capabilities and features does your API offer?
- How does your API’s authentication and authorization work?
- What endpoints are offered and what are the request/response details?
Summary: Be sure to revisit your API documentation strategy to ensure that you are able to address these questions for API consumers just getting started with your public API.
3. Write usage examples
Private APIs are often consumed by applications for which you already have the source code. Therefore, examples of how the API is used exist already. Once your API goes public, your API consumers will need examples to understand how to use it.
Examples may use a combination of cURL and code snippets for the top 3-5 programming languages of your target audience. At a minimum, they should demonstrate how to accomplish simple tasks based on your API capabilities.
I also strongly recommend demonstrating more complex examples alongside the simple ones by building demo applications, allowing developers to gain a deeper understanding of how to connect API calls together to tackle larger solutions.
Summary: Add code samples and demostration apps to help developers integrate your API faster. You can learn more about how to incorporate code examples into your documentation from our recent article, Great API documentation requires code examples.
4. Install rate limiting and endpoint protection
Mistakes happen. Developers may introduce a logic bug that causes their code to hit your API way too often. Or, perhaps a developer has some ideas on how to take down your API.
Before taking your API public, install an API gateway or management layer. This will ensure that rate limits are applied to incoming requests, protecting your endpoints from accidental or malicious spikes in usage that may result in poor performance and increased cloud infrastructure costs.
Summary: API gateways and management layers protect each of your endpoints from unauthorized use and malicious attacks, allowing your API to offer tiered access on an authorisation or subscription basis. Whether you are taking your API public or maintaining a private API, installing an API gateway on-premise or in the cloud should be one of your first steps.
5. Define KPIs and usage reports to drive improvement
Once you release your public API, you will need to ensure that your public API meets your business and technical goals. Many API gateways and management layers offer analytics support to track usage. These metrics can be used to assess your key performance indicators (KPIs) that business stakeholders use to measure success. They will also ensure your infrastructure is performing within expected parameters.
Summary: Using your API product strategy as a guide, start by selecting a few key metrics to track. Then layer new or different kinds of metrics to assess the health of your business. Work with your product management and executives to identify both the business and technical metrics necessary to monitor the health of your new public API product.
Taking your API public requires planning
As these 5 items point out, taking your API public isn’t as easy as changing a firewall setting and allowing access to your internal APIs. It takes planning and consideration about security, developer experience, protection, and performance. Be sure to develop a plan for rolling your API out to partners or public developers, to reduce the risks associated with opening your API outside of your organisation.
Ready to launch your API to the world? Tyk’s open source API gateway and management platform provides all the features you need, including API security, rate limiting, detailed API analytics, and a developer portal. Get started now – you’ll be managing your APIs in minutes.
