Considerations for Private APIs

In the past, we've talked about the nature of private APIs (those interfaces that are built primarily to serve an organization's own projects rather than to fulfill the needs of others).  But what are the specific challenges and architectural decisions that need to be made when implementing a private API?

First and foremost, an API can't be considered private if it is open for widespread public use, right?  A simple way of keeping an API private is to host the interface on a public network without explicitly advertising or documenting its existence.  This can work well initially but may lead to problems in the future. If your service is valuable enough that others want to get their hands on it, even an undocumented, unsupported, private API can easily end up becoming a depended-upon API for application developers, resulting in an outcry when the API publisher has the audacity to modify or retire its own service.

A better approach is to provide access control at run-time and restrict usage of your API to a few known parties. There are a great number of methods for protecting access to internal resources but the best ones are those that achieve a balance between ease of implementation and resistance to infiltration. Security at all costs can greatly increase the complexity of an interface and – in turn – the time required to complete the projects that depend on it. Instead, we need to implement access control that is practical. Thankfully, security protocols like SSL, HTTP Basic authentication and OAuth 2 are great for providing the basic level of access control needed to make it difficult for outsiders to use a private API. Bear in mind that there is much more to API security than simply validating identity but this is the minimum level needed to ensure a degree of privacy.

Although a private API's developers are generally known to the publisher, the best private APIs utilize API portal components to provide self-service registrations and integration to their private developer communities. This can greatly reduce the friction involved in getting API integration-based projects started and reduce the overall project costs for B2B and mobile-based initiatives. In fact, many of the lessons of simplified design, documentation and administration learned from the public API world can be directly applied to private API management. While the ultimate goal may be different (driving efficient API usage for private APIs rather than far-reaching adoption of open APIs), the ways of getting there are largely the same.

A unique characteristic of private APIs is the need to manage groups of developers. Unlike the public API space, private API publishers will often define out of band contract terms before offering up a quick self-service integration mechanism for that team. This type of group-based role definition is particularly common in integration projects that occur between organizations and can stretch the limits of API portal software that has been built primarily for open API use. Ideally, an API portal should at least be capable of managing developers within groups, communities or organizational affiliations as part of the self-service registration process. Even better, the portal could  provide capabilities for managing whole communities as separate domains within the same infrastructure.

Designing a private API certainly requires a different perspective but the good news is that much of the knowledge around public API design can be directly applied to interfaces you want to keep secret. Of course, building the management and security capabilities required to expose the API to your trusted parties can be daunting but that is why a great API management portal and gateway combination can save the day.

The Author

Ronnie Mitra

Lead Designer

Ronnie Mitra is an expert in enterprise development and integration who leads the CA Technologies API Architecture and Design Practice across Europe. In this role, Ronnie helps companies leverage their burgeoning API potential. Before joining CA, he worked at IBM where he held the worldwide leadership role for WebSphere connectivity products.

Related Articles

Microservices and APIs
API Strategy

Microservices, APIs and Innovation: The Power of APIs

Explore the role APIs play in empowering teams and enabling organizations to innovate.

Mike Amundsen on May 24, 2018

API Strategy

I am joining the API Academy

I'm excited to be a part of such a great team. Here's why.

Mehdi Medjaoui on Oct 3, 2017

API Economy
API Strategy

The Three Drivers of the API Economy

Discover the three main drivers of API strategies today

Erik Wilde on Apr 11, 2017

Join the Conversation