--- published: true layout: post title: You’ve Been Put in Charge of Your Public API Presence and Experience date: 2025-03-07T09:00:00.000Z tags: - Presence - Experience - Portal - OpenAPI image: https://kinlane-productions2.s3.amazonaws.com/algorotoscope-master/bf-skinner-seattle-shipping-people-walking.jpg --- In an effort to capture another recent conversation I had with someone being tasked with API change at scale within their enterprise, I wanted to capture as much of what I shared in a story that others can read and learn from on their own, but also so that I can use as a link referral in response to future conversations. The conversation reflects my recent journey at Bloomberg, and conversations I am having with enterprises across many industries, while outlining what it is I offer to enterprise organizations in the form of guidance and consulting. ### Our API Presence You’ve been put in charge of the API portal, presence, experience, and documentation for your enterprise. All of this already exists in one form or another, but you have an opportunity to rebuild, reformulate, and establish your dominance following a leadership mandate, program consolidation, acquisition, or other seismic shift in how your enterprise works. You have been chosen to lead the charge and make your mark with bringing your API presence into the future, but you need help knowing where to start with this monumental task. ### Our API Experience You want to be empowered to deliver the modern and robust API experience expected by developers today in support of the robust and valuable API resources and capabilities your enterprise offers. You are looking to deliver a presence that rivals Stripe, Twilio, and other API leadership, offering the common building blocks developers will need to discover, onboard, and rapidly integrate your resources into their applications and systems—what do I focus on? - **Portal** - A single location to access all API resources and capabilities. - **Documentation** - Simple, clean, and modern documentation for all APIs. - **Sandbox** - A place to help developers onboard with APIs in a safe way. - **Code** - Providing the snippets, libraries, and SDKs developers need. - **Plans** - Having a plan for rate limits, pricing, usage, and other details. - **Support** - Processes in place to make sure consumers have what they need. - **Feedback** - Actively encouraging and using feedback from API consumers. You’ve done your due diligence and understand what is expected by developers today, and have a strong grasp of what the building blocks are of a modern API experience. You understand that you have one chance to make a first impression on developers, but also their bosses who are making the purchasing decision, and have done the work on your plan for your API experience. ### Our OpenAPI Priority While conducting your research you were able to properly understand the role that OpenAPI plays in delivering this experience. You aren’t using the word Swagger anymore because you know that it is a trademarked set of tools, and the specification you need to describe the surface area of your enterprise is an OpenAPI definition. You don’t just see a specification, you see the configuration for the API experience above. - **Documentation** - Generating accurate modern API documentation. - **Snippets and SDKs** - Generating snippets and SDKs for your APIs. - **Mock Servers and Examples** - Generating mock servers w/ examples. - **Plans and Rate Limits** - Automating service composition and rate limits. - **Testing & Performance** - Automating the testing and performance of aPIs. - **Security & Governance** - Automating the security and governance of Apis. Your awareness that the completeness and quality of your OpenAPI definitions will define and shape the API experience and API presence. OpenAPI isn’t just about documentation or code generation, and is the expression of the digital resources and capabilities your enterprise produces and is your API presence and experience. You are determined to ensure that your enterprise and teams produce the best possible OpenAPI you can. ### Our API Reality Just behind the facade of your API presence and experience, your vision and well-prepared plans come up against the reality of what actually happens on the ground, as well as the upper floors of your enterprise. This is something that is not unique to your organization, but I am guessing your enterprise can put a unique spin on sprawl and dysfunction that prevents many enterprises from ever achieving a meaningful public presence and experience because of the following. - **Tribal Factions** - The new mandate may have dissolved legacy boundaries, the systems, services, and people still remain. - **API Literacy** - While everyone uses the web, there is no foundational understanding of HTTP, as well as what an API actually is. - **OpenAPI** - The OpenAPI is a generated output of code and systems and nobody understands it or sees the role it actually plays. - **Standards** - Standards have been used, but inconsistently, and any documentation is usually out of date, obsolete, and not useful. - **Priorities** - The priorities of enterprise business leadership is focused on APIs at this moment, but they haven’t always been and it shows. - **People** - Teams don’t have the literacy and awareness needed to come together for external presence, let alone the time and resources. - **Compliance** - You realize that every API, bit of code, content, and everything needed for presence will need to go through security and compliance. Your vision for your API presence has just slammed into the reality of how your enterprise has historically worked. You realize that you don’t have a lot of help in producing complete and accurate OpenAPIs, and they will just be auto generated outputs at best. At worst you will need to parse PDF, Spreadsheets, Word documents, Slack and Team messages, emails, and chase and harass teams at every step to get the OpenAPI artifacts you will need to do your job. You are overwhelmed even more now, and you just don’t know where to start. ### Our API Survey & Assessment Your mandate is massive. You are literally the person between your enterprise and the world. You are responsible for taming everything happening inside your enterprise and making it fit for presentation to your partners, customers, and the world. Now, close your eyes for a second, and just take 2-3 deep breaths, and stop being overwhelmed with the big picture and let’s just survey and assess the world around you by doing the following. - **GitHub Organization** - Establish a dedicated GitHub, GItLab, or Bitbucket organization to organize your work. - **GitHub Repository** - Create a single repository that you will use to organize your survey and assessment. - **OpenAPI** - Generate, gather, and produce OpenAPI for every API you can find existing out there and put into repo. - **JSON Schema** - Ensure the requests and responses for all APIs have JSON Schema defined as part of each OpenAPI/ - **APIs.json** - Organize all of those APIs, plus all other artifacts, documents, and resources into a single APIs.json manifest. - **Rules** - Begin assembling Spectral and Vacuum rules which identify the patterns and anti-patterns that you see. - **Reviews** - Automate the reviews of your OpenAPI and APIs.json, then publish and report upon results via your repo. - **Tags** - As you are doing this work make sure you are tagging your OpenAPI and apis.json to identify resources and boundaries. - **Teams** - Document who the people are producing these APIs, including engineering, product, and other stakeholders. Do this work until you feel like you have a sizable surface area of your API operations surveyed and assessed. You will learn a lot. You will build relationships. You will learn who your allies are, as well as who your enemies are. You will establish a baseline of quality for APIs being produced by our organization. You will establish a baseline for the lifecycle and operations surrounding those APIs. Only now, will you be able to effectively put together a strategy for how you can achieve the presence and experience you have in your head for your enterprise organization. Using Git will allow you to not just manage the work in a single repository but shard and expand as your tag boundaries evolve, allowing you to separate workstreams as needed by repository. However, maintain this as the source of truth, keeping all references to human and machine-readable artifacts referencing your Git repositories. Then use pipelines, webhooks, and APIs to push and pull artifacts and updates from any other system teams may be using. Keeping you focused on the funamentals, centered using Git, and the leveraging automation and APIs to stay out of the dogma, ideology, and history associated with the other systems and tooling teams are using, while still getting the work done you need. If you do not ground your work in a proper survey and assessment you will never be successful in your work. If you do not have a baseline for your APIs and operations you will never be successful in your work. If you do not build relationships with teams producing APIs you will never be successful in your work. This isn’t solely about API strategy, governance, management, products, and other phrases your vendors have equipped you with. This is simply about surveying and assessing your enterprise landscape and developing enough awareness of the reality on the ground that you can deliver an API presence and experience that is balanced between what you want to put out into the world for your partners and customers, and what the reality is on the ground within your enterprise. ### Other Supporting Links It is difficult to capture everything I covered in our conversation, but here are a couple of additional stories I mentioned that may help you in this journey. - [Do you have any blueprints for API design style guide?](https://apievangelist.com/2025/03/04/do-you-have-any-blueprints-for-api-design-style-guide/) - [More Examples of using GitHub to Manage Your OpenAPI](https://apievangelist.com/2024/07/08/more-examples-of-using-github-to-manage-your-openapi/) - [Who the API Evangelist Speaks With About Being an API Change Agent Within the Enterprise](https://www.linkedin.com/pulse/who-api-evangelist-speaks-being-change-agent-within-enterprise-lane-lmuse/) - [The Missing API Fundamentals](https://apievangelist.com/2025/01/23/the-missing-api-fundamentals/)