A blueprint for helping jumpstart a mapping of the internal API landscape, allowing an organization to begin getting a handle on what is happening across operations. Beginning by profiling a specific group or domain, but then expanding it across operations once a portion of the landscape has been mapped and understood.
Understanding the makeup of the teams behind the development of APIs is an essential part of moving APIs forward at scale across an organization. Mapping out the team landscape can begin in three areas, with efforts focusing on a single group and the members and roles that exist within that single group, before expanding to other teams. Working to make sure that the current state of teams is mapped out, but then establishing an apparatus that will accommodate the future of development by mapping out three key areas.
- Team Groups - Teams can be organized by groups that reflect lines of business, and business domains. Establishing bounded context for assigning team members to, allowing API operations, workspaces, artifacts, and other resources to be organized, accessed, and reported upon via logical groups.
- Team Members - Formerly defining who the team will be moving an API forward through all stages of it~s lifecycle, providing a clear definition of who is responsible for each part of producing an API.
- Team Roles - API teams can be assigned a specific role that is in alignment with their involvement in the API lifecycle, allowing them to have the access to APIs, artifacts, and resources based upon their role in the process. Allowing teams to play the part they have been assigned, while also still ensuring the integrity of operations, helping ensure more reliability, but also productivity in how teams work.
- Members - The individual and collective members of a specific team are involved in producing and consuming APIs, identifying the human beings behind API operations, organizing them into logical groups, applying designated roles and access permissions, helping be more organized about how API operations are defined.
- Groups - Establishing a logical separate of teams, grouping by domain, line of business, project, or another bounded context that makes sense to the human part of operations, but will ultimately shape the workspaces, APIs, documentation, and other elements of API operations, helping shape the API factory floor.
- Role Based Access Control - The ability to assign roles individual team members then shape access to workspaces, APIs, collections, and environments based upon their role in producing or consuming APIs, allowing for the protection of artifacts and other elements from unwanted changes, while still making them available to the widest possible team members for use, striking the right balance across domains, groups, and workspaces. null
Mapping the API landscape is required to get a handle on API operations, and allow business and technical leadership to assert the observability and control they need to move things forward. Until all APIs are mapped out, documented, and made discoverable, you will not be able to effectively evolve APIs, and there will always be redundancy in the API infrastructure behind web, mobile, and device applications. Mapping of the enterprise API landscape begins with documentation for each API but then focuses on the artifacts that are increasingly defining them.
- Documentation - Documentation published as human consumable HTML pages help potential API consumers learn about what an API does by describing the paths, channels, parameters, headers, schema, messages, and other building blocks of APIs, showing examples of what is possible or by providing an API client to make calls to each API as part of the documentation.
- OpenAPI - The OpenAPI specification provides a common vocabulary for describing the surface area of request and response APIs, as well as webhooks, ensuring that API producers and consumers are on the same page when it comes to integration, but also helps stabilize multiple areas of the API lifecycle providing a contract that can be used for delivering documentation, mocks, testing, and more.
- Watch - Watching of some element of API operations, allowing team members, partners, or public users to signal they want to receive notifications of any change to an API and it~s supporting elements, making API operations more observable and something that all stakeholders are able to stay in tune with as they evolve and change.
- Changes - Dealing with the inevitable change that is happening within any industry, and across enterprise operations in response to a changing world, taking the time to regularly assess what change is occurring, establishing common practices for managing and communicating around change across teams and with consumers.
- Comments - Comments on APIs, collections and other elements of API operations allow for more tightly coupled and inline conversations to occur around entire elements or specific parts and pieces of elements, allowing teams to collaborate and communicate across the API lifecycle. API RBAC** - Providing guidance for how RBAC should be applied to APIs. null
Understanding where work on API is occurring is needed to be able to standardize, observe, and govern the API development process. API workspaces are where you will find the artifacts developers are using to design, develop, and sustain APIs, and provide what is needed to observe operations, but then also begin to steer things in any particular direction. These are the common elements where you will find work occurring on APIs, and are where leadership should look for what is needed to observe operations and move things forward.
- Team Workspace - Establishing and properly setting up a dedicated workspace for each API helps ensure there is always a single place to go to find everything that is happening with an API across it~s entire lifecycle.
- Github Repository - Having a dedicated Github repository for an API provides a single place where code and other artifacts can be managed, with a pipeline, issues, and other supporting elements an API will need to operate.
- Watch - Watching of some element of API operations, allowing team members, partners, or public users to signal they want to receive notifications of any change to an API and it~s supporting elements, making API operations more observable and something that all stakeholders are able to stay in tune with as they evolve and change.
- History - Having access to the history of requests and other activity associated with API operations, providing an accounting of what is happening from both producer or a consumer point of view, relying on logging, but making it much more usable as part of team or consumer working within any API workspace.
- Activity - Activity - The changes made to any aspect of operations by team members, providing observability into when APIs, mock servers, documentation, testing, monitors, and other critical elements of API operations are changed, configured-- **helping give a log of everything that happens at the operational level.
- Workspace Name - Providing guidance for how workspaces should be named.
- Workspace Overview - Providing guidance for how workspaces overviews should be crated.
- Workspace RBAC - Providing guidance for how workspaces RBAC should be applied. null There is so much more that you can invest in as you progress in yoru API journey, but mapping out the human, business, and technological layers of your operations is important to the stabilization of your platform–with a clear map of what exists today, you will be able to better prepare for what is next.