A playbook for API-first transformation at scale-API platform team, roles and responsibilities

In the previous post, we discussed the key building blocks of an API Platform that are fundamental to an API-first transformation, in an organization of any size. In this post, we’ll discuss what it takes to build an API platform team, and the associated roles and responsibilities.

Remember from the previous post, an API Platform is made up of these key building blocks;

• The business capability model
• The business domain (s) vocabulary
• API architectural standards
• An API product development lifecycle
• The API infrastructure
• Developer advocacy

You API platform team structure should mimic the above platform functions. Given below is the structure of an API platform organization and the associated roles and responsibilities.

An API platform team would have the following roles and responsibilities.

Portfolio Manager

The portfolio manager role should be set up to work in a federated model.

A portfolio manager is the primary contact for API owners in the API creation process. The portfolio manager is accountable for the consistency and cohesion of the API portfolio in one or more capability domains in the business capability model. For example, a portfolio manager for the identity domain is responsible for the sanity of all the identity APIs and ensures that each API product in the portfolio has a unique value proposition (&meaningful in the overall product offerings from an outside-in standpoint) and its functionality doesn’t overlap with any other existing API product. A portfolio manager also recommends an API’s namespace, resources, versions, and API names to the API owners. More about the API portfolio alignment later in a separate post.

A portfolio manager role should be set up to work in a federated model. The decision on when to federate would depend on the maturity of your organization. For example, if you are in an organization that have technical product management functions in all domains, who are highly involved in building software products, these technical product managers could most likely perform the role of the API portfolio manager right away. If you don’t have dedicated technical product management functions, the portfolio management can be performed by the central API platform team until the time, the skill gaps are addressed. A third model, which is a hybrid model and consists of members from the central API Platform team and the product managers from the business domains that could collectively manage your API portfolio. From experience, the third model works best in companies of any size, as the knowledge is equally distributed among all team members, doesn’t create any central dependency on a particular portfolio manager and has a multiplier effect.

API Designer

The API designer role should be setup to work in a federated model.

The API designer is accountable for the API design reviews in one or more capability domains and consults with them on API design and ensures adherence to API standards and guidelines. An API designer educates the API owners on API standards and guidelines on a continuous basis. An API Designer also performs the API maturity assessments (i.e, grading of APIs against the API Design quality criteria), wherever automated validation is not available or possible. More on the API maturity assessment in a separate post on API product development lifecycle.

Like the portfolio manager, the API designer role should be setup to work on a federated model. The API design role for a capability domain is usually carried out by the domain’s lead architect. So, the decision on when to federate, depends on the skill level of these domain architects. If there are skill gaps, the central API platform team can perform the design reviews, and continuously mentor the domain architects. Eventually, like the portfolio management federation, once the skill gaps are bridged, a hybrid model could be used for design federation. As discussed in the previous section, such a model scales better, with knowledge equally distributed among all team members, it doesn’t create any central dependency on a particular designer and has a multiplier effect.

All other roles from hereon, are either dedicated roles in the business domains or the central API Platform team.

API Product Owner

An API product owner plays a very important role in the API product development lifecycle. An API product owner is role in a business domain and may also perform the role of a portfolio manager for the domain. An API product owner is responsible for the following functions.

• Defines and manages the roadmap of an API product in a capability domain (A capability domain consists of comprises of several API products).
• Perform user research, analyze competitive API products, and strive to build best in class APIs.
• Accountable for integration, use cases, complete Developer Experience (including documentation), and overall product strategy.
• Collaborates with developers and iterates on improvements to the Developer Experience

API Engineering Owner

An API engineering owner leads the API design and technical implementation. The engineering owner is overall responsible for the delivery of the API implementation, including non-code artifacts (e.g test coverage report,), ensure API interface and implementation conformance and the overall API quality.

API Product Sponsor

The API product sponsor is the business sponsor of the API Portfolio in one for more capability domains. An API product sponsor (along with the engineering sponsor) is accountable for the overall API portfolio health, identifying API product owners for each capability domain and responsible for resolving any conflicts impeding API Portfolio progress. In many companies, the API product and engineering sponsor is one consolidated role.

API Engineering Sponsor

The API engineering sponsor is the engineering sponsor of the API Portfolio in one for more capability domains. An API engineering sponsor (along with the product sponsor) is accountable for the overall API portfolio health, identifying API engineering owners for each capability domain and responsible for resolving any conflicts impeding API Portfolio progress. In many companies, the API product and engineering sponsor is one consolidated role.

API Platform Architect

An API platform architect is a critical role in the API platform team. The API platform architect is accountable for establishing and maintaining the API architectural standards, doing API design reviews for one or more capability domains, or performing the role of a lead API designer for the federated API design team (with the shared responsibility of API design reviews). The API platform architect is also responsible for the providing the overall architectural and technical guidance to the API infrastructure team for tooling implementations. To scale an API platform architect role in an organization of any size, an architect per API protocol is ideal. For example, if you are an organization that build REST, GraphQL and Evented APIs, it would be ideal to have three API Platform architects (one each for REST, GraphQL, and Events). When looking for skills, you would look for someone who have extensive engineering and architectural experience, great interface design skills with customer focus and passion for mentoring and education- all these skills are important.

API Platform Developer Advocate

An API platform developer advocate performs the role of a translator between the API platform and its users (internal and external). The developer advocate evangelizes the platform’s new features, standards via various forums (blog, audio/video tutorials, demos etc.) and help users integrate with these platform features. The developer advocate also collates feedback from the platform’s users and convert it to feature requests, for the platform team to work on. A developer advocate should always be up to date with all the platform’s products. A developer advocate is a serious role by itself, requiring focus and a different skillset (e.g., communication, networking, and development). Organizations should invest in building a dedicated developer advocate team, instead of trying to force fit these responsibilities with other roles.

API Platform Infrastructure Product Owner (s) and Engineering Owner(s)

The API Platform infrastructure engineering and product owners are responsible for building and managing all the tooling in API platform tooling. More on the API infrastructure tooling blueprint later in a separate post.

This article is the second of seven that explores the API-first transformation playbook in detail. In the next post, we’ll discuss what a business capability model means, what it takes to build one and why it is such a critical building block of the API Platform.