Lessons From Training 1400+ People in Web API Design

For the last 2 years, Keith Casey and I have been conducted API training workshops with over 1400 participants across nearly a dozen roles. While we are still available for training engagements, we wanted to stop and take an assessment of what we have learned so far. We hope that by sharing these lessons, we will help your teams to become more educated and productive around the understanding and design of APIs.

Lesson #1: Involve everyone, including product and business

APIs aren’t like many of the software development technologies that tend to be hidden away in the implementation details. Instead, they are an architectural concern that requires involvement from a variety of team members beyond developers. As a result, a variety of different team roles need to be included: developers, QA teams, technical writers, product managers, product marketing, and ScrumMasters.

While some may argue that any of these team members could attend a developer-centric API training program and learn something, there are often some critical pieces missing when we only focus on developers:

• QA teams are often left out of standard training curriculum, leaving teams uncertain about how and when to test web APIs
• Technical writers are left out and are therefore uncertain of what to document, when, and what tools exist
• Product managers miss opportunities to build better business value and increase organization agility using web APIs
• Product marketing may lack clear understanding about developer concerns around web APIs, creating missed marketing opportunities
• ScrumMasters are unable to integrate the varying processes for designing, developing, and deploying great APIs compared to standard product development

By building in each of these aspects into your API training program, each member of your product team will better understand and apply the fundamentals of web API design and development.

Lesson #2: Focus on a product-based approach to APIs

In the early stages of API adoption, most APIs solve a specific problem and often begin as a bolt-on solution within an existing application. As a result, the API design is specific to the application and difficult to reuse.

Taking a product-based design approach to APIs encourages teams to think beyond a specific application. The result is the company seeing APIs as first-class products rather than integration solutions.

We found that training teams to think in terms of products (external or internal), rather than integration points for applications, opens up teams for those “AHA!” moments that differentiate market leaders.

Lesson #3: Train for the full API development lifecycle

During our workshops, we looked for opportunities to discuss how the various job roles should be involved with API planning, design, development, testing, marketing, and management. This helps prepare product teams for addressing real world problems, including missing or ambiguous requirements that could result in a poorly designed API.

To accomplish this, we use exercises that are outside of the team’s domain, resulting in a more focused learning process outside of company politics and problems. For our 2-day workshops, we also conduct a variety of group exercises that simulate API design from requirements, screen mockups, and existing database designs to better prepare teams to design APIs from real world circumstances.

Lesson #4: Cover the API fundamentals

The most important step when conducting API training is to get everyone to the same definition of an API. This may seem like an unnecessary step, but it is essential to cover the web API basics. Too many assume everyone in a product team knows what an API is and how they work.

If a single member of your team doesn’t understand API fundamentals, it can hurt the entire team. If some of your team members misunderstand some of the concepts, it could cause miscommunication, delaying or fixing your API design and development efforts – negatively impacting the business.

Also included in our training is an introduction to how HTTP works. On average, 25% of a class has never seen an HTTP request/response. Without a foundation in basic HTTP, learning web APIs will be difficult at best. Once they have a solid foundation in the basics of HTTP, examples of APIs will be better understood.

Lesson #5: Focus heavily on API thinking

Many API training programs spend a considerable amount of time digging in to the technical details of API design. While we agree that a great API design is essential, we have found that API modeling prior to API design is critical to product-based API thinking.

API modeling is the process of capturing the activities, or jobs-to-be-done, that users and developers will expect from the API. Without this preparation, too much of the focus is on the “how” of the API (i.e. the resources, HTTP verbs, and response codes) and less on the “what” and “why” of the API.

By focusing on API modeling first, everyone on the team can discuss and contribute to the core business needs. Team-based API modeling, rather than just involving dev leads and architects, is important. It helps to create team ownership of the API, rather than just developer ownership and ensures that everyone from the team becomes a stakeholder from inception to production and beyond.

Lesson #6: Keep code out of training – at the start

Refrain from getting too detailed too quickly on the implementation details. This is especially the case when developers build training materials, as they often want to get to the “show me the code” phase quickly.

However, we have found success in teaching the fundamentals, business drivers, governance guidelines, and basics of API design to all team members first. By taking this approach, we help the entire team become more effective at solving problems alongside product and business goals prior to focusing on code.

This doesn’t mean that those in the workshop don’t interact with APIs. Instead, we use tools such as cURL and Postman to interact with APIs. We simply skip the coding step initially.

If a deeper dive is desired by developers, it can be covered in a follow-up workshop tailored for more technical team members. However, leaving programming languages and frameworks out of it prevent developers from adopting bad or default design patterns from frameworks while skipping proper API design-first techniques.

Lesson #7: Prepare the team for success and follow-up afterward

Try to allocate a full day to the training when possible, with the attendees considered “out of the office” and unavailable for email, phone, or instant messaging. This requires scheduling the training during a time when there will be no new product releases or other projects due.

If necessary, split teams into separate groups to prevent an entire team from being away on the same day. This may require training across multiple days, but will keep the training on the same week to encourage better understanding as more team members attend the workshop.

Our workshops cover a lot of material in a short period of time, often in 1-2 days. This means that questions will arise. We make ourselves available via email for follow-up questions, as well as provide a copy of the slide deck and our book to reinforce the concepts and provide a reference as teams begin their API journey.