I’m rarely surprised by, but still often caught off guard by the subtle ways in which power asserts itself when faced with change the introduced by API projects. In my 30 years as a database professional I’ve seen numerous overt, covert, and subversive ways in which existing holders of power (data), but I often still get blindsided by the creative, and subtle ways in which folks defend what they already have, and work to keep things from changing.
While doing unfunded work to define industry level API specifications, and help move forward the API conversation in multiple industries, I’ve been encountering two pockets of friction I want to understand better, so I can develop some sort of grease, that might make things smoother. There are two main pockets of practitioners in this setting, implementors (those you publish an API), and vendors (those who currently sell solutions to implementors). My role in any industry as the API Evangelist is to help ultimately define and showcase healthy, common API definitions, that can be reused across the API lifecycle–from design to deprecation.
The Vendor Question Trying to understand the culture, and motivations of any SMB, SME, or enterprise is often a full time job I do not have the time or resources for. I work pretty hard to understand any of the key players in any industry being touched by APIs, but will still have much I need to learn. One thing I do know, is that I should never take a company for face value, because behind the mask there is always much more going on. Honestly, APIs are actually a pretty good barometer of what is going on behind the scenes, something I don’t think some API providers fully grasp before they decide to jump into the API game.
The most obvious thing a vendor in an industry will do is ignore you. When approached about participating in discussions around a common API definition, they’ll just not return your emails, tweets, and other front door solicitations–this is fine, many are busy, or just very confident in their place within an industry. Next, you’ll get the folks who will join you at the table in some capacity, or other. Most are busy, and will have limited time–that is understood. What I am trying to understand is their behavior once they are at the table, because I feel that many of them aren’t actually at the table to participate. They are at the table to be present, influence the discussion, which often times might mean keeping the discussion from moving forward at all.
As someone who does not have a job, and regular paycheck, I’m fascinated by the amount of time that can be wasted by SMB, SME, and enterprise folks when you are trying to talk about a common API definition. I don’t care if you have a machine readable way to define the conversation using OpenAPI for the API, and JSON schema for the schema, folks will find a way to dance around any clear process and framework. The first hurdle is always learning to speak OpenAPI and JSON schema, and helping vendors become fluent in OpenAPI, allowing conversations be anchored to specific APIs, paths, headers, parameters, responses, and schema. This is no guarantee of forward motion, but it does help keep things focused, and potentially productive around establishment of a common API contract.
With vendors, all roads lead to their products, and their solutions. The question is always how we can best get them to invest in shared public API infrastructure, over routing all conversations to their platform, on their roads. Money and investment is always the quickest way I see vendors take control of conversations, and route things in their direction. Let’s work on this project, or this infrastructure involving a specific implementation of our choosing, and we’ll move forward the API standards conversation in those terms, and within the context of our choosing and funding. Sure, some environments might actually be conducive to moving things forward, but I think we need to think deeply about how we decouple the technology, business, and politics of all vendor project engagements.
All vendors are suspect. Even the nice ones. Honestly, those are the ones that worry me the most. I’ve had way more time of mine wasted by nice vendors, talking about participating, putting meetings in the calendar, and collaborating on press releases that never see the light of day, to know better. Honestly, the opinionated, straight forward vendors are the ones I worry about least–you know where they stand. From my view all vendor projects need to have a defined (de)coupling from specific vendor interests and the standards interest. Keeping this API is the best way do this, as the central API specification will have an OpenAPI and JSON schema, as will the individual project. Using OpenAPI as a contract for vendor engagement provides a nice scaffolding for this (de)coupling, keeping any billable hours spent measured by commits to the OpenAPI, JSON Schema, or actually now that I’m thinking about it an APIs.json or other discovery document.
Now I am getting to the goal of writing this post. Each vendor related project will begin and end as a Github repository with an OpenAPI, JSON Schema, and APIs.json as the central definition, and contract. This will be the central (de)coupling business contract, even if the vendor, and other parties are not fluent in OpenAPI, JSON Schema, or APIs.json. I will maintain the contract, and communicate it out in all proposals, meetings, and project documentation, encouraging awareness and literacy around all three specifications when possible. With API definitions published to Github as central contract, it regularly allows me to assess progress made, and measure the effectiveness of individual projects, making decision on how to fund and move forward, as well as cut them loose when they are no longer making sense.
The Implementors Dilemma Individual API implementations are an entirely different beast from vendors, and while they may live within the tractor beam of one or many vendors, they often have their own silos, resource deficient, and organizational isolation that drives it’s quest to retain power. In each of these industries I am approaching things from a position of harmonization, standardization, interoperability, and reuse, which is often out of view of individual implementors. Individual industry level API implementations want to be successful in their context, and often want the benefits of harmonization, standardization, interoperability, and reuse that are being suggested, but rarely want to, or have the time to do the had work needed to make necessary changes. This will manifest itself in many different ways when you are trying to talk about API standards, something that is often in response to, or driven by the power motivations of vendors who have their ear.
Literacy and awareness are the biggest challenges with individual implementors. Whether federal government, city government, higher educational institutions, or small regional nonprofit organizations, almost every group I come across is underfunded, and under-resourced when it comes to their IT needs, and the delivery of data and content systems. Many folks I meet are well meaning, but lack the skills and training necessary to deliver scalable IT systems, having often landed in their jobs by accident, and being in the right place at the right time. Some are aware of these deficiencies, but lack time and resources they need to get the training they need, while others are completely unaware, and in denial, often taking a very hostile and combative approach when it comes to new ideas, even if they may seem like common practice in the wider API sector.
The majority of organizations I come across are not ready for API. They are not confident in what they know, and what they do not know. They want to share data and information, but often aren’t setup technically or culturally to share data and information. Implementors want to be able to leverage data from other implementations, and reuse open source code, services, and tooling, but will rarely want to do the hard work required to reciprocate in these environments. While well meaning, many are so far behind because of many decisions they’ve made along the way to stay behind, and will require a significant amount of training and investment to bring into alignment with industry-wide standards. Some will never be brought into alignment, and should be replaced–whether they are well meaning or not.
Similar to all vendors, each individual API implementation should have it’s own contract and repository. If an OpenAPI cannot be mocked for an implementation, bringing into focus existing schema, and access requirements for an individual API implementation, it is unlikely that an implementation will ever be moved forward. OpenAPI, JSON Schema, and APIs.json help quantify:
- API Operations - What APIs are there, as well as all supporting resources like documentation, registration, terms of service, and other things that govern doing business online today.
- API Access - What are the technical details for each API path, parameter, and schema, providing a detailed list of what each access request and response involves.
- Data & Content - What data and content is being made available, often reflecting backend databases and other systems, but ideally reflects common schema that can be reused in other systems.
If an organization can not come together have a constructive conversation around access to data, content as part of a new approach to working with external groups via an API operations, it is unlikely and individual implementation will ever be viable. OpenAPI, JSON Schema, and APIs.json can all exist as YAML documents, which is (should be) plain language, no code, brackets or otherwise, allowing business and technical groups to both participate. Similar to vendor implementations, I will be providing oversight of each Github repository, and central project OpenAPI, JSON Schema, and APIs.json index, but ideally each individual implementation becomes the keeper of the contract for each of their projects, requiring only minimal engagement from other implementations, vendors, or at the standards level of the discussion.
Bringing This Home For Next Round Of Conversations Ok, I actually have to invest in the next rounds of these industry level API discussions. I think I’ve settled in on my Github repo managed, OpenAPI, and APIs.json governance of these large number of relationships I need to engage in, manage, and measure. I’ve been blindsided by several conversations at the implementation, vendor, and industry levels, across city and federal government levels, and small, medium, and larger corporations lately. My goal in this post is to help me mitigate damage in future conversations, and keep myself moving along at a faster pace, with least amount of friction on my end as I can. When dealing with so many personalities, as I am across a handful of industries, it is something can be very exhausting if I do not find a way to insulate myself.
Each vendor and implementation involved with the defining of an industry API standard with live as a Github repository. Being able to sign up for a Github account, and participate in issues is a minimum entry fee. Not that they’ll be excluded. They’ll just be identified as making a choice to stay behind. The presence and robustness of an APIs.json will be the next layer of definition, providing essential links to API operations for either the vendor or the implementation. In my opinion, this is always a great way to size up a company, organization, institutions, and government agency. Similar to how you can size up an organization by their web, and social media presence, if they don’t have an existing API or open data effort already, there are other deficiencies right around the corner, or behind the firewall.
Next, the presence and evolution of a coherent OpenAPI and JSON Schema will bring into focus the viability of a vendor partnership, and individual implementation viability. If an OpenAPI can be established and moved forward, there is potential. If there hasn’t been commits in months, and difference between commits productive, with a healthy amount of issue activity, I’m guessing a vendor relationship, or individual API implementation needs further assessment regarding its viability, and sustainability. Of course, any final decisions are made by a human (me), as everything I’m discussing here operates under the API Evangelist, and Adopta.Agency network of API research projects.
The majority of my time as API Evangelist is spent researching the technology, business, and politics of API operations across ALL industries. I’ve created my Adopta.Agency domain to help me manage my investment in common API definitions, schema, and actual implementations of public open data and API projects. I’m trying to establish an approach to help define common OpenAPI, JSON Schema, and APIs.json for a number of industries, that allows me to move forward a number of conversations, with the least amount of friction, and impact on me. I don’t enjoy getting sucked into politics, and prefer staying at the highest level possible when it comes to helping influence what is API today–something that is impacting a significant portion of our world, not just the tech sector.
I’ve been tracking on many different API industries using small data driven Github repositories for three years now. I track on over 1500 APIs using my API Stack research, which has morphed into what I call the Stack.Network, where I profile specific industries or sectors of how we do business online today–companies like Amazon, Microsoft, and Google. My API Stack research is all about identifying common patterns across individual API implementations, aggregating them into over 1500 individual building blocks that contribute to my definition of the almost 100 stops along a modern API lifecycle. Each of my stacks tends to represent an industry like SMS, or news, but I also have individual company stacks like Facebook, or possibly even the federal government like with the General Services Administration (GSA). Each of these projects have an OpenAPI, JSON Schema, and APIs.json core, which gives me a distilled down definition of each stack for inclusion across my research.
I’m looking to define I want to expand my existing approach to quantifying the world of APIs to include specific APIs, schema, implementations, and collections, and open it up for collaboration and discussion with a variety of vendors who may serve multiple industries, as well as specific implementations within an industry. Honestly, nothing really changes for me in all of this, except that I will be encouraging vendors and implementations to at least participate, and ideally move forward their own OpenAPI, JSON Schema, and APIs.json. I’m also looking to encourage them to be a little more Github fluent when it comes to defining a common industry API definition and schema. I see Github as just another social network like Facebook, Twitter, Instagram, and Pinterest, except the actions taken often revolve around code, and machine readable templates, instead of messages, images, video, and other common social building blocks.
Ok, phew. If you are still reading this, you should probably develop a hobby. I’m writing this to help me get my ducks in order. If it makes sense to you, and helps you in your API journey–awesome! I feel I have to regularly write about the feels I get in my working as the API Evangelist. It is about me talking through what I’m seeing, and finding a way forward. The scope at which some of these API conversations are occurring at can be dizzying, and if I don’t step back from time to time, and just work through my feels, they tend to pile up and I stumble more. This post help me come around full circle to realize some of the new projects I’ve been taking on are actually just an extension of what I’ve already been doing as I map the world of APIs, I’m just turning up the intimacy level on some of the vendor and implementation level relationships. However I’ve done a pretty good job of building an insulator between me an the space, I just need to keep doing what I’ve been doing for the last seven years, and confidently push some more of these common API definitions, schema, and collections out the door.
