5 Reasons Your API Is Still Private

This guest post comes from Jason Harmon, contributor at APIUX.com, API Architect at uShip, and co-organizer of the Austin API meetup. He has worked in software architecture and Integration at a variety of companies, and evangelizes high-quality API User Experience and adoption.

Software engineers all over the world are working on APIs every day, at companies of all sizes and shapes. Nearly all of these APIs are never seen by the public. Only heavily vetted partners will ever have access; sometimes endpoints are purpose-built for specific integrations. It's easy to forget that private APIs like this are, in fact, the norm.

Developer teams in this position are often confused and frustrated by the fact that these APIs seem like they'll never be made available to the general public. Building a system that is capable of rapidly integrating your capabilities, but never telling anyone outside of your company and closest partners, can feel like watching opportunity slipping away.

There are times when a company’s potential in the future API-driven tech economy is at risk. There are other times when a company’s livelihood is at stake because its Platform’s integration capabilities are overexposed. Putting together the right strategy requires identifying the risks and needs of your business, and making smart moves to take things in the right direction.

Most of the challenges listed here presume that there are budget constraints which make it hard to convince management that an open API is the right approach. As such, many of the solutions presented here are simply about how to get the ball rolling. Bootstrapping is the hardest part of getting started. Once positive results come in, justifying more dollars to mature your API platform gets a lot easier.

If you’re not budget-constrained, I presume you’re reading about products or staff to buy into, rather than a blog post like this...or maybe what kind of private jet you are buying next.

Competitive risk

There are industries in which the fear of exposing proprietary knowledge is often too great. Allowing access to data or business logic that your competitors want to reverse-engineer could put your competitive advantages at risk. However, there are times when companies are so risk averse that they do a disservice to their greatest opportunities by keeping their infrastructure blocked off.

Discussions about the real value proposition of your company over competitors can help you focus on the portions of business logic or data that are the most sensitive in nature. Identify the contentious areas and stick to the items that are the lowest friction to get started. Push for the most agreeable items to be opened as a competitive advantage. That is, unless your competitors already have an API for the same thing…in which case your API may be justifiable as competitive parity.

Increased costs

Providing a Developer Portal to project a well-defined platform means that a company has to invest in building a new public-facing layer. The costs of building this from scratch, once quantified, can be overwhelming—it’s not easy to learn the discipline of building APIs that developers love.

Look into tools that outsource this capability as a service. Emerging tools like apiary.io, apihq.com and mashape.com provide a cloud-based service to expose your API to the public with a documentable, explorable interface. Depending on your budgetary constraints, fighting for developer Resource time (or hiring more developers) may be a much greater challenge than justifying an inexpensive service.

There is certainly more to growing a mature program, but a well-documented, explorable API is probably the highest-value component. If you can swing an API-experienced technical writer (even on contract), this role can add tremendous value in communicating your technology effectively. Allowing developers to explain how they built the API can be a formula for disaster from the API consumer’s perspective.

Taking it a step further, utilizing an API management provider, such as 3scale, Apigee, Layer 7 or Mashery can significantly cut the costs of building from scratch. API management providers bring their own host of costs (although some have free tiers for a surprisingly large call threshold), including implementation time and an up-front or monthly bill, but can sometimes fit into the budget better than new staff or dev time.

In addition, most of these vendors are very focused on education and assistance tools to help teams adapt to API-driven strategies.


Many companies invested heavily in SOAP-based technologies throughout the last ~15 years. Opening up this approach in a well-marketed strategy would be very unlikely in most situations. Most API clients are no longer interested in consuming SOAP web services. As such, this is another cost and delay. More and more tools are enabling this transition, but it won't happen overnight, nor smoothly.

We all want to build a rock-star team and build REST APIs from scratch that would make Roy Fielding cry, but that’s not always among the highest business priorities. However, if you want to project an image of modernity and don’t have the time or budget to write new code, there are some configuration-based options out there. In the API management space, players like Layer 7 and Apigee have SOAP-to-REST conversion tools. These adapt a RESTful interface on top of your existing SOAP infrastructure, to cut down on developer cost/time. In addition, there are many other features that can make API management tools very attractive for opening up your business capabilities.

Business Focus

Integrating with anxious third-party developers doesn’t make the priority list for many management teams. It's arguable that at some point, reducing the priority of open APIs will be an inadequate business strategy. However, in the current environment, oversight of open API strategies is all too often the case.

Look at the competitive landscape or similar industries to find examples of open API success stories. With a few searches or tweets, you can probably get first-hand testimonials about how the open API approach has fundamentally changed businesses. Simply put, engage business management in terms of how API-driven strategies can make them more competitive.

Another approach is to challenge your developers to create sample applications based on internal-only APIs, perhaps during internal hackathons (yes, you should be having these). This can provide a means for discussion on the serendipitous events than can occur when external developers get a chance to utilize your platform’s capabilities.

Sometimes business leaders know there is a need for open APIs, but they need extra focus on the issues required to expose their capabilities. More companies are starting to define an API product manager role, which can provide an organizational hub where these issues can be solved.

Marketing and Support

Opening your doors to developers and integrators is only the first step. To make the investment in the approach worthwhile, it takes significant marketing coordination. Most marketing departments don’t have the education or ability to adapt to this type of messaging. As such, hybrid marketing groups that cross the bridge between IT and business development might need to be formed. For traditional marketing management, this can be an intimidating concept.

Additionally, there are often specific staffing needs for roles such as "developer advocates” or “evangelists”; somebody to help API consumers succeed, and relay feedback from real world developers and early adopters.

Not every open API strategy requires this level of coordination, but putting up a developer portal and expecting anything valuable to come from it is a failed strategy.

Look for industry contacts who can help put the word out about your new open API program through Twitter, LinkedIn and other communication channels such as blogs. Provide business-centric descriptions about the capabilities of your APIs to give business development and marketing groups a chance to describe things on their own terms in their communication channels.

Identify the unique developers on your teams who have the right social and technical skills, as well as the enthusiasm to evangelize your platform. Dedicate a portion of a few developers' time to attending conferences and trade shows. This can sometimes be considered training costs, because your devs will learn about industry perspectives when they attend these events.

Sales and marketing teams are likely to want some of your time to help them communicate the capabilities that your platform brings in technical conversations at these events. The feedback your evangelists provide from real-world developers will need to be highlighted and valued by sales and marketing.

You might find that the same individuals can help with supporting API consumer questions, although it might be different developers who can contribute to that effort.


To better understand the non-technical issues in API implementation, I recommend watching the talk “APIs are not a technical challenge” by Andreas Krohn at the September 2013 Nordic APIs conference. Krohn does a great job explaining the soft skills required by developers to help their businesses understand the benefits of open APIs.

Once these items have been addressed, the next challenge might be how to build a business model around your API. I recommend watching the comprehensive talk presented by John Musser, founder of Programmableweb, and currently CEO of API Science, titled “20 business models in 20 minutes.”

The API economy will be powered by technology, but the decisions to get involved will be made by business leaders. Overlooking this fact guarantees one of two outcomes: no involvement, or failed involvement. As builders of APIs, we must remain vigilant to create the best-quality, easiest-to-use APIs. Sometimes, that can mean being technically prepared to open up our platform with APIs. However, we must balance our technical work with efforts to help the business side understand the challenges and opportunities of the emerging API economy.

Be sure to read the next Tools article: Twitter Engagement Part 1: Moving Beyond Bulk Following