APIs are as vast and varied as the systems that depend on them; while some systems may handle client data, payments, and collaborative research, other APIs may handle less important data such as social media and image sharing.

Due to the variations in application and usage, APIs face a unique set of considerations and issues arising from their availability that no other system faces – the difference between having an API for public consumption or one intended for internal use, in certain circumstances, can mean the difference between megalithic success and catastrophic failure.

Understanding the specific business objectives involved in making your API private or public is paramount. Today, we’ll be identifying the difference between Public, Private, and Partner APIs, and when each type makes sense in different scenarios. We’ll also tackle a few examples of failure in API restriction and documentation, as well as a few success in design and development.

Differences In API Approaches: Private, Public, & Partner APIs

When considering the interaction between APIs and their intended markets, there are three general approaches to licensing and availability.

Private APIs are APIs intended to streamline internal operations, translating calls in a hidden way. While they may be documented, this documentation is largely limited and is meant for internal purposes only. Development is handled entirely by the creators of the API, and no derivations are allowed. While this type of development and implementation cycle can be very effective in creating and maintaing accelerated growth, your API is limited by what you have designed it to do — your API will not evolve with the times and needs of the marketplace unless you specifically force it to, which can be both time and money intensive.

Public APIs are APIs that have certain public access, working more transparently and allowing other users, services, and systems to tie into parts of the underlying interface. These APIs are usually heavily documented, as they will be used publicly by developers to utilize the API for various services. For some very transparent Public APIs, “Forking” the API — creating new derivations of the API — is open to any who wish to do so, making it evolve organically. This is rare though, as most public web APIs are still closed-source, allowing a company to maintain full ownership. In general, Public APIs allow a third-party developer ecosystem to be created with your data or services, an organic evolution with new posibilities and services, potentially resulting in explosive and sustained accelerated growth. The downside of a Public API is that it could decrease the value of your main distribution channels, and, in some situations, direct monetization opportunities that would arise from a more locked-down Private or Partner API.

Partner APIs are B2B APIs that are exposed through agreements between the developer and the client, outlining the application and use of the API. Documentation is usually thorough, but only for those interface calls that will be used by the business as defined in the contractual license; other functionality is locked down, undocumented, or requires authorization and authentication to utilize. Such an API is highly effective and can be extremely lucrative. Derivations can be contracted out, but all of the API development is synthetic and directed rather than organic.

Considerations and Caveats

What, then, is the choice that drives one business to the Public API model, and another to the Partner API? When considering the type of API licensing and availability, several considerations should be made at the beginning of the API Lifecycle, as they can fundamentally change the approach to the development of your API by changing the methodology of implementation.

Firstly, consider the nature of the data and systems that your API will reference. When designing an API that taps into secure, personal data, such as social security numbers, payment records, and general identification services, the amount of security needed for your API shifts the balance drastically towards a consideration of either private or business-to-business licensing.

This is largely due to the vulnerability of public-facing API code and documentation. Think of your licensing as a suit of armor. While plate armor is heavy and makes movement hard, it is extremely secure. Leather armour, on the other hand, is extremely light and flexible, granting extreme agility. Your licensing is much the same — Private APIs being plate armor, and open-source Public APIs being leather. Business-to-business Partner APIs are like chain mail— somewhere in the middle in terms of granting agility and protection. While the use of Public APIs can be somewhat controlled (or tanned in the spirit of our armour metaphors), they will never be as secure as a closed-source and plated Private API.

Secondly, consider the amount of upkeep you wish to perform. All API types can have arduous, long, and expensive development cycles, relying on proprietary systems and interfaces. Costs and resources may be extended for Public APIs in order to maintain public-facing developer portals and upkeep external support systems such as marketing channels, hackathons, and other API product operations.

Finally, monetization should be considered. While closed-source Private APIs can be monetized through improved operational efficiency and content promotions, Partner APIs can be licensed at a fee for direct revenue; open-source Public APIs can also be monetized through the direct sale of data and other methodologies.

So Where Is The Middle Ground?

So where, then, is the line? What is the ideal combination of security, access conditions, and monetization for your specific situation? Functionally, your API should only be as public-facing as it is required to be by its functions, its designs, the limitations of your business, and the objectives of its implementation.

For example, if one were developing an API that would use data provided by third party vendors to collate data for analytics, what would be an appropriate amount of exposure? Given the nature of the data, and the security requirements likely put in place by the vendors, a Partner API would be appropriate; after all, other partners will have to tie in to your API to deliver data, and you will need to provide a certain amount of documentation for that to occur.

Conversely, if we were designing an API that delivers social media or RSS feeds to a user, what would be an appropriate type of exposure? In this case, because the data is entirely open, is not tying into systems, and utilizes public data, a Public API is appropriate. In this scenario, open-source is perfect, as it allows the maximum number of users to utilize the API and improve it over time, utilizing collaboration services like GitHub and Bitbucket to revise and fork the API into bigger and better systems; if the API were ever to deal with confidential data, third-party vendors, etc., this would change, but as it is, the level of exposure is absolutely appropriate to the use-case scenario.

Your considerations should be a broad spectrum of monetization opportunities, upkeep cost, and more, but in terms of security, developers should always follow the rule of simplicity — expose only what needs to be exposed.

Real-World Failure

In late 2014, social media giant Snapchat faced a large security failure in their undocumented API discovered by security firm GibSec. Because of the nature of their API — B2B and semi-private — third party apps were able to connect to the service in such a way that the servers and systems connected were made vulnerable.

One vulnerability in the API, utilizing an authenticated, authorized call to the /ph/find_friends request, opened the Snapchat system to hackers in a way the developers never even considered; after calculating the number of Snapchat users and the amount of requests that could be completed in a minute, GibSec estimated that all 8 million users could have their personal data, phone numbers, and even images scraped by an average server in approximately 26.6 hours (which was a conservative estimate).

So how did the API fail? Functionally, there was a mismatch between the documented access and the actual restrictions on those features. While the API was designed to be a Partner API, it was documented with these partners in the same way a Public API is.

While it’s true that if the API were more public vulnerabilities could have been detected and fixed before it became a larger issue, the fact of the matter is that the API did not need to be open in the first place. By not properly managing the data and allowing unvetted companies and developers access to the Snapchat API and internal systems, Snapchat was unnecessarily exposed and made vulnerable.

Additionally, the fact that Snapchat did not adhere to a singular approach was extremely detrimental. If the system were 100% internal, a team would likely have been monitoring the API, and would have come across the issue far before it was actually discovered. If the API were B2B alone, the vulnerability would have not been an issue, as the calls would have required authentication and authorization far above that of a normal user, preventing the leak from occurring. Finally, if the API were completely public, it is likely that the vulnerability would have been discovered earlier, perhaps through the efforts of so-called “white hat hackers” testing vulnerabilities for fun or by common usage.

Neither plate, leather, or chain, the Snapchat failed because it was occupying a strange space between API approaches. Since the necessary preparation in defining the API premise was not performed, API access was not well-maintained, leaving a gaping vulnerability present.

Two Real-World Successes

Lego

LEGO, the famous brick-toy company from Denmark, has spent most of its existence making sure that their toys were fun, creative, and safe. As LEGO launched into the modern era, they began to seriously consider developing their own API, focusing largely on extending that creativity and security into the world wide web. Below, Dennis Bjørn Petersen discusses the development, challenges, and successes of their closed-source Private API.

The success of the LEGO story demonstrates exactly why an API needs to have determined limits when it comes to source disclosure. Due to the nature of the data LEGO is handling, and the young age of its target audience, the API that was developed was locked down in a Private API environment. This development, isolated from exposure, made sure that the system was safe and effective.

Carson City, Nevada

Another great API success story is that of Carson City, Nevada. Whereas the success of the LEGO API was due to its closed nature and purposeful design, for Carson City, the integration of an API utilizing both the assets of city infrastructure systems and the collaboration of various private and public partners demonstrates success in the Partner API space.

When Carson City set out to design their smart city system, they formed a partnership between the Carson City Public Works Department, the citizens of Carson City, and Schneider Electric. The city packaged open data generated by various smart devices around the city into a Partner API designed specifically for optimization, reporting, and planning. Carson City officials were able to accomplish some pretty amazing things, converting their city into a true smart city. According to the final report filed by Schneider Electric, there were many benefits:

• Management of the city’s power plants was streamlined
• The water management system was drastically optimized.
• Maintenance operations were cut from a 5 to a 4 day week.
• Staff hours were saved in the form of reduced “drive time” between locationsBy designing their API to function specifically for the purpose intended — in a limited circumstance with secure, defined, and vetted partners — Carson City set themselves up for massive success with real lucrative results.

Conclusions

Contemplating the licensing, accessibility, and fundamental availability of your API should be your first step in the API Lifecycle. The complexity of situations presented by your choice in this initial step can impact your APIs success, longevity, and usefulness. While security is, as always, a chief concern in initial considerations, the monetization of your API, the availability of the system, and the user-friendliness of that system as a whole is dependent entirely on the approach taken.

Let’s review the benefits of each approach:

• Leather Armor Public APIs can have a wide adoption rate and potential to spread brand awareness.
• Plated Armor Private APIs allow for increased security and internal management. Keep it secret, keep it safe.
• Chain Mail Partner APIs are perhaps the Goldilockian Mithril for your B2B integration situation, allowing a mix of both security and defined partnership potential.

More than any other consideration, your particular purpose for developing an API will determine the choice you make. Now enter the API economy brandishing the armor of your choosing, and happy requesting!