I recently posted a question on Twitter asking for questions or insights into the role of the API architect. I received some wonderful responses, including insights from API product managers, architects, and company founders. I want to summarise these findings within a framework developed by Edward de Bono called the Six Thinking Hats, then answer some common questions by applying this framework.
The Six Thinking Hats
I was first introduced to The Six Thinking Hats by Edward de Bono at a startup in Austin that was one of the few groups that truly demonstrated the original intent of the Agile Manifesto principles. They used three of the hats as part of their retrospective, allowing the team to identify what was working, what didn’t work, and then brainstorm on creative ways to improve their process. They would then select 2 or 3 areas of improvement, focus on those for the next sprint, and review if further adjustments were required in the next retrospective. It was a powerful tool that I then investigated in its entirety and have applied in different areas since.
In short, the six thinking hats allow teams to communicate more effectively by allowing a team member to “wear a coloured hat” that indicates what kind of thinking that are undertaking. The hats help to clarify the intent of a comment or observation by sharing the idea on the kind of thinking they are doing. When used properly, it is a constructive way to share ideas and areas of improvements, while guiding meetings toward a more productive result.
As I started to consider how best to describe the role, I first starting thinking about the titles and roles in the different kinds of organisations I consult to, from enterprises to SaaS companies. The problem with this approach is that every organisation has a different structure, from functional to divisional, and titles vary greatly. I then reached back to a tool I’ve been using for almost 20 years – The Six Thinking Hats. This seemed to fit better, as it allows us to think about the role of from a variety of perspectives. So, let’s look at each hat and how it helps us to understand the role a bit better.
The White Hat: API trendspotter
The White Hat provides or seeks required information. It focuses on facts. (“objectivity”)
Facts and information are a key driver of our recommendations and form the foundation for the use of The White Hat. They use tools such as API gateways, metrics, and dashboards to determine what API operations are most used, least used, and where to focus efforts. API analytics help to provide understanding about how well an API is performing, including if a recent release has resulted in an increase or decrease in errors experienced by API consumers. Observations such as an increase in 400 errors help to drive the use of other hats to determine why API consumers are struggling to generate properly formed API requests.
They use linters as part of the API design and development process to assess how much of the API standards have been implemented and what design decisions deviate from approved practices. These objective metrics are used to determine API health and API quality, to the extent possible. Analytics dashboards and reports are used to track changes and trends across APIs. These trends help to identify APIs in production that are not being used or perhaps experiencing an increase or decrease in use over time.
Additionally, the White Hat drives the desire to better understand important RFCs and specification documents that define protocol specifics. These specifications help to shape the standards and practices that encourage consistent API design.
Finally, they use automated tests to determine if an API implementation matches the promises of its description, often captured using OAS, API Blueprint, or RAML.
All of these metrics, data points, and facts are used to determine the health of an API and even entire API programs.
The Red Hat: API reviewer
The Red Hat seeks to understand what people like and dislike (“emotion”)
One of the biggest challenges is helping others become better API designers. While standards, practices, and protocol specifications provide more of an objective review process, much of the API design process can be subjective. API designs may be viewed as good or bad based on some internal emotion or recognisable trait. This is the role of the Red Hat.
They are tasked with reviewing an API design not only with the White Hat of facts and objectivity but also from a subjective point of view. They asked questions such as:
- “Does the API seem easy to use?”
- “Do the names of paths, parameters, and resource properties make sense for the target audience?”
- “Why does this API design seem to have a minor flaw or design stink?”
The Red Hat includes assessing an API relative to market understanding and product management. For organisations with dedicated product management, architects act as more of a bridge between the product manager (PdM) and the design of the API. For organisations that lack PdM, they may be required to wear this hat more often when it comes to assessing the market reception of an API.
The Red Hat provides API design reviews (DX reviews) and documentation reviews. Using the input from the White Hat, the API is reviewed both from a compliance perspective and an overall emotional experience.
The API architect helps to identify hunches or “gut feelings” of what might be possible. This includes what may need to be further investigated, using the White Hat to avoid being misled without facts and using the Green Hat to creatively find new ways to use an API or adjust the design of an API.
The Red Hat ensures that everyone has their say about an API design. They recognise the value that PdMs, developers, QA team members, project managers, customers, and others bring when it comes to API design. They listen and make recommendations based on the likes, dislikes, and other emotions when it comes to an API’s vision and design.
The Black Hat: API risk assessor
The Black Hat seeks to understand why something might not work (“judgement”)
This identifies and reduce risks for an API. This may include evaluating and applying caution before adding new API protocols or styles into an organisation’s set of accepted standards. Often, this is driven by recognising patterns from years or decades of past experience, along with any recent knowledge as a result of seeing things not work in one or more areas of a large organisation. They have the difficult challenge of wearing the Black Hat to resist following trends when the outcome isn’t clear or the risk is high.
Additionally, the Black Hat performs security audits, considering what could go wrong with the API, including how the combination of operations could leak sensitive PII data and how the API be used maliciously or incorrectly. For organisations with a dedicated security team, they act as a first and last line of defence by ensuring proper security reviews are applied to each API design that they review.
The Black Hat is also used to identify and prevent anti-patterns from creeping into API design. This may be anti-patterns common to software or those specific to past mistakes that are to be avoided. This includes identifying APIs that are designing for an unknown future, instead encouraging designs to provide minimal operations and data for a more evolvable API design.
Black Hats can also be used to software architecture, where techniques such as event-driven architecture, microservices, and functions-as-a-service may be the wrong fit for a specific solution. As such, they bring their experience in architecting software to help teams reduce risk at the build stage of an API, not just the design stage.
This hat is often combined with the Green Hat and Yellow Hat to find new ways to creatively solve a problem or innovate on a high-risk solution. They also use the White Hat to identify facts that help encourage good behaviours and discourage bad ones.
A word of caution. The use of the Black Hat must be kept in check using the other hats. Otherwise, there will be a tendency to strong arm others to make API design changes that are more subjective. This always results in frustration by teams that are told that their API design is wrong and that users should know better. Room must be provided for teams to design APIs within the guidelines provided by lightweight standards and practices. Otherwise, only a single person or small group of people will be allowed to design APIs rather than empowering teams to learn and grow as self-sufficient API designers.
The Yellow Hat: API advocate
The Yellow Hat represents optimism, benefit, and value (“benefit”)
Architects often straddle the concerns of design and consumption. While they appreciate a clear, simple design that hides behind it complex problems, they also realise that the design itself isn’t the goal – it is to empower developers and end-users. The Yellow Hat represents API advocacy on behalf of the current and future developers that will be tasked with integrating the API. It also represents the advocacy on behalf of the end user that seeks to experience outcomes that the API will empower. They seek to find things that end users couldn’t do before or couldn’t do without significant effort and empower them through APIs.
The Yellow Hat separates the API design from internal systems, including the database design. They encourage API designs to be clear and easy to use, not clever but difficult to understand.
Those who use the Yellow Hat focus on outcomes and business value over easy-of-implementation. They advocate for doing the right thing for the developers and end-users over faster implementation choices and shortcuts. They view APIs as a multiplier effect for the API consumer.
Additionally, the Yellow Hat enables ways to share knowledge and resources to accelerate team learning at scale. They develop articles, videos, training, and other resources to accelerate learning across the organisation.
Like product managers, API architects evaluate opportunities to innovate or add customer value through marketing and distribution channels, new ways of evangelism and developer relations to reach new markets, identify new partnership opportunities to consider. The Yellow Hat extends the responsibilities beyond API design to ensure that the API delivers business and customer value.
Finally, the Yellow Hat encourages a vision for an overall API program, beyond a single API or set of API operations/use cases. This results in some wearers developing big picture thinking, moving them into a role of greater influence within the organisation.
The Green Hat: API creator
The Green Hat focuses on creativity, ideas, growth, and possibilities (“creativity”)
One of the most exciting aspects of APIs is the creativity required. I’ve mentioned in the past that APIs blend technology with business and product thinking. The Green Hat offers new possibilities. Whether this is a new operation on an existing API, or a new API that focuses on a new or related problem space.
Additionally, the Green Hat involves incorporating feedback from customers, developer relations, analysing usage logs to find new and creative ways of using existing APIs. The metrics from wearing the White Hat, risks identified by the Black Hat, and a desire for delivering value from the Yellow Hat results in generating sparks of creativity.
The Green Hat is also used to seek API documentation improvements to encourage easy cognitive understanding of an API’s usage, making API consumption easier for everyone in the future. It is seen as an investment in growth and possibilities in the future. This may involve the use of lateral thinking to find new ways of addressing problems or identifying new opportunities. It may include finding ways to repackage existing API capabilities into new products and offerings.
Those who wear the Green Hat prioritise API ownership by finding creative ways to increase API usage and engagement. For organisations with product managers, they may not be solely responsible, but should be involved with the API ownership responsibilities.
The Blue Hat: API planner
The Blue Hat represents organisation, pulls teams together (“planning”)
It helps to plan, scope, and define an API product and its roadmap. The apply API modeling and design techniques to translate customer requirements and API design.
API architects are often required to develop an API program, including all of the standards, practices, processes, and checkpoints required to deliver APIs in the organisation. The Blue Hat helps them to develop these programs into an API guild, Center of Excellence (CoE), or Center for Enablement (C4E). They routinely perform a process and standards review to determine what is working, what needs to be changed, how can we ensure teams are able to produce/consume APIs unobstructed.
While they may not have every answer to every question, those wearing the Blue Hat are willing to seek input from others, opening up involvement to others in the organisation. They seek to break down organisational silos by looking across the organisation rather than a specific area in isolation.
Those with big picture thinking will wear the Blue Hat to manage the organisation’s API portfolio. They evaluate emerging APIs in context with the overall portfolio, identify gaps in the portfolio that need to be filled, and prune APIs that no longer fit.
Wrap-up
An API architect has to wear six different hats:
- API trendspotter (The White Hat)
- API reviewer (The Red Hat)
- API risk assessor (The Black Hat)
- API advocate (The Yellow Hat)
- API creator (The Green Hat)
- API planner (The Blue Hat)
Each one of these hats may be worn by a single person, a group of people, or spread across the organisation in different ways. For smaller organisations, a single person may be wearing most or all of the hats. The hat wearers may be officially recognised as an API architect, or it might be a function of another job title that you hold.
One thing is for certain: the role isn’t easy and probably has its ups and downs, but it can be rewarding. The important thing is to recognise the hats you wear, how often you or others are wearing them, and what hats are not being worn at all and how your organisation will fill the gap.
