API Governance Models in the Public and Private Sectors: Part 6
Join us as the API Evangelist, Kin Lane, shares a detailed report concerning the U.S. Department of Veteran Affairs and its wish to understand API governance.
Join the DZone community and get the full member experience.Join For Free
This is part six (you can find part five here) of an eight-part series on the Department of Veterans Affairs microconsulting project, “Governance Models in Public and Private Sector.” Providing an overview of API governance to help the VA, “understand, with the intention to adopt, best practices from the private and public sector, specifically for prioritizing APIs to build, standards to which to build APIs, and making the APIs usable by external consumers.” Pulling together several years of research conducted by industry analyst API Evangelist, as well as phone interviews with API practitioners from large enterprise organizations who are implementing API governance on the ground across the public and private sector, conducted by Skylight Digital.
We’ve assembled this report to reflect the interview conversations we had with leaders from the space, helping provide a walkthrough of the types of roles and software architecture being employed to implement governance at large organizations. Then, we walk through governance as it pertains to identifying possible APIs, developing standards around the delivery of APIs, how organizations are moving APIs into production, as well as presenting them to their consumers. Wrapping up with an overview of formal API governance details, as well as an acknowledgment that most API governance is rarely ever a fully formed initiative at this point in time. Providing a narrative for API governance, with a wealth of bulleted elements that can be considered, and assembled in the service of helping govern the API efforts across any large enterprise.
Making APIs Available to Consumers
The next step in the life cycle of properly governed APIs is making them available to the consumer after they’ve been published to a production environment. The governing of APIs is not limited to the technical side of things, and this is where we begin understanding how to consistently deliver, measure, and understand the impact of API resources across the many consumers who are integrating the valuable resources into their applications. Shining a light on the business and politics of how digital assets are being put to use across the enterprise.
This portion of this governance research is intended to provide a basic list of the building blocks used by enterprise groups to help reduce friction when putting APIs to work, but also make sense of how consumers are using API resources and establishing a feedback loop that guides the roadmap for the future of the platform. Taking us back to the beginning of this research and informing how we should be targeting the development of new APIs, the evolution of existing services, and in many cases, the deprecation and archiving of services. Ensuring governance goes well beyond the technical details and making sure they are benefitting from the platform as well as consumers.
Making your APIs available to consumers requires doing a lot of research on who you are marketing them to and positioning yourself to speak to an intended audience. Tailoring not just the design of your APIs, but the overall presentation, messaging, and even portal, documentation, and other building blocks to speak to a particular audience. For many API providers, APIs might be made available to multiple audiences in a variety of ways based upon knowing their customers and presenting exactly the resources they are needing to get a specific job done.
- Studies — Conducting regular stories about what internal, partner, and public user groups are using and needing when it comes to developing applications, and integrating systems.
- Landscape — Establishing an understanding of the industry landscape for the area being targeted by services, and regularly tuning into and refining the understanding of what consumers are using across that landscape.
- B2B — Positioning the API to speak to a B2B audience, providing separate portal, documentation, and other resources to cater to a business audience.
- B2C — Positioning the API to speak to a B2C audience, providing separate portal, documentation, and other resources to cater to a consumer audience.
- Partners — Providing a unique set of resources that speak to partner groups, providing separate portal, documentation, and other resources to cater to exactly what existing partners will be needing.
- Internal — Positioning the API to speak to internal groups, providing separate portal, documentation, and other resources to cater to the needs of development groups within the enterprise.
- Context — Making sure services have knowledge of the context in which they will be delivering resources into. Different patterns, processes, and practices work well within different contexts, while others will fail depending on the context that is relevant to the consumer.
- Office Hours — Holding conference call, or virtual office hours for different consumer groups to be available for discussion around what APIs are available, their supporting resources, as well as contributing to the platform roadmap.
Knowing your existing and potential API consumers is essential to position your API program to speak to its intended targets. It is difficult to design and present the right set of resources for an audience you do not understand. Demonstrating how knowing your consumers is something that should happen before you begin the development of services, as well as an ongoing features of a platform, and that understanding the challenges of your consumer, and shifting the roadmap to stay in alignment with your consumer audience is critical to realizing platform-wide governance
While studying the consumer outreach strategies of leading API providers, as well as the ones that were interviewed, there are common patterns at play defining how to best reach your audience. The consistency of governed APIs speaks to how to best reach a wide audience, helps increase the impact APIs will have in the applications they are used in, and reduce overall friction and support required to operate them. There are several common patterns present when looking at how organizations are presenting APIs to their consumers publicly and privately.
- API Design — The design of APIs, using common RESTful resource design patterns, helps present simple, intuitive, and familiar resources that speak to a wide as possible audience.
- Developer Portals — Consistently designed, easy to navigate, well-branded portals provide a familiar, known destination in which consumers can discover, onboard, and stay in touch with where an API platform is going.
- Documentation — Using common open source documentation across APIs provides an interactive, hands-on way for developers to learn about APIs, understand how to integrate with them, and be able to regularly check back in for added features and benefits that they provide.
- Definitions — Providing machine readable OpenAPI, and Postman Collections for consumers gives them a portable definition of what an API does, which they can use in their client tooling, to generate code libraries, set up monitors, tests, and generally understand what is possible.
Common design and presentation patterns are of the reasons many of the leading API providers have established their foothold with their consumers. When you study the approach of Amazon, Google, Twitter, Twilio, Stripe, and other leading API providers, you see that they all use consistent design patterns, as well as provide similar portals, documentation, and other resources for their consumers. Governing the presentation layer for their API-driven services, which reflects the consistency consumers are used to when working with multiple API providers across even different business sectors.
The next aspect of presenting production APIs to consumers involves communication and ensuring that all stakeholders are kept up to speed on what is happening. Keeping a steady stream of information flowing around the platform, blending it with, and encouraging the activity on feedback loops, with an intent to drive the platform roadmap.
- Updates — Providing updates on a blog, or another mechanism, helping keep consumers up to date on what is going on with the platform, and making sure everyone knows there is someone home.
- Roadmaps — Publishing a public roadmap for API consumers to help them understand what is being planned, and what the future holds. Also maintaining private versions of a roadmap for internal groups and potential partners.
- Issues — Being transparent and communicative around what the current known issues are with a platform, and publishing a list of anything current.
- Change Logs — Translated the roadmap, and issues into a changelog for the platform showcasing what has historically occurred via a platform.
- Showcase — A published listing of applications and developers, showcasing the work being done by API consumers, highlighting the value a platform brings to the table.
Maintaining a steady stream of communication around what is happening with an API platform is a clear signal coming from the strongest enterprise API platforms out there. You see regular communication around what is happening, and what is being worked on, with teams reach out to each other, and sharing healthy practices, challenges, and showcasing what is being done with their API resources.
Stay tuned for part seven: Realizing API Governance.
Opinions expressed by DZone contributors are their own.