What Does Open Mean in the World of APIs?
11 Jan 2021
The word “open” gets thrown around so much in the API space I find myself needing to regularly ground myself in what it actually means. It gets thrown around in so many different ways that I find eventually I start to believe the bullshit and regularly have to pause and recalibrate. It is one of those words that has been captured and used by people looking to manipulate the space so often it often means the exact opposite of what we all think it means, but it is also such an important word that I think we have to fight to keep it in our vocabulary. I feel like I am perpetually fighting with some invisible force over one of the front doors to the house we all live in, and I am determined for the door to not get completely shut, and I have to make sure the door actually ends up go where someone expects when they do open the door.
Let’s begin by actually taking inventory regarding the many different ways people use the word “open” to describe the world of APIs. Gathering all the ways it gets wielded in service of publishing and consuming APIs. Some of the ways in which it gets wielded are good, and some of them are bad. At this point I am just looking to be able to see the spectrum of use, and I am not looking to entirely pass judgement on anyone who uses it in specific ways. Here is the laundry list of ways “open” is wielded that impact the landscape I pay attention to on a daily basis, and have been helping shape for the last decade.
- Publicly Available - Open means something is available to anyone in the public, allowing them to use an API, and any resources around them.
- Access - An API or supporting resource is open for access by the public or the developer community in general, making it something they can use.
- Business - Stating that a digital resource is open for business, and consumers can purchase or be purchased in an ongoing way using an API.
- Source - Focusing on the code behind or in front of an API, and acknowledging that APIs are built upon and evolved using open source code.
- Specifications - Applying to API specifications like OpenAPI or OpenID, and ensuring that the specs we leverage across our APIs are always open.
- Standards - Looking at specific industries and business sectors, and ensuring that the standards that are in place for industries are available openly.
- Licensing - The word open is regularly applied to the legal side of the API world, which leverages the lawyers to loose up or tighten down the open screws.
- Exploitation - Many APIs and the platforms they reside upon are open for exploitation, or possibly open to the exploitation of API consumers and end-users.
- Discovery - Can I find the API? Is it easy to discover and explore for any potential consumer, and able to find via common, well-known channels.
- Portal - Is the landing page or portal for the API accessible to the public, partners, or a private audience allowing them to learn about the API.
- Documentation - Is there complete, up to date API documentation for the API that is accessible, providing an honest and open view of what an API does..
- Paths - Do developers have access to all of the paths that are available for the API made available, or are there hidden paths available behind applications.
- Enumerators - As a developer do I have access to all enumerated values that can be used for an API, and is it clear for me the values an API will accept.
- Read / Write - Is an API just GET access, or can developers POST, PUT, and DELETE resources, ensuring the surface area of each digital resources is open.
- Media Types - Are there standardized media types in use for each API response from an API, or are they cryptic, closed, and unique formats that aren’t open.
- Sign-Up - Is the signup for the API self-service and allows developers to easily access and complete, and something that is open for all types of consumers.
- Sign-Up Scope - How much information is required from developers to be able to get access to an API, or will I need to share my entire life story to get access.
- Sign-Up Approval - Do developers have to wait for access and be approved before they can obtain keys to access, making open very subjective in reality.
- Authentication - What is involved with authentication, and is the technical bar set too high for some developers, compared with the digital resources.
- Design - Is an API intuitive, easy to understand, and accessible to everyone using it, or is it cryptic and hard to learn, and only understandable by a few.
- Consistency - Are API patterns consistent across all APIs, alleviating extra work to put any of the APIs to work, or is each part some new to have to learn.
- Rate Limits - What limitations are placed upon developers access to an API, limiting the usage of any individual API, putting full usage out of reach.
- Rate Ceilings - Are there not just limits, but entire ceilings I cannot overcome at any point in development, rendering APIs not open to growth and scale.
- Sandbox - Can developers access all APIs in a sandbox, so you do not have fear of only working with live data, restricting openness due to only a production state.
- Status Codes - Are standard HTTP status codes returned allowing for understanding what each response means, leveraging the shared open meaning of the web.
- Error Messages - Are there standardized and coherent error messages associated with each API, making things understandable, making failure more open.
- Availability - Is there large periods of time when the API is not available for use within applications, leaving a platform only open during specific times.
- Reliability - Is the availability of the APIs reliable, making it something developers can count on and put to use, and open in a reliable way across consumers.
- Performance - Is the API performant and something you can actually receive responses in an acceptable time frame, and open to operating at speed we need.
- API License - Is the interface for an API openly licensed so I can confidently integrate and use in my code, ensuring the surface area of the API is truly open.
- Data License - Is data returned as part of API responses licensed in an open way allowing developers to use, keeping the data exhaust involved as open as possible.
- Code License.- Are the cod made available as part of an API openly license for wide usage within applications, keeping backends and frontends as open as possible.
- Tooling - Developers need to have access to the open source tooling they need to get their immediate job done, and meeting their day to day needs for this to work.
- Usage Costs - Are the costs associated with usage of an API within reasonable ranges for developers, leaving it open to smaller players as well as larger ones.
- Cost Increases - Are there regular cost increases that might move an API out of range of access, pushing the boundary for what is open out of range for some.
- Support - Can I get access to support when it comes to accessing and using an API, and is a platform open to supporting it’s consumers at the levels needed.
- Communication - Is there anyone home behind an API helping communicate about what is happening, providing a regular open heartbeat for consumers to hear.
- Feedback - Are API operators open to feedback, ensuring that consumer feedback is a regular part of API operations, leaving the road map open to feedback.
- Road Map - Is there any visibility into what the future will hold when it comes to the development road map, providing more openness to what the future holds.
- Ideas - Does a platform foster the open creation, development, and cross pollination of ideas across the platform between API publisher and consumer.
- Censorship - Is data or content actively being filtered or censored as part of API operations, and open are the filters that are in place on API infrastructure.
- Terms of Service - Is there a TOS in place that governs the API, and what are the constraints in place, and how open is the language used for terms of service.
- Service Level Agreement - Are there any guarantees In place that govern the availability and costs associated with an API, being open about exceptions.
- Regulations - The constraints of regulations will define how open or closed a specific business sector will be, setting the tone for open across APIs in that space.
- Auditors - The transparency, openness, and observability of regulatory auditors will define each business sector being defined by the coming API regulations.
- Investment - The accessibility of investment will continue to define the API space, opening up the building of the next generation of API instructor and applications.
This reflects the “open” knobs and dials that get used to control the open or closed nature of APIs we build and use each day. Open is a dance between provider and consumer and end-user when it comes to API, but also across providers and consumers within a specific sector or industry. In order for “open” to have meaning or not is about the trust that exists (or doesn’t) within a space. How a platform dials things in along these lines will define how open or closed they are, and this playing out across all the players within a sector will determine how open or closed the entire industry is. Each of these knobs and dials will reduce or introduce friction across the API factory floor for an enterprise organization, as well as within the industries they operate within. It represents where we can individually make a difference, as well as collectively, to put the open in not just APIs, but also across every part of our world that is being touched by technology—which is pretty much everything.
Ironically “open” is not a boolean in the world of APIs. In my experience the APIs that declare themselves “open” usually aren’t. However, I don’t want this to bias me, and I want to still believe that when folks use the word they have the best intentions. I want people to feel like they can use it without being immediately suspect. However, I want people to understand that the usage of this word comes with responsibility. That you will have to prove yourself. That there is a certain amount of accountability required here. This includes myself. I like to use the word open to describe a significant portion of what I do in the API space. I am an open storyteller. I am an open evangelist. 75% of the APIs I develop I would call open. I believe in the importance of open in the API space. It is why all of this works. However, I also understand the importance of doing some things in a proprietary or closed way, as long as it is done deliberately and for the right reasons. I believe in the role that open APIs plays across all of these levels, but I also understand that open is just a reflection of what is closed. I don’t see open as good nor bad. I see open as a meaningful way in which we can leverage the web to accomplish our individual and collective objectives and missions. I also am very skeptical of anytime open gets wielded, and will keep working to define what it means and doesn't mean as part of the API economy.