Why should you categorize your APIs?

API category cheat sheet helps you pick the right audience, business model and security for your API

Marjukka Niinioja

When starting to design new API, you should always ask first: “Who am I designing it for?” This leads to network structure, security measures the API needs to fit for. And finally, there is the question who owns the data and other resources the API is processing.

These decisions are a bit easier to make if you can categorize the API somehow. Use common patterns. Many API experts in the world have discussed how APIs should be categorized. For example, Kin Lane makes a difference between internal and private APIs. RestCase -blog author is using the categories internal, partner, and public. From experience we have to say that Kin Lane, backed up by Steve Wilmot, is actually more correct.

To help our fellow API architects, Jarkko Moilanen and I created the API category cheat sheet. The cheat sheet compares the concepts of open API, open data API, internal, private, partner, and public API.

While writing a book about API Economy, we started seeing that the terms related to APIs were not clear. In scientific research and industry blogs, the terms were used without specifying them properly. The situation was even worse when translating the terms and ideas into other languages. Or when used by the public sector, mainly the context of APIs and Open Data.

How open is Open API?

The problems start when using terms like Open API. People assume the term “open” is a synonym for 100% unsecured and free. The terms and initiatives of Open API and Open Data are mixed together. Some Open APIs are public for anyone to use (or to register for use). Some might serve Open Data, i.e. data licensed with Creative Commons (CC0) or other such licenses. Also, Open Data can be handled with other methods than REST APIs. But not all APIs are Open APIs and most Open API providers need API consumers to register.

One of the first occasions the term was used was in 1996. It was used by Sun Microsystems to describe the Java extensions APIs. The APIs were “published, uniform, open API that anyone can implement and build an extension with”. The term was later adapted and associated to REST APIs. Linux Foundation Open API initiative uses term Open API specification for describing REST APIs. Confusingly, the specification can be used to design also internal APIs.

Public and partner APIs

We have consulted and worked in both public and private sector companies, big and small. When writing the API Economy book, we were comparing notes and discussing with our Facebook community. We found out that defining your terminology is crucial at the beginning. For example, if audience was mainly from the public sector, they mixed up public API with APIs provided by the public sector. Companies were afraid to launch APIs because they thought everything needs to be public and free.

We have used the definition which seems to be most common, that Open API is either a public or partner API. An API which is meant to be used according to the terms of use by external parties.

Same as open APIs in the Java Platform, these open REST APIs are designed so that others can re-use and extend their functionality. API consumers can build new services by using these Open APIs. The main difference between public vs. partner API is who gets to use it. Public APIs can be used by anyone without having a business relationship with the API provider organization. Partner APIs are available after accepting partner or customer agreement or buying a service or product.

Internal and private APIs

An internal API is not publicly available and using it does not cost anything. An internal API may have strict identity and access management policy even for internal access. Unfortunately, internal APIs are usually very poorly secured. The only protection is often access to the internal network itself or with a simple API key shared by many.

In internal APIs, data and other resources are often different from the external APIs. A product API may be an API that provides basic product information, such as GTIN / EAN codes, product names, and features. An internal API may include profit margin or storage codes. Information not necessary for customers, partners, and especially competitors.

At least most of the internal APIs should have clear data models and security as if they were Open APIs. They should also be documented in the way there is a chance the APIs are going to be opened up someday but even now it will help internal developer experience. The reason for using security fit for public APIs is that private APIs are being used in public internet, for example by mobile applications. Kin Lane puts these APIs to private API category. Rest Case blog puts both mobile application APIs and APIs used inside internal network to the same category, internal. With so many cloud and SaaS implementations anyway, the concept of an internal network is often blurred. So, using one category may suit many companies. We put both private and internal APIs into the same category.

It’s normal for big enterprises to have lots of APIs which are not possible to be exposed to external networks. The reason is usually that of compliance, either legal or according to company policy. A typical example is also APIs of public organizations handling classified or sensitive information. Other case is that internal APIs might be provided by internal applications. Those might have commercial user-based licensing, not so user-friendly endpoint designs and poor SLAs and scalability for bigger audiences. These APIs should be treated as internal, even if the systems are running in public clouds.