David Yonan is the founder of FlowStep.com. Flow step is a collaborative framework for software development and adopts an API and documentation first approach to defining requirements. The platform provides guardrails that enable staff to support Agile processes and complements existing design documentation and development tool sets that automate many tasks and improve people’s work quality. FlowStep makes building software with APIs easier, faster, and more enjoyable. In this article, David Yonan shares principles and practices that help shape the way you think about what you are building.
How do you make APIs the common language?
You need to make them relevant by adopting an API-first mindset. An API-first mindset requires a shift in how businesses think about and deliver. Teams need to design APIs that internal and external stakeholders can consume. They need to create API catalogs and API products that can be shared with different audiences.
This is a story in four parts. To get started, we need to agree on a few things. It takes a team of people who are aligned and working together to build the best software, and building the best software is a process. This process should start with identifying a problem the user has and end with an outcome that delights the user. APIs are central to this process because they provide the interactions that transmit the data and enable the outcome. APIs can be daunting when you’re unfamiliar with the challenges of building a successful program. These challenges go well beyond what’s covered in hello world examples. And real-world experience is invaluable.
Why do you create APIs?
People must understand why they’re creating APIs. You need to educate people on how APIs can enable and empower businesses. Do you want to do better business by enabling connectivity within your business, or do you want to do digital business by creating API products that can empower other businesses? The reality is you want to do both. And using APIs to do one will allow you to do the other.
How do you define APIs?
Does the experience define the technology, or does the technology define the experience? There’s no right or wrong answer because it will depend on the needs and the circumstances of the business. What is important is you listen to the consumers of the API because the API will only stay as relevant as long as it satisfies the needs of the consumers. We need to muster the troops now that we’ve established a foundation.
What motivates people across the business?
Once we understand their motivations, we can figure out how to get them involved. For business, it’s about winning. Product owners want to deliver value; designers want to design cool things. Developers want standards in the way things are done. Ops people want to have confidence in the work that’s being done.
Business – The business is responsible for ensuring that there is a business. Explain why building the business on APIs is a competitive necessity. For each problem, an API is a solution. Demonstrate how APIs will add reusable value, enable the business’s strategy, improve security, increase agility and reduce risk. These items are front of mind for many business stakeholders. You want to show them that APIs can address these challenges with each new deliverable. It’s a compelling proposition.
Product Owners – Product owners care more about the user’s needs than any other group. They’re measured by the value they deliver to the users and the business. They explained that an API, product owners, and software enable every screen sequence and interaction of value. The API product owners and software application product owners have different roles, responsibilities, and considerations, but the success of one is dependent on the other. They need to be involved in the API design process to allow them to understand and influence the roadmap. This allows them to coordinate when and how to deliver value.
Designers – Designers want to design cool things. Sometimes they don’t design realistic things. It’s because they don’t know what’s feasible. You need to tell them their designs are constrained by what the API does. Show them how APIs work and integrate them into the design process. Explain how different properties, parameters, and attributes can affect how an API behaves in the data it returns. Convince them to think about context as constraints as enablers. They often define the limits of what’s feasible. Encourage designers to get involved in the design of APIs, so they can influence what’s feasible, which allows them to do cool things.
Developers – They understand the tech and will probably be your biggest allies. If developers lack requirements to be documented in a standard format, they’ll probably ask many clarifying questions. It is because change is hard. It’s important that each change in clarification is documented because it gives developers a context that allows them to focus on the design and their work. Developers use APIs to contract between the business, the front end, and the back end. Get developers to explain to others how APIs provide a framework for standards and get them involved in the design process. There might be more questions upfront for developers to handle, but it means that there’s less change down the track.
Ops and Infra – Ops and infra people want confidence in their work. They don’t like to say no, but they often have to. They don’t want to have any services crash. Get them to explain how API gateways and service meshes can help the company deploy with confidence. Encourage them to help people understand how services combine to make up the applications that they are running. Tell them that the more people can understand how systems work, will eventuate in more realistic requests that come through.
Starting a project – While starting with a project, we start with a blank page. There’s no prompt structure or guidance. It’s not like we don’t understand the environmental or business constraints. Yet we expect people to know where to work and how to start. We assume that they’ll know, understand and follow the standards that other people have implemented. It doesn’t make sense. In my experience, every project should start with the same set of questions.
- What are we building, and what value does it add?
- What does success look like, and how do we scale that success?
- What are the APIs that we need, and what do they need to do?
- Do the services exist, and are they fit for purpose?
- What is the data and where does it live?
Documenting requirements – Some use a word document, excel sheet or have their own set of preferred tools. But, the larger problem is that the only way to identify and manage change in this environment is manually. The biggest challenge companies face is not posed by competition, technology, or regulation. It’s the people challenge. Humans are the most amazing, inspiring, and sometimes frustrating creatures. People are emotional beings influenced by any number of factors, and they’re usually outside your or their control. Despite the best intentions, people can rarely work to their full potential for extended periods.
Build Better Software Better – We’ve established a philosophy that guides the development strategy. Now we need a framework to support the development activities. Building better software can be difficult. Context is king.
Collaborative – You want to use the collective wisdom of your people, clients, and users. You want to explore problems and focus on people.
Design Thinking – Be mindful that the people you’re designing for developers build applications to connect systems, not necessarily people.
Promote Agility – You want to find a way to embrace change because changes are given. Remember that agile and agility are different things.
Structured – You want to be structured in how you do things. You want to look for patterns that create repeatable models. That’s the key to scaling.
Governance – You want to establish a foundation built on good governance. It’s about creating clear expectations for how people work, supported by checks and measures that allow people to work confidently. You need to think of it as freedom within a framework.
Tools – You want to figure out which tools you use but need to consider the observability nightmare. There will be requirements captured in different formats and systems. There could be many different artifacts, which are created in different formats and saved in different systems. Change is still possible, but it gets harder, and thus begins the observability nightmare. You want to use context and constraint to refine the collective understanding. The deeper you get into the design and documentation process, the harder it becomes to track the detail.
Avoiding observability nightmare – Design processes, finalize solutions, and identify APIs to create the different artifacts. The best understanding will come from a set of steps describing the processes and containing all relevant information. You want to use this information to identify the actions and interactions required to complete the processes and deliver the outcomes. Change now is a major challenge. It’s also no longer just the documentation that’s changing. This is where things start to get missed. This is the observability nightmare. Now it’s time to build a solution to minimize change. The only changes that should be approved are strategic ones. But that never happens.
In summary, you want to adopt API first. You want to understand the how and why of APIs. You want to solve the problem of the user and motivate people to consider the observability nightmare. Stop starting with a blank page; use a framework, and make APIs the common language.
