Jekyll2024-03-12T11:05:24-05:00https://launchany.com/feed.xmlLaunchAny - API Strategy & Digital Transformation ConsultingAPI Strategy and Design Consulting/Training , Cloud Native and Microservices Architecture Consulting based in Denver, Colorado Springs, and AustinJames Higginbothamjames@launchany.comA Look at API Program and Governance Trends for 20242024-01-04T09:29:00-06:002024-01-04T09:29:00-06:00https://launchany.com/apifutures-2024<blockquote>
<p>This article is part of APIFutures, a distributed, creator-led effort to identify the most significant opportunity and/or the greatest challenge facing the API community in 2024. You can check out other articles and viewpoints on the <a href="https://matthewreinbold.github.io/APIFutures/index.html">APIFutures landing page</a>.</p>
</blockquote>
<p>For some, 2023 was an amazing year for their API program. For others, 2023 will be remembered as a year where API programs were met with challenges such as reduced budgets and a mandate of “do more with less”. No matter what last year was for you, I want to share some insights of where I believe some of the biggest opportunities are for API programs in 2024.</p>
<h2 id="opportunity-1-a-leaner-api-program">Opportunity #1: A Leaner API Program</h2>
<p>Digital transformation initiatives have been underway for 5 years or more now, with the earliest adopters having started the effort 8 years ago or longer. Millions have been poured into the initiatives to realize cloud migrations, the shift to platform engineering through technologies such as Kubernetes, and a focus on API first culture.</p>
<p>Last year, the budgets slowed down, forcing the “do more with less” approach to API programs and enterprise IT in general. Some enterprises saw a reduction in their API program budget, while others continued to maintain their commitment to their API program and an API first culture.</p>
<p>Things are shifting back to the business. No more expansive rewrites and modernization. We had years to get that done. Time to deliver value to business and customers. APIs are at the center of this, but it will require a leaner API program.</p>
<p>This shift to a leaner API program was seen through several trends that we predict will continue into 2024:</p>
<ul>
<li><a href="/api-training/">Self-service API training resources</a> to equip their product owners and technical leadership in necessary API skills</li>
<li>Establishing a <a href="/scaling-your-api-program-with-federated-coaching/">federated API coach program</a> to equip leaders across the organization</li>
<li><a href="/api-c4e-engagement-models/">Adding API governance engagement models</a> to extend the effectiveness of the API program through office hours, collaborative design sessions, and API design facilitation for high-profile initiatives</li>
</ul>
<p><strong>Summary:</strong> Expect a continued effort to produce a leaner API program through self-service API training, establishing a federated API coach program, and new API governance engagement models that make better use of time and resources.</p>
<h2 id="opportunity-2-realizing-the-goal-of-api-reuse">Opportunity #2: Realizing the Goal of API Reuse</h2>
<p>When we speak with organizations of all sizes and industries, one of the top 3 goals for their API program is reuse. Whether the reuse is focused internally (“localized API reuse”) or intended to drive optimized partner and customer integrations (“globalized API reuse”), the intent is the same: organizations are seeking a culture of “consume when possible, build when necessary”.</p>
<p>Last year, we saw organizations focusing their efforts around <a href="/effective-api-programs/">API portfolio ownership</a>, which included disciplines such as API discovery, API cataloging, and API lifecycle management. Some organizations used these efforts to track unused APIs (“zombie APIs”) or unknown APIs (“shadow APIs”) to prevent them from compromising their systems. However, the longer-term goal by most of these organizations is to catalog and offer APIs to their internal developers, partners, and customers.</p>
<p><strong>Summary:</strong> Expect to see a continued focus on API portfolio ownership, including the discovery and cataloging of all types of APIs and digital assets.</p>
<h2 id="opportunity-3-the-growth-of-the-api-product-manager">Opportunity #3: The Growth of the API Product Manager</h2>
<p>APIs are becoming the lingua franca of today’s digital business. APIs are the digital front door to every organization. This is resulting in conversations about API capabilities and API onboarding by everyone - from account managers to product leaders and executives.</p>
<p>Last year, we saw that many organizations had to quickly <a href="/api-training/api-fundamentals-course/">upskill their staff in API fundamentals</a>. We also noticed that organizations had to adjust their processes to support routing API-related discussions to product owners or business product managers that were familiar with the APIs in the particular domain area.</p>
<p>No longer are product owners and product managers limited to overseeing partner integrations, web apps, and mobile apps. Digital assets such as APIs, events, and data will become the responsibility of product leaders to own and manage. Training in the concepts of applying a digital product mindset and understanding of API fundamentals will be necessary for this new role.</p>
<p>Product leaders will also be expected to manage APIs through their full lifecycle. This means applying a digital product mindset, including product discovery, to APIs. Product leaders will rethink the fit-for-purpose approach to API delivery, instead applying productization for reuse into the typical partner integration project.</p>
<p>This will require the specialized role of API product manager to become more common in organizations starting in 2024. This role will demonstrate the use of APIs for their partners by making simple API requests to demonstrate value. They will be participating in API onboarding calls that were traditionally left to technical leaders to help them identify gaps in the onboarding process, spot improvement opportunities in API documentation, and add missing API capabilities to their backlog. Existing product leaders will require coaching in skills such as API fundamentals, API design, and <a href="/effective-api-programs/">full API lifecycle ownership</a>.</p>
<p><strong>Summary:</strong> Expect to see an increased focus in the role of API product manager, with a focuse on the full API lifecycle, skills in using and designing APIs, and API productization to better support new business opportunities.</p>
<h2 id="final-thoughts-on-the-evolution-of-api-programs">Final Thoughts on the Evolution of API Programs</h2>
<p>The landscape of API programs and governance is poised for significant evolution in 2024. Organizations are moving towards a more efficient and effective management of their API initiatives, driven by the need to optimize resources and deliver value more rapidly. Three key opportunities stand out:</p>
<ol>
<li>
<p><strong>The Development of a Leaner API Program:</strong> Enterprises will streamline their API programs, focus on self-service API training, implement federated API coaches, and expand their API engagement model. This lean approach aims to enhance effectiveness while optimizing the use of resources.</p>
</li>
<li>
<p><strong>Enhancing API Reuse:</strong> The growing emphasis on reuse will drive demand for API portfolio ownership, focus on API discovery and cataloging, and improved lifecycle management of APIs. This approach seeks to maximize the reuse of APIs, both internally and externally, aligning with the principle of “consume when possible, build when necessary.”</p>
</li>
<li>
<p><strong>Rise of the API Product Manager Role:</strong> As APIs have become integral to digital business, the role of the API product manager is gaining prominence. This specialized product leadership role will be pivotal in managing APIs throughout their lifecycle while applying a digital product mindset to ensure APIs are fit for purpose and contribute to new business opportunities.</p>
</li>
</ol>
<p>Overall, 2024 appears to be a year where the alignment of API strategies with business goals will be crucial.</p>James Higginbothamjames@launchany.comA look at the API program challenges and opportunities in 2024Unlocking Opportunities with API Generation Software2023-12-04T09:39:00-06:002023-12-04T09:39:00-06:00https://launchany.com/unlocking-opportunities-with-api-generation-software<p>Anyone who was spent time in one of my API design workshops or read some of my articles knows that I prefer a user-centric approach to API design. While I recognize that taking a <a href="https://launchany.com/should-you-expose-your-database-directly-using-a-rest-api/">data-based API design approach is sometimes warranted</a>, I prefer an approach that <a href="https://launchany.com/api-training/rest-api-design-workshop/">focuses on delivering outcomes</a>.</p>
<p>My hesitation is often due to the use of a code generator to blindly turn data models into an API model. These generators did nothing more than turn DDL into a JSON serialized format. They added no value and often came with no additional business logic – just pure and simple SQL over HTTP.</p>
<p>However, I was recently introduced to <a href="https://www.g2.com/categories/api-generation">a new G2 category, API Generation Software</a>. This category combines elements of code generation with API management and a more customizable approach to API generation. <a href="TODO link to article when published">I recently wrote about this new category</a>, including the common capabilities, advantages, and challenges presented by these tools.</p>
<p>In reviewing some of the product offerings in this category, I came to realize that this is not an old-school approach to code generators. Instead, they present opportunities to unlock data from existing systems, drive the generation of API prototypes, and accelerate enterprise integration strategies commonly found within traditional IT departments. Let’s look at each of these opportunities and how this new category of API tools may become a valuable part of your API enablement.</p>
<h2 id="1-speeding-up-integrations-as-part-of-an-eip-strategy"><strong>1. Speeding Up Integrations as Part of an EIP Strategy:</strong></h2>
<p>Enterprise Integration Platforms (EIPs) play a pivotal role in connecting diverse systems, applications, and data sources within an organization. API generation software complements EIP strategies by:</p>
<ul>
<li>
<p><strong>Accelerating Development:</strong> API generation software expedites the creation of connectors and APIs required for integration, reducing the time and effort needed to implement complex integration scenarios.</p>
</li>
<li>
<p><strong>Agility and Scalability:</strong> EIPs often require flexibility and scalability to accommodate changing business needs. API generation software provides the agility to respond quickly to new integration demands.</p>
</li>
<li>
<p><strong>Reducing Development Overheads:</strong> By automating code generation and data mapping, API generation software frees up development resources to focus on strategic integration tasks.</p>
</li>
</ul>
<h2 id="2-rapid-prototyping-of-apis"><strong>2. Rapid Prototyping of APIs:</strong></h2>
<p>One of the most compelling opportunities offered by API generation software is the ability to rapidly prototype APIs. Traditionally, developing APIs could be a time-consuming and complex process, requiring extensive coding and testing. With API generation software, organizations can now create API prototypes swiftly and efficiently, enabling them to:</p>
<ul>
<li>
<p><strong>Innovate Faster:</strong> By reducing the time and effort needed to create APIs, businesses can experiment with new ideas and innovations more rapidly, staying ahead of the competition.</p>
</li>
<li>
<p><strong>Validate Concepts:</strong> Prototyping allows organizations to validate the feasibility and functionality of APIs before committing to full-scale development, reducing the risk of investing in unsuccessful projects.</p>
</li>
<li>
<p><strong>Gather Feedback:</strong> API prototypes can be shared with stakeholders and potential users for feedback, ensuring that the final API design aligns with their needs and expectations.</p>
</li>
</ul>
<p><strong>3. Building System APIs:</strong></p>
<p>API generation software is not limited to creating APIs for external consumption. It can also be used to build system APIs that provide access to legacy systems. These APIs:</p>
<ul>
<li>
<p><strong>Unlock existing systems and platforms:</strong> System APIs allow legacy systems and platforms to to expose data through APIs. In some cases, these system APIs provide context to legacy systems that are used for a variety of needs across lines of business. Leveraging API generation software enables context-based system APIs to be generated quickly and easily for use by other teams in the organization.</p>
</li>
<li>
<p><strong>Avoiding the need to understand existing systems:</strong> System APIs help to abstract the complicated internals of existing systems. Codes can be translated into more meaningful values for use by developers not familiar with the internals of the system.</p>
</li>
<li>
<p><strong>Adapting to change:</strong> By encouraging integration through system APIs, updates to newer versions can be easily adapted to work with previous API clients. API generation software supports rapidly deploying updates that can contain transformation code to ensure that existing API clients continue to operate as expected while a newer version of the API is generated to take advantage of the latest features of an updated system.</p>
</li>
</ul>
<p><strong>4. Turning Data Sources into Private APIs:</strong></p>
<p>API generation software empowers organizations to turn their data sources into private APIs, unlocking valuable insights and enhancing data accessibility:</p>
<ul>
<li>
<p><strong>Internal Data Accessibility:</strong> Private APIs make it easier for internal teams to access and leverage data from various sources, promoting data-driven decision-making.</p>
</li>
<li>
<p><strong>Custom Data Integration:</strong> Organizations can create custom data integration solutions tailored to their unique needs and data sources, ensuring data flows seamlessly.</p>
</li>
<li>
<p><strong>Data Monetization:</strong> Private APIs enable organizations to monetize their data assets by securely exposing them to authorized users or partners, creating new revenue streams.</p>
</li>
</ul>
<h2 id="conclusion">Conclusion</h2>
<p>In the dynamic landscape of modern technology, businesses are constantly seeking ways to innovate, streamline processes, and harness the full potential of their data and applications. API generation software has emerged as a transformative force, opening up a multitude of opportunities that can reshape how organizations operate and thrive in the digital era.</p>
<p>In this article, we explored the exciting new opportunities presented by API generation software, from rapid prototyping to powering EIPs, creating system APIs, and transforming data sources into private APIs. I would encourage you to explore this new category of API tools to see how it could benefit your organization.</p>James Higginbothamjames@launchany.comAPI generation software presents new opportunities for enterprisesAccelerating Digital Transformation with API Generation Software2023-12-04T09:39:00-06:002023-12-04T09:39:00-06:00https://launchany.com/accelerating-digital-transformation-with-api-generation-software<p>In today’s fast-paced digital landscape, businesses are constantly seeking innovative solutions to streamline their operations and stay ahead of the competition. One of the key elements of the digital transformation journey is the effective use of Application Programming Interfaces (APIs). APIs serve as the building blocks of modern software applications, enabling seamless data exchange and integration between different systems and services. However, designing and delivering APIs can be a time-consuming process. Let’s explore a new category of tooling called API generation software that can help to alleviate some of these challenges, enabling organizations to respond quickly and efficiently to emerging market needs.</p>
<h2 id="doing-more-with-less-with-api-generation">Doing more with less with API generation</h2>
<p>In this “do more with less” economy, reducing the time and cost of API delivery can offer an advantage for organizations that need to support internal application developers and partner integrations. API generation software is a <a href="https://www.g2.com/categories/api-generation">new category from G2</a> that recognizes tooling that allows users to rapidly create, deploy, and secure data-driven APIs.</p>
<p>API generation software is a game-changing tool that empowers IT and business developers to rapidly create and deploy APIs securely. This technology leverages a low-code interface that allows users to connect to a data source and generate an API using the underlying data model. While these tools have existed for some time, what differentiates this category of API tooling is their support for customization using a low-code approach for customized scripting, fine-grained security, and automated deployment. Essentially, API generation software abstracts the intricacies of API design, making it possible to achieve instant and secure API creation.</p>
<h2 id="key-capabilities-of-api-generation-software">Key capabilities of API generation software</h2>
<p>Let’s delve deeper into some of the key capabilities of API generation software:</p>
<ol>
<li>
<p><strong>Multiple data source connectors</strong>: API generation software expedites the process of setting up connectors to access data from databases and networks. This feature is especially valuable in today’s data-driven world, where organizations rely on real-time access to information to make critical decisions.</p>
</li>
<li>
<p><strong>Access Control:</strong> API generation software includes built-in access control mechanisms. This ensures that only authorized users and applications can interact with the APIs, enhancing security and data protection. Role-based access control (RBAC) is commonly offered, providing more fine-grained access control than traditional code generation solutions.</p>
</li>
<li>
<p><strong>Rate Limiting:</strong> To prevent abuse or overuse of APIs, rate limiting features are often incorporated. This helps organizations maintain the performance and reliability of their systems while optimizing resource utilization. API generation software can provide rate limiting out-of-the-box, or defer to an API gateway or API management platform to control and manage rate limits.</p>
</li>
<li>
<p><strong>Auto-Generated Documentation:</strong> High-quality documentation is crucial for developers to understand and utilize APIs effectively. API generation software simplifies this task by automatically generating documentation, reducing the burden on developers and improving API usability.</p>
</li>
<li>
<p><strong>Script Editing and Fine-Tuning:</strong> While API generation software accelerates the API design process, it also offers flexibility. Developers can access and edit the underlying script of their APIs to fine-tune logic and functionality, ensuring that APIs align perfectly with their organization’s unique requirements.</p>
</li>
</ol>
<p>API generation software empowers organizations to transform their digital landscape by expediting API development, enhancing security, and optimizing resource utilization. It is a tool that bridges the gap between business needs and technical execution, making it an invaluable asset for digital transformation initiatives.</p>
<h2 id="advantages-of-api-generation">Advantages of API generation</h2>
<ol>
<li>
<p><strong>Rapid Creation and Deployment</strong>: This software allows users to quickly generate and deploy APIs in a secure environment. By setting desired parameters through a user-friendly, low-code interface, the software scripts the logic and configuration, significantly reducing the time and technical expertise required for API development.</p>
</li>
<li>
<p><strong>Abstraction of API Design</strong>: One of the core advantages of API generation software is its ability to abstract the API design process. This enables instant, secure creation of APIs, making it an invaluable tool for businesses needing to quickly adapt to market changes or customer needs.</p>
</li>
<li>
<p><strong>Versatile Connectivity</strong>: Users can easily set up connectors using a variety of standardized API types, allowing for seamless data extraction from databases and networks. This versatility is crucial for organizations that manage large volumes of data across different platforms.</p>
</li>
<li>
<p><strong>Flexibility for Developers</strong>: While the software simplifies and shortens the API design process, it also offers flexibility. Developers can delve into the script of their APIs, fine-tuning the logic and functionality to meet specific requirements. This blend of simplicity and customizability makes it an ideal choice for businesses at various stages of digital maturity.</p>
</li>
<li>
<p><strong>Integration with existing API Management Tools</strong>: API generation software is not an isolated tool but often works in tandem with API management solutions. This integration provides developers with the capability to monitor, control, and even monetize the APIs they create. This allows generated APIs to be managed using existing investments, rather than introducing yet another API management platform into the ecosystem.</p>
</li>
</ol>
<h2 id="when-api-generation-software-isnt-a-fit">When API generation software isn’t a fit</h2>
<p>API generation software offer many benefits, but they also come with their set of challenges and limitations. It’s essential to consider these challenges and evaluate whether API generation tools are the right choice for a specific solution. Here are some challenges of API generation software:</p>
<ol>
<li>
<p><strong>Limited Customization:</strong> While API generation software offers scripting support for customization, it may not always support the complexity require for some APIs. This can limit the API’s capabilities when trying to meet unique requirements for internal and partner APIs. Businesses with highly specialized or complex needs may find these tools too restrictive.</p>
</li>
<li>
<p><strong>One-Size-Fits-All Approach:</strong> API generation software is designed to cater to a wide range of use cases, but sacrifice some of the developer experience unless properly addressed. Poorly designed data models may be surfaced directly through the API, resulting in a poor developer experience. However, this can be mitigated through customized queries that transform internal data models into a more approachable API resource design.</p>
</li>
<li>
<p><strong>Complex Data Transformations:</strong> If an API requires intricate data transformations, such as aggregating data from multiple sources, performing complex calculations, or implementing specific business logic, API generation software may not handle these scenarios well.</p>
</li>
<li>
<p><strong>Security and Compliance:</strong> While API generation software often includes role-based access capabilities, businesses with stringent security and compliance requirements may need to implement additional security measures or customize API behavior, which can be challenging with pre-built tools. This is common in industries that require data entitlements to be enforced in addition to RBAC.</p>
</li>
<li>
<p><strong>Legacy Systems Integration:</strong> API generation tools may not seamlessly integrate with legacy systems or technologies that have unique integration challenges. Compatibility issues may arise, necessitating custom solutions.</p>
</li>
<li>
<p><strong>Performance Optimization:</strong> For applications with high-performance requirements, fine-tuning and optimizing API performance may be challenging with API generation software. Custom code and optimizations may be necessary, requiring the involvement of more senior developers as part of the process.</p>
</li>
<li>
<p><strong>Vendor Lock-In:</strong> Some API generation tools may lock businesses into a particular vendor’s ecosystem or proprietary formats, limiting future flexibility and scalability.</p>
</li>
<li>
<p><strong>Complex Use Cases:</strong> Complex use cases that involve multi-step workflows, asynchronous processing, or stateful interactions may not be well-suited for API generation tools, which often focus on simpler request-response APIs.</p>
</li>
</ol>
<h2 id="conclusion">Conclusion</h2>
<p>It is crucial that IT leaders recognize the significance of API generation software in the organization’s journey towards establishing and maturing your API platform. By leveraging API generation software, you can accelerate your digital initiatives, unlock new opportunities, and stay ahead in an increasingly competitive market. This will allow teams to focus on high-value APIs that require more thoughtful API design and delivery processes. However, be sure to perform an assessment of the problem space and ensure that API generation software is the right fit for your next project.</p>James Higginbothamjames@launchany.comReduce the time it takes to design your APIIntegrating API Generation Software into the API Delivery Lifecycle: A Strategic Approach2023-12-04T09:39:00-06:002023-12-04T09:39:00-06:00https://launchany.com/integrating-api-generation-software-into-the-api-delivery-lifecycle<p>The introduction of <a href="/accelerating-digital-transformation-with-api-generation-software/">API Generation Software</a> is offering new opportunities to enhance the traditional API delivery lifecycle. This includes accelerating the API delivery process for integration and data-driven API design is a better choice than the traditional user-driven API design approach. This article explores how integrating API generation tools into the API lifecycle can streamline processes, enhance productivity, and align API development with strategic business goals.</p>
<h2 id="user-driven-api-design-vs-data-driven-api-design">User-Driven API Design vs. Data-Driven API Design</h2>
<p>User-driven API design, as the name suggests, places the end-user at the center of the design process. The primary goal is to create APIs that cater to the specific needs, preferences, and expectations of those who will consume them. These users could be developers, partners, or even customers.</p>
<p>In contrast, data-driven API design prioritizes the organization and accessibility of data and functionality within an application or system. The primary objective is to expose data and processes efficiently, making it accessible for various use cases.</p>
<p>Historically, a data-driven API design was solely focused on exposing a database table or view as an API. This led to exposing internal data model details to API consumers, an anti-pattern that often results in fragile APIs that can break consumers when the underlying data model changes. All data was treated the same and had the same authorization rules applied.</p>
<p>Due to these inefficiencies, data-driven API design was only considered for specific circumstances. However, API generation software is causing IT teams to give data-driven API design a second look.</p>
<h2 id="rethinking-data-driven-api-design">Rethinking Data-Driven API Design</h2>
<p>With the introduction of API generation software, <a href="https://launchany.com/should-you-expose-your-database-directly-using-a-rest-api/">many of the challenges encountered with data-driven API design</a> are addressed. This new category of API tooling now supports more robust mapping of data to the API resource model, often through a visual builder. Access roles can also be applied to restrict access to the underlying data, ensuring that modifications to the data cannot be made without prior authorization.</p>
<p>Additional patterns, such as pagination and rate limiting, ensure that the API doesn’t negatively impact the underlying data store performance due to large queries or aggressive API clients. Plus, low-code support in many of the tool offerings allows for a more customizable API to meet business needs, without the need to craft each line of code using a traditional approach.</p>
<h2 id="incorporating-api-generation-into-the-api-delivery-lifecycle">Incorporating API Generation into the API Delivery Lifecycle</h2>
<p>This maturity of API generation software tools has IT groups rethinking how they deliver APIs that are meant to support system integration and rapid delivery of data via APIs. Plus, these tools support organizations with a mature API delivery lifecycle to properly incorporate API generation into their common practices. API generation no longer lives outside of the API delivery lifecycle, but rather complements it by accelerating many of its phase.</p>
<p>Below is a summary of how the API delivery lifecycle is accelerated by API generation tools:</p>
<p><img src="/images/diagrams/api-generation-lifecycle.png" alt="The API Generation Software Lifecycle" /></p>
<p>Let’s look at each phase and explore how API generation tools can be incorporated to accelerate the API delivery process:</p>
<h3 id="1-plan-identifying-the-need-for-speed-and-efficiency">1. Plan: Identifying the Need for Speed and Efficiency</h3>
<p>In the planning phase, organizations identify the need for a new API or the improvement of an existing one. This involves defining the API’s purpose, target audience, and strategic goals, as well as outlining the scope and requirements.</p>
<p>Organizations now have the option of taking a user-driven API design approach that is focused on user experience for more complex solutions, while accelerating the design and delivery phases using API generation tools. While some compromises in the API design will be made for the sake of speed, a data-driven API design doesn’t have to directly expose the data model. Instead, customizations and low-code tooling may be used to incorporate both data and user-driven design elements at a much higher velocity than traditional design methodologies.</p>
<h3 id="2-design-mapping-the-data-to-the-api">2. Design: Mapping the Data to the API</h3>
<p>During the design phase, the API’s architecture, endpoints, data models, and user interfaces are carefully planned and documented. It is crucial to create a clear design that aligns with the intended use cases and business objectives.</p>
<p>API generation tools shine by offering low-code interfaces that simplify the design of the API. These tools enable designers to visualize and document the API’s structure efficiently, ensuring that the design aligns with both technical and business objectives.</p>
<h3 id="3-prototype-visualizing-with-agility">3. Prototype: Visualizing with Agility</h3>
<p>Prototyping, a stage critical for validation, benefits immensely from API generation software. By quickly creating functional mock-ups, stakeholders can provide immediate feedback, leading to a more refined and targeted API design. This rapid prototyping not only saves time but also increases the prototype’s accuracy in meeting user needs. Plus, live data from production or sanitized data sources may be used to better understand the API’s design rather than using a test data set.</p>
<h3 id="4-implement-streamlined-development">4. Implement: Streamlined Development</h3>
<p>In the implementation phase, developers write the code to build the API based on the design specifications. This phase includes coding, database integration, and the development of any necessary logic.</p>
<p>API generation tools automate the coding and integration tasks, turning weeks of development time into an almost immediate delivery process. This automation reduces human error and accelerates the development process, allowing developers to focus on more complex and creative aspects of API development.</p>
<h3 id="5-secure-built-in-security-measures">5. Secure: Built-in Security Measures</h3>
<p>Security is a critical aspect of API development. In this phase, security measures such as authentication, authorization, encryption, and access controls are identified and implemented to protect the API and its data. In most cases, this involves defining configuration rules that will be applied when publishing to an API gateway.</p>
<p>API generation software provides a low-code method of defining role-based access controls (RBAC), ensuring that security is integrated into the API from the outset. This is a significant improvement from simple code generators that apply no authorization rules without significant effort.</p>
<h3 id="6-publish-and-test-efficiency-in-deployment-and-testing">6. Publish and Test: Efficiency in Deployment and Testing</h3>
<p>The next step in the API lifecycle is to publish details of the API to an internal API catalog and/or an external developer portal. This makes the API available for use by developers before being rolled out to production to gain feedback from consumers. The phases are repeated to incorporate changes until the API is ready for promotion to a production environment.</p>
<p>Upon publishing, the API enters a crucial testing phase. Here, API generation tools can facilitate automated testing procedures, ensuring comprehensive coverage of functional, load, and security testing. This leads to a more robust and reliable API.</p>
<p>Note that as of this article’s publication date, most API generation tools are not capable of publishing to an API catalog or portal directly. They do generate documentation to assist in this process.</p>
<h3 id="7-document-auto-generated-documentation">7. Document: Auto-Generated Documentation</h3>
<p>API documentation is crucial for users to understand how to interact with the API effectively. This phase involves creating comprehensive documentation that includes usage instructions, endpoints, parameters, and examples. For external-facing APIs, additional documentation may be produced, such as a getting started guide, examples, and an optional reference application.</p>
<p>Documentation is streamlined with API generation software. It automatically generates reference documentation, often in the <a href="https://www.openapis.org/">OpenAPI Specification format</a>. This reduces manual documentation effort and ensures accuracy and consistency.</p>
<h3 id="8-deploy-monitor-and-monetize-continuous-improvement-and-revenue-generation">8. Deploy, Monitor, and Monetize: Continuous Improvement and Revenue Generation</h3>
<p>Deployment involves making the API accessible to users and systems in a production environment. It includes setting up servers, configuring network settings, and ensuring scalability and reliability. This step also includes making the API accessible through an API gateway and applying all security configurations. Continuous monitoring is then applied to track API performance, usage, and health in real-time.</p>
<p>API generation software offer rapid deployment and rate limiting to support quick deployment without the need for existing API management infrastructure. Deployments often occur in only a few seconds, without the need to stand up a full CI/CD pipeline.</p>
<p>However, it is not necessary to leverage the capabilities of these tools. Organizations are able to leverage their existing investments in their CI/CD processes and API management infrastructure to properly deploy, secure, monitor, and monetize their APIs.</p>
<p>For organizations looking to generate revenue from the API, the monetization phase involves implementing billing, pricing, and subscription models. It may also include enforcing usage limits and tracking API consumption. API generation tooling typically doesn’t have this built-in, so an API management platform is often required to support monetization.</p>
<h3 id="9-maintain-adapting-to-change">9. Maintain: Adapting to Change</h3>
<p>The maintenance phase is ongoing and involves regular updates, bug fixes, security patches, and feature enhancements. Maintaining API quality and performance is critical to meet evolving user needs. This often involves going through the same lifecycle once again, applying these enhancements into a new API revision.</p>
<p>In the maintenance phase, API generation software simplifies updates and adaptations, enabling APIs to evolve with changing business needs and technology landscapes. Caution must be applied, however, to prevent introducing breaking changes in the API design that could result in API consumers scrambling to adapt to changes. Some tools are capable of warning of breaking changes to prevent causing an outage with API consumers.</p>
<h2 id="conclusion">Conclusion</h2>
<p>API generation software is forcing IT to rethink its approach to API design from user-centric to a hybrid approach that includes data-centric API design. By blending both approaches, enterprises are able to rethink the way they approach their API strategy to support high-velocity delivery. Integrating API generation software accelerates each phase of the lifecycle, from planning to maintenance, API generation software aligns API development closely with business strategies, paving the way for innovation and growth in the digital world.</p>
<p>While API generation software is not a silver bullet, thoughtful application of these tools will enable enterprises to accelerate their integration efforts through a low-code approach to API design and delivery. Unlike tools that promised similar outcomes in the past, these data-driven APIs can be integrated into the same lifecycle as their user-centric APIs. This new category of API tooling should be evaluated by enterprise leadership to determine how it can accelerate their API roadmap.</p>James Higginbothamjames@launchany.comAPI generation software is rethinking how you design APIs5 Ways Your API C4E Can Engage and Enable Teams2023-07-05T09:23:00-05:002023-07-05T09:23:00-05:00https://launchany.com/api-c4e-engagement-models<p>When you think of an API Center for Enablement (API C4E), what comes to mind? Perhaps you think of API style guides, API design style selection, and design review processes. While this is a critical element of any API C4E, there is another important aspect that needs to be considered: <em>What are the engagement models that the API C4E will use to enable API producer and consumer teams?”</em></p>
<p>The role of an API C4E isn’t just about enforcing the rules set forth in various API governance documents. It also includes a variety of engagement models that are necessary to meet teams where they are today and help them to deliver high-quality API designs that meet the needs of end users and API consumers.</p>
<p>Let’s look at five important engagement models that an API C4E can use to enable and empower teams to deliver high-quality, reusable APIs across the organization.</p>
<h2 id="api-c4e-engagement-model-1-community-support">API C4E engagement model #1: Community support</h2>
<p>One of the most impactful and least time-consuming engagement models is to engage in API community support. These engagements offer quick turnaround through a question and answer format. Some API programs implement this through Slack or Teams rooms that are open for anyone to join and ask questions. Answers might include directing the person to an example of how a particular design problem was solved by another team. The API C4E representatives can also provide links to standards and practices documents that set expectations and share examples of preferred approaches.</p>
<p>For organizations that have an internal Stack Overflow site, a more discussion-oriented approach to community support can be offered. In this case, not only may the API C4E answer questions but also the API community at large. In some cases, we’ve seen both chat rooms and Stack Overflow used to offer immediate interactions, combined with a frequently asked questions (FAQ) approach for a more self-service approach.</p>
<h2 id="api-c4e-engagement-model-2-office-hours">API C4E engagement model #2: Office hours</h2>
<p>Not all API-related questions can be answered in a chat session. In those cases, a weekly recurring office hours is made available for people to bring their questions. The API C4E established a consistent day and time for people to join and raise questions, allowing for slightly longer engagements. This format supports screen sharing, allowing a guided walkthrough of the proposed solution and discussion of alternative approaches.</p>
<p>Because the number of attendees may vary week-to-week, interactions are typically limited to 10 or 15 minute discussions. If a single team is the only one raising questions that week, the API C4E may continue to extend the time allocated to the team during office hours. In some cases, more time may be required to dig into the challenge further. That is the purpose of our next engagement model.</p>
<h2 id="api-c4e-engagement-model-3-api-design-session">API C4E engagement model #3: API design session</h2>
<p>An API design session is a one-hour discussion focused on a specific area of a team’s API design challenges. These may be requested using a form-based approach, such as through a <a href="http://www.servicenow.com/">ServiceNow</a> workflow, or simply scheduled during office hours as time runs out.</p>
<p>These design sessions may require more than one hour, especially when more context is required to fully understand the problem. In this case, consider booking 90 minutes for the first meeting and a follow-up hour meeting should the team request further discussion.</p>
<h2 id="api-c4e-engagement-model-4-api-design-review">API C4E engagement model #4: API design review</h2>
<p>An API design review is often a mandatory step prior to the release of an API into production. While some aspects of the review may be automated using an API linter, there will still be design elements that a machine cannot review and flag. This is where an API C4E design review engagement model is used to help ensure consistency and that future API consumers will have a good developer experience with the API design and documentation provided by the team.</p>
<p>Teams should be encouraged to create a sequence diagram demonstrating how the API will be used to deliver on the outcomes desired by the identified personas. A README mock-style document, demonstrating HTTP request and response pairs, may be used to provide greater fidelity and convey intent on how an API is meant to be used.</p>
<p>Performing an API design review often takes some up-front work, including the review of any documentation artifacts (e.g., OpenAPI Specification document) prior to the meeting. Therefore, time should be allocated prior to the review meeting, an hour for the review meeting, and another 30 minutes or so to write-up and share recommendations with the team afterward.</p>
<p><strong>A word of caution about API design reviews:</strong> API design reviews can either be a positive experience for teams or a negative one. Focus on finding opportunities for improvement and be clear on your expectations of what must be changed prior to a production release. Avoid making the design review a negative experience that causes teams to circumvent processes or share their negative experiences with others in the organization.</p>
<h2 id="api-c4e-engagement-model-5-api-design-facilitation">API C4E engagement model #5: API design facilitation</h2>
<p>The final engagement model we will discuss is API design facilitation. There may be circumstances where teams are either new to API design or perhaps are comprised of mostly offshore teams that lack a deeper understanding of business intent. In these situations, the API C4E may need to faciliate design sessions to guide the team through the process and ensure alignment with business goals.</p>
<p>These “white glove” engagements are demanding and are often applied to high-profile and/or high-priority initiatives that benefit from additional hands-on design guidance. The API C4E should not be expected to faciliate a series of design sessions for every team in the organization.</p>
<h2 id="investment-of-time-for-api-c4e-engagements">Investment of time for API C4E engagements</h2>
<p>As you may have noticed, different engagement models demand different time investments. The diagram below shows the kind of time investment required for each engagement model:</p>
<p><img src="/images/diagrams/api-c4e-engagement-model-investment.png" alt="Time investment required for each API C4E engagement model" /></p>
<p>Not every API C4E will be sufficiently staffed to support all of these engagement models. Start with engagement models that your API C4E can support with time available while offering the best impact to teams. If necessary, you may find that you need to scale your engagement model through the introduction of an API coach program.</p>
<h2 id="scaling-the-api-c4e-engagement-model-with-api-coaches">Scaling the API C4E engagement model with API coaches</h2>
<p>As previously mentioned, the more API C4E engagement models necessary to support your organization, the more time investment is required. Implementing a <a href="/scaling-your-api-program-with-federated-coaching/">federated API coaching program</a> offers many benefits for your API C4E:</p>
<ul>
<li>Coaches serve as advocate of an API first mindset by guiding teams in more strategic API designs</li>
<li>API design issues are addressed earlier in the delivery process when the cost of change is lower</li>
<li>Teams are directed toward API C4E standards, conventions, and guidelines thereby avoiding rework later</li>
<li>Coaches are able to combine context of the domain area with standards to advise on where deviations to the standards should be applied</li>
<li>Faster turn-around time for API design review and approval processes</li>
<li>Institutional memory is better preserved for the domain as API coaches and delivery teams are aligned in understanding of the problem and solution</li>
<li>API designs are higher quality without wasted time and effort, and over time the cohesion of the API platform and portfolio catalog is improved</li>
<li>Encourage the creation of reusable APIs within and across domains for partner and internal developer support</li>
</ul>
<p>If you are struggling to scale your API C4E, consider implementing a federated API coach program in your organization.</p>
<hr />
<p><i class="fa fa-lightbulb-o fa-5x" aria-hidden="true" style="float: left; padding-right: 10px; "></i> Need some additional insights into your API C4E engagement models and establishing an API coaching program? LaunchAny partners with organizations of all sizes to establish, scale, and mature their API program. <a href="/contact/">Contact us to find out more</a>.</p>James Higginbothamjames@launchany.comExplore ways your API C4E can support delivery teamsSelecting an API Governance Model2023-07-04T10:39:00-05:002023-07-04T10:39:00-05:00https://launchany.com/api-governance-models<p>Today’s API governance is not like the kind of governance familiar to those that went through the service-oriented architecture (SOA) days. Many organizations have learned from past mistakes, opting instead for a lighter-weight governance model. No longer does API governance focus on internal optimization. Rather, today’s API governance is focused on the external developer experience. It is meant to advocate for the current and future API consumers, while delivering value for the business.</p>
<p>Choosing an API governance model can be challenging, however. There are a variety of options available. How are you supposed to know which one is best for your organization?</p>
<p>Let’s look at what a healthy API governance program includes, then examine the different models of API governance to see which one may be the right fit for your organization.</p>
<h2 id="what-does-healthy-api-governance-look-like">What does healthy API governance look like?</h2>
<p>Healthy API governance should encourage consistency across the organization, mixed with the flexibility to support changing market needs. In the early stages of an enterprise API program, a small group of API architects will often fulfill this role. They will establish standards, practices, and patterns that are encouraged across all lines of business.</p>
<p>Over time, standards are formalized and API design reviews are required before APIs can be deployed onto a production API gateway. While they may not operate under the title of an API Center of Excellence (API C4E), they are often performing the duties of a governance team.</p>
<p>This early stage of an API C4E can either make-or-break your API program. Strict API design reviews with caustic feedback can discourage development teams, resulting in circumvented processes. Bottlenecks can also emerge, resulting in days of waiting for an API design review, only to find out that the team has to go back and make significant changes to their design and code.</p>
<p>An effective governance model seeks to empower teams to be self-governing as much as possible. They drive consistency and seek to cross-communicate the experiences of other teams through shared resources and automation.</p>
<p>API design reviews are conducted in the spirit of listening, understanding, and encouraging improvements rather than strict pass/fail feedback.</p>
<p>Common design patterns are demonstrated through examples and from existing production APIs. Less time is spent trying to re-invent solutions and more time is invested in delivering value consistently.</p>
<h2 id="selecting-an-api-governance-model">Selecting an API governance model</h2>
<p>We have found that there are a set of common API governance models. They vary based on the level of centralization and the degree of control exerted over API design and implementation. These governance models include:</p>
<p><strong>Centralized Governance</strong>: A single central team or authority is responsible for all aspects of API governance, often as part of an API C4E. This central team defines the standards, approve API designs, and enforces compliance. This model provides a high level of consistency and control, but it can also slow down development and limit flexibility for larger organizations.</p>
<p><strong>Federated Governance</strong>: The responsibilities for API governance are distributed among multiple teams or individuals across the organization. Each team has autonomy over their portfolio of APIs. However, they must still adhere to a set of basic standards defined centrally. This model offers a balance between control and flexibility for larger organizations that wish to encourage consistency across the entire organization while still offering automony.</p>
<p><strong>Distributed Governance</strong>: A model where each team has full control over their APIs with no central authority. This model offers maximum flexibility and speed. It is often seen in organizations that have product-centric organization structures, where each team has its own executives, product managers, development teams, and budgets. However, it can lead to inconsistencies and make it difficult to enforce a unified security model and set of quality standards. This is especially the case as product lines try to cross-sell to existing customers but find that their authorization mechanisms vary significantly, resulting in frustrating integrations by customers.</p>
<p><em>Summary:</em> These three models are seen the most often when we consult with organizations on establishing a growing API program. Unless your organization is an early-stage startups or a smaller organization with a handful of APIs, a federated governance model will fit your needs.</p>
<h2 id="customizing-your-api-governance-model">Customizing your API governance model</h2>
<p>While the three governance models outlined above are most common, there are some techniques used to further customize the model to fit your specific organization needs. These include:</p>
<p><strong>Hybrid Governance</strong>: Combines elements of centralized and decentralized governance. For instance, a central team might define broad standards and guidelines, but individual teams have discretion over how to implement these in their specific context. This model attempts to balance consistency and control with flexibility and autonomy. Applying this model is helpful when organizations must support business units created from acquisitions that are still operating somewhat independently. A hybrid model provides time for groups to realign themselves to a centralized set of guidelines while managing their existing APIs.</p>
<p><strong>Automated Governance</strong>: This model leverages automation tools to enforce governance policies. For example, API linters and automated tests are used as part of an automated CI/CD process to check whether APIs comply with design standards. This can increase efficiency and consistency while shifting left your compliance checks to an earlier stage of the design and development process. This model is useful when combined with any of the above models to enhance their effectiveness.</p>
<p><em>Summary:</em> Automate when possible to reduce the burden and wait time for your API design reviews. If you have multiple APIs across the organization that each have their own style guide as a result of independent development or acquisitions, start with a hybrid governance model. You can target a federated governance model as you are able to unify teams into a single set of standards and practices.</p>
<h2 id="scaling-your-api-governance-model">Scaling your API governance model</h2>
<p>Once your API governance model is established, it is time to start thinking about how to scale it across the organization. If your organization are like some that we have partnered with to grow their API program, you may have thousands of developers spread across different lines of business and domain areas. In this case, scaling your API governance model is essential. We recommend implementing a federated API coaching model alongside governance automation.</p>
<p><a href="/scaling-your-api-program-with-federated-coaching/">Federated API coaches</a> support their business units or domain areas, reducing the burden and wait time often associated with a centralized governance model. These coaches are trained and deployed across the organization to distribute the review process. API coaches also benefit from their knowledge of their domain area, providing deeper insight than a centralized group that is less familiar with the domain.</p>
<p>You can learn more about federated API coaching from our recent article, <a href="/scaling-your-api-program-with-federated-coaching/">“Scaling Your API Program with Federated API Coaching”</a>. In this article, we take a deeper dive into the challenges of scaling an API program and how API coaches can help alleviate many of the day-to-day pressures experienced by an API C4E.</p>
<h2 id="getting-started-with-your-api-governance-model">Getting started with your API governance model</h2>
<p>As organizations grow their API landscapes, governance can become a challenging task. Selecting the appropriate API governance model is an important step for your API program. By examining each of the models and selecting the appropriate one, organizations can be prepared to scale their API program effectively. Combining the API governance model with a federated API coach program enables teams to gain the support they need quickly and with the deeper understanding of those in their same area of business.</p>
<hr />
<p><i class="fa fa-lightbulb-o fa-5x" aria-hidden="true" style="float: left; padding-right: 10px; "></i> Did you know that LaunchAny has partnered with organizations of all sizes to establish their API governance model? We can perform an assessment of your API program to identify the best API governance model for you, as well as recommend areas of improvement to effectively scale your API program. <a href="/contact/">Contact us to find out more</a>.</p>James Higginbothamjames@launchany.comHow to select an effective governance model for your API programScaling Your API Program with Federated API Coaching2023-07-03T10:39:00-05:002023-07-03T10:39:00-05:00https://launchany.com/scaling-your-api-program-with-federated-coaching<p>We’ve worked with organizations in a variety of different business verticals, from banking to commercial insurance and healthcare. Universally, one of the biggest challenges for any organization is the difficulty in scaling their API program.</p>
<p>Most API programs have already established their community of standards and practices. Yet, their request queue continues to grow, with no end in sight. Every day seems like a scene from the “I Love Lucy” episode with the conveyor belt of chocolate, speeding up and never slowing down.</p>
<p style="font-size: 14px"><img src="/images/uploads/ilovelucy.gif" /><br />Live view of your API program trying to scale as more requests are queued up.</p>
<p>In this article, we will explore some of the root causes of an overwhelmed API program and how to overcome them successfully through an approachable, scalable process that extends the reach of your API expertise across the organization.</p>
<h2 id="why-is-your-api-center-for-enablement-c4e-overwhelmed">Why is your API Center for Enablement (C4E) overwhelmed?</h2>
<p>Nearly every API program I’ve assessed has a feeling of being overwhelmed. Requests for design reviews are stacked up and <strong>every day yields more meeting requests</strong>. Then comes that high-profile API that will need personalized attention as they design an important, partner or customer-facing API.</p>
<p>The root cause of an overwhelmed API C4E is <strong>limited resources</strong>. There just isn’t enough time in the day to handle every request. It takes time to understand a line of business, the problems they face, and how their API goals align (or don’t align) with the overall API portfolio of the organization.</p>
<p><img src="/images/diagrams/api-coach-direct-c4e.png" alt="The overwhelmed API C4E" /></p>
<p>Perhaps the limitations are due to <strong>budget constraints</strong> that prevent the API C4E from hiring sufficient staff to handle the large amount of requests for API design reviews and facilitated design sessions. This places the burden of the organization upon the shoulders of one or a few specific people familiar with APIs.</p>
<p>Another reason may be a <strong>lack of trained product and technical leaders</strong> due to limited time for the API C4E to conduct proper training sessions. I’ve witnessed circumstances where the API C4E is simply unable to find sufficient time to create and deliver <a href="/api-training">API-related training</a>.</p>
<p>Finally, it could be that <strong>the organization is simply so large</strong> that there will never be enough API C4E staff to handle the many teams across the lines of business. In these circumstances, you will never be able to hire sufficient staff to handle hundreds or even thousands of teams delivering APIs across the enterprise.</p>
<p>The API C4E has limited time available to answer API-related questions from teams across the organization. This becomes a bottleneck for the organization, resulting in slow response times and lost opportunities to help teams when they need it.</p>
<p>Establishing a formalized API coach program helps to equip people all over the organization to better support teams when and where they need API guidance. Let’s take a look at the role of API coaches and how you might consider incorporating them into your API program.</p>
<h2 id="how-api-coaches-help-scale-your-api-program">How API coaches help scale your API program</h2>
<p>While the API C4E wishes to help every team with their API design needs immediately, <strong>limited resources present scaling issues</strong>. Members of a C4E are unable to keep up with the latest initiatives across the organization. In addition, <strong>they often lack the necessary domain understanding</strong>, requiring more time to be effective when offering API design guidance.</p>
<p>An effective API program recognizes that the API C4E cannot be available all the time, instead opting to equip qualified individuals with the resources they need to support teams within their area. These individuals bring their unique technical and product talent, combined with their understanding of the domain area, to teams that need additional guidance throughout the API management lifecycle.</p>
<h2 id="api-coaches-are-an-extension-of-the-api-c4e">API coaches are an extension of the API C4E</h2>
<p>API coaches enable an API program to scale across the organization by <strong>becoming an extension of the API C4E</strong> across all lines of business. They are able to engage with teams within their specific domain of expertise to <strong>provide API design feedback</strong>, <strong>guidance regarding standards and practices</strong>, and <strong>facilitate sessions for high-profile initiatives</strong>.</p>
<p>When necessary, the C4E provides a central place for API coaches to raise issues or gain assistance, but otherwise the API coaches operate independently. The opportunity for collaboration with the C4E enables the API coach to bring “in-the-field” knowledge back that can be incorporated into future revisions of the standards and practices. Likewise, the API C4E is able to help API coaches to apply patterns found in other parts of the organization.</p>
<p><img src="/images/diagrams/api-coach-lob-domain.png" alt="API C4E with an API coach program" /></p>
<p>While most API coaches operate as a “side-of-desk role” in addition to other responsibilities, some API coaches may be dedicated within a specific line of business or business unit. They apply their deep knowledge of the area as part of their coaching efforts, making engagements more effective and contextually relevant.</p>
<h2 id="selecting-an-api-coaching-approach">Selecting an API coaching approach</h2>
<p>API coaching is typically structured in one of three ways:</p>
<p><strong>API C4E Coaches</strong> that is dedicated within the C4E to offer general API design guidance across the organization. In this model, the API C4E hires dedicated staff to support the organization. This model works well for small and mid-size organizations, but doesn’t scale well for larger organizations.</p>
<p><strong>Domain API Coaches</strong> focus within a specific domain area, line of business, or business unit. Domain-level API coaches are more familiar with the day-to-day needs and specifics of their assigned area compared to the API C4E. This model works well for organizations that require very specific domain expertise, or for larger enterprise organizations.</p>
<p><strong>Hybrid coaching</strong> mixes the first two models, allowing for centralized coaching when domain API coaches are unavailable or need additional assistance. This model is often used only for a limited period of time while domain API coaches are being trained.</p>
<p>Identify the model that best fits the needs of your organization. If you are uncertain, start with API coaching from the API C4E. Over time, <a href="/api-training/">train your API leaders</a> and certify them for coaching within their respective domain areas.</p>
<h2 id="getting-started-with-api-coaching">Getting started with API coaching</h2>
<p>Implementing an API coaching program requires time and effort. The API C4E must put focused effort into designing sufficient resources and processes to support API coaches. Start by ensuring your API standards and practices are clear and easily accessible. Doing so will ensure that the coaches feel supported and limit the number of times they have to reach out to the API C4E for assistance.</p>
<p>Once you have the necessary resources in place, such as API standards and practices, and have trained up your API coaches, start simple. Offer weekly office hours for anyone to join if they have a question. Allow your API coaches to shadow and then lead these weekly meetings.</p>
<p>You may also wish to offer a list of certified API coaches on your API C4E website, so that people looking for additional design guidance know who is certified in their domain area. Capture guidance as new questions arrive, to help support your coaches over time.</p>
<p>Organizations embarking on this journey must ensure they have support from their managers and executives so that sufficient resources are available to grow the program once established. Otherwise, the API coaching initiative will languish.</p>
<h2 id="is-an-api-coach-program-a-good-fit-for-your-organization">Is an API coach program a good fit for your organization?</h2>
<p>Does API coaching seem like a good fit for your organization? Be sure to start small, perhaps with one or two API coaches to start. Establish the necessary resources and processes to help them be effective. Communicate their availability on an as-needed basis at first, then seek to promote the program to a broader audience when they are ready. As the program grows, be sure to capture metrics and case studies that demonstrate the positive results of having an API coaching program. This will help to justify the effort put forth and quantify the number of new API coaches required as demand increases.</p>
<hr />
<p><i class="fa fa-lightbulb-o fa-5x" aria-hidden="true" style="float: left; padding-right: 10px; "></i> Did you know that LaunchAny has helped accelerate the creation of a formalized API coaching program? We deliver packaged training, perform assessments of your API program to identify areas of improvement, and can facilitate an initial API coach certification to help bootstrap the process. <a href="/contact/">Contact us to find out more</a>.</p>James Higginbothamjames@launchany.comLeverage an API coaching program to scale your API programIntroducing the ADDR API First Design Process2021-12-10T09:22:00-06:002021-12-10T09:22:00-06:00https://launchany.com/intro-addr<p>I am pleased to announce the release of my latest book, <a href="https://www.informit.com/store/principles-of-web-api-design-delivering-value-with-9780137355709">“Principles of Web API Design: Delivering Value with APIs and Microservices”</a>. This book helps teams and individuals transform their product and business requirements into one or more APIs. The book introduces a repeatable, scalable process for API design called Align-Define-Design-Refine, or ADDR.</p>
<p>Let’s explore the book by looking at the ADDR process and why I think it is an effective way to take an outside-in approach to API design by focusing on outcomes, activity steps, and then designing APIs to satisfy those outcomes.</p>
<h2 id="what-is-api-design-first">What is API design first?</h2>
<p>API design first shifts the focus from code to designing an API with a focus on delivering a great developer experience for your API consumers. It recognizes that both developers and end-users benefit from a thoughtful API design approach.</p>
<p>An API design that looks good to the designer may not solve the problems at hand. If an API is designed by taking a code-first approach, the focus of the design will be on the internal implementation details. Optimizations are made for the delivery team rather than the API consumer. This results in a poor developer experience for your API consumers that wish to integrate your API into their solutions.</p>
<p>For organizations to undergo digital transformation, the first step is shifting the culture to an API design first approach. This requires a fundamental change in the way that enterprise IT and engineering teams approach their API efforts. With an API design first approach, teams take an outside-in approach to API design. They recognize that coding is important but an API design is more important to guide the development process. Otherwise, the API design is emergent, focusing on coding details rather than delivering on the desired outcomes of the end-user.</p>
<h2 id="the-need-for-an-api-design-process">The need for an API design process</h2>
<p>One challenge with API design first is that there hasn’t been a prescribed way to go from business and product requirements to an API design that delivers on the desired outcomes of your developers and end-users. I witnessed teams struggle with how to organize and align their understanding of the requirements into an effective API design. Time was wasted arguing about design elements and processes.</p>
<p>Without a structured approach to your API design process, teams end up in “analysis paralysis” as they try to design their API. They spend more time trying to design and re-design their API, without any clear understanding of what the end user wants to do. The result is design thrash and front-end rework as the API design changes over-and-over again.</p>
<p>That is why I created the ADDR process. It offers a framework for gathering requirements into a simple series of artifacts that guide you through the API design process. It encourages alignment with business and product teams, along with fast feedback that ensures you remain agile as you gain insights into the needs of the developers and end users.</p>
<p>As your organization scales beyond a small number of APIs, it is important to equip teams with a repeatable, scalable API design process. The process must also ensure alignment and cross-functional communication between business, product, and software engineering.</p>
<p>Let’s look briefly at the ADDR design process that is detailed in the book.</p>
<h2 id="the-addr-scalable-api-design-process">The ADDR Scalable API Design Process</h2>
<p>The Align-Define-Design-Refine (ADDR) Process is a lightweight approach that guides organization through an API design process in a repeatable way.</p>
<p>The process is comprised of four phases:</p>
<ul>
<li><strong>Align Phase:</strong> Gain alignment of understanding and scope across business, product, and technology around a set of desired outcomes and the steps required to achieve those outcomes</li>
<li><strong>Define Phase:</strong> Map the activity steps into one or more API profiles that describe the APIs and how they will deliver on the desired outcomes</li>
<li><strong>Design Phase:</strong> Transform the API profiles into using one or more API styles including REST, GraphQL, and gRPC</li>
<li><strong>Refine Phase:</strong> Incorporate fast feedback to improve the API design through the use of documentation, prototyping, and testing efforts</li>
</ul>
<p>The diagram below illustrates the steps that make up the ADDR process:</p>
<p><img src="/images/uploads/addr-process.png" alt="The ADDR API Design First Process" /></p>
<p>There are several benefits to adopting the ADDR process:</p>
<ul>
<li>Aligns Business and Technology with Product Thinking - Successful API design processes support collaboration across business, product, and technical teams</li>
<li>Improves Cross-Functional Communication - ADDR is an iterative, team-oriented process that improves quality and speeds delivery by encouraging early alignment on the scope and goals of the API across business-facing and technical roles</li>
<li>Incorporates Stakeholder Feedback - Good API design relies on both iteration and parallel efforts with frequent feedback</li>
<li>Avoids API Design Anti-Patterns - Anti-patterns are usually signs that we learned important details too late. ADDR ensures API design considerations and feedback are factored in early</li>
<li>Delivers a Repeatable, Teachable Scalable Process - The ADDR process guides groups through a repeatable, teachable, trackable process</li>
</ul>
<p>Let’s look at each phase in more detail to better understand how the ADDR process works.</p>
<h2 id="the-align-phase">The Align Phase</h2>
<p><strong>Goal:</strong> Gain alignment of understanding and scope across business, product, and technology around a set of desired outcomes and the steps required to achieve those outcomes.</p>
<p>The Align Phase is the most critical phase and often the most overlooked. Rather than immediately starting to write code, this phase focuses on ensuring that the team response for API design have sufficient understanding of the responsibilities of the API. This prevents building an API that delivers raw data but fails to deliver outcomes desired by the end user or developer.</p>
<p>The Align Phase consists of two activities:</p>
<ol>
<li><strong>Identify digital capabilities:</strong> Identifies the customer needs and desired outcomes to address the jobs to be done (JTBD), written as job stories</li>
<li><strong>Capture activity steps:</strong> Expands the digital capabilities to include the list of activity steps required to go from a problem or situation to the desired outcomes identified by the job stories. For complex or unknown problem domains, this may include using collaborative techniques such as EventStorming to explore and understand it prior to identifying the activity steps</li>
</ol>
<h2 id="the-define-phase">The Define Phase</h2>
<p><strong>Goal:</strong> Map the activity steps into one or more API profiles that describe the APIs and how they will deliver on the desired outcomes.</p>
<p>The Define Phase acts as a bridge between requirements, identified in the Align Phase, and the API design that will be created. During the define phase, teams will focus on mapping the activity steps into one or more API profiles. An API profile defines the scope of responsibility of the API, the API operations that will be needed, the API resources that are required, API security concerns, and opportunities for business events that will be emitted. The Define Phase is also used to identify existing APIs that can be leveraged, encouraging reuse of APIs in your catalog.</p>
<p>There are two activities that are used in the Define Phase:</p>
<ol>
<li><strong>Identify API boundaries:</strong> Groups the digital capabilities into API boundaries and determine if existing APIs may be leveraged or if new APIs are required</li>
<li><strong>Model each API:</strong> Define the high-level API profile, including resources and operations needed, and the events it will event. The API profile also identifies authorization scopes that may be required based on who is (and is not) allowed to perform the operation.</li>
</ol>
<h2 id="the-design-phase">The Design Phase</h2>
<p><strong>Goal:</strong> Transform the API profiles into using one or more API styles including REST, GraphQL, and gRPC.</p>
<p>The Design Phase is where the technical details are applied. First, select the API style or protocol that best fits the needs of the API consumers: REST, GraphQL, gRPC, or something else. Then, map each API profile into the selected API style. It is encouraged to use a tabular format for this step, prior to documenting your API using the OpenAPI Specification or other documentation format, as this makes it easier to make quick changes based upon feedback in the Refine PHase.</p>
<p>In some cases, you may need to use the API profile to design more than one API style or protocol. For example, you may choose to design all of your APIs using a REST-based approach, but also offer a GraphQL-based API for more advanced query support and response shaping.</p>
<p>There is only one activity for the API design phase, but it will be repeated for each API profile you are ready to design and deliver:</p>
<ol>
<li><strong>High-Level API designs:</strong> Selects one or more API styles that each API profile will offer and document the high-level design elements</li>
</ol>
<h2 id="the-refine-phase">The Refine Phase</h2>
<p><strong>Goal:</strong> Incorporate fast feedback to improve the API design through the use of documentation, prototyping, and testing efforts.</p>
<p>Before embarking on the full code delivery process, it is a good idea to refine your design through fast feedback from your API consumers. Create diagrams, README documentation, or other assets before committing to your API design. API mocking tools are always a great way to help people experience your API before you code it up. Make any design adjustments based upon feedback, then finalize the first version of your API reference documentation and getting started guides.</p>
<p>There are two primary activities in the Refine Phase, although you may need to create a variety of artifacts to help communicate your API design and intended usage to your consumers for feedback:</p>
<ol>
<li><strong>Refine the design:</strong> Incorporates design feedback from API consumers using techniques that encourage improvement in the developer experience</li>
<li><strong>Document the API:</strong> Completes the API documentation, including reference documentation and getting started guides, to accelerate integration</li>
</ol>
<h2 id="a-look-inside-the-book">A look inside the book</h2>
<p>The book is divided into give parts, starting with the principles of web API design, then a step-by-step review of each recommended activity across the four phases, and finally an HTTP primer for those that need a quick review.</p>
<p>As you read the book, you are guided by the ADDR process through a real-world example with sample artifacts produced along the way. Using this example, you will be able to quickly apply the ADDR process for your own API design efforts.</p>
<p>Below is the table of contents:</p>
<ul>
<li>Part I: Introduction to Web API Design
<ul>
<li>Chapter 1: The Principles of API Design</li>
<li>Chapter 2: Collaborative API Design</li>
</ul>
</li>
<li>Part II: Aligning on API Outcomes
<ul>
<li>Chapter 3: Identify Digital Capabilities</li>
<li>Chapter 4: Capture Activities and Steps</li>
<li>Chapter 5: Identifying API Boundaries</li>
<li>Chapter 6: API Modeling</li>
</ul>
</li>
<li>Part IV: Designing APIs
<ul>
<li>Chapter 7: REST-Based API Design</li>
<li>Chapter 8: RPC and Query-Based API Design</li>
<li>Chapter 9: Async APIs for Eventing and Streaming</li>
</ul>
</li>
<li>Part V: Refining the API Design
<ul>
<li>Chapter 10: From APIs to Microservices</li>
<li>Chapter 11: Improving the Developer Experience</li>
<li>Chapter 12: API Testing Strategies</li>
<li>Chapter 13: Document the API Design</li>
<li>Chapter 14: Designing for Change</li>
<li>Chapter 15: Protecting APIs</li>
<li>Chapter 16: Continuing the API Design Journey</li>
</ul>
</li>
<li>Appendix: HTTP Primer</li>
</ul>
<p>Check out the <a href="https://www.informit.com/store/principles-of-web-api-design-delivering-value-with-9780137355709">publisher’s website to preview the book</a> and learn more.</p>James Higginbothamjames@launchany.comImprove efficiency and reduce cost using ADDR. a scalable API first design processCreating an Effective API Program2019-01-17T13:39:00-06:002019-01-17T13:39:00-06:00https://launchany.com/effective-api-programs<p>It can be challenging to establish a healthy API program within your organization. But what happens when your teams start to produce a large number of APIs and microservices? Things can get out of hand quickly, resulting in APIs that go unused or rebuilt multiple times.</p>
<p>Effective API programs require three key ingredients:</p>
<ol>
<li><strong>API portfolio ownership</strong> that meets the needs of both internal and external stakeholders,</li>
<li><strong>Lightweight governance</strong> that combines coaching with consistency, and</li>
<li><strong>Ease of API adoption</strong> for increased speed and efficiency.</li>
</ol>
<p>Let’s examine each one to better understand what your organization may be missing or need to improve upon for your API program.</p>
<h2 id="1-api-portfolio-ownership">1. API Portfolio Ownership</h2>
<p>The first and most significant step any company can take to tame their APIs and microservices is to be organized. I have seen companies produce large quantities of APIs and microservices, yet they have no clear organization of their overall portfolio.</p>
<p>An organization’s lack of portfolio management results in a spiraling effect, where new APIs are built without knowledge of others that already exist. Plus, it isn’t always clear who should be responsible for a new API - your team or someone else. It doesn’t take long for this spiral effect to render an API program messy and ultimately labeled by executives as a failure.</p>
<p>As your API program expands, seek to tame your portfolio of API and microservices through the following steps:</p>
<p><strong>Manage your API portfolio:</strong> Not all APIs are related (e.g., customer accounts, orders, and inventory for an eCommerce platform). Separate your APIs and microservices into domain areas and assign product ownership of each area. Select a product manager to own the entire API portfolio, or place it under the stewardship of an API governance team.</p>
<p><strong>Craft a clear process to add new APIs and microservices:</strong> By defining a clear process for adding new APIs into the portfolio, API consumers will have an easier time finding the APIs they need. Properly executed API portfolio management ensures teams across the organization can contribute to the overall portfolio. It will also make the job of consuming teams easier when looking for an API to address the needs of their apps.</p>
<p><strong>Oversee URL paths:</strong> The URL paths under your API domain name (e.g., api.mycompany.com/accounts) are like real estate for developers. Manage your URL paths through the use of prefixes or other naming conventions. This will scope resources to domain areas to prevent scattered API endpoints, duplicate or confusing resource names, and conflicting paths.</p>
<h2 id="2-introduce-lightweight-api-governance">2. Introduce Lightweight API Governance</h2>
<p>A healthy API governance initiative should encourage consistency across the organization, mixed with the flexibility to support changing market needs. For smaller organizations, or in the early stages of an enterprise API program, a single API architect often fulfills this role. While they may not operate under the title of “API governance” or an “API Center of Excellence”, they are often performing the duties of a governance team:</p>
<ul>
<li>Coaching teams on API design techniques</li>
<li>Delivering educational material, training, and other resources to communicate shared knowledge</li>
<li>Empowering solution teams to discover and consume existing APIs</li>
<li>Defining clear API standards, protocols, and design patterns supported through an API style guide</li>
<li>Creating policies for onboarding, rate limiting, and access control</li>
</ul>
<p>For some organizations, API governance may start with an individual but will eventually grow into a small team. For larger organizations, it may evolve into a federated governance model. Whatever this needs to look like for your organization, seek to drive consistency across the organization as the number of APIs and microservices increase.</p>
<h2 id="3-make-api-adoption-easy">3. Make API Adoption Easy</h2>
<p>Developers are an essential ingredient of any API program. However, many organizations focus on the strategy and processes to create APIs but fail to address the need to support easy API adoption.</p>
<p>Common tasks to drive increased API adoption include:</p>
<p><strong>Maintain great documentation:</strong> Your documentation is the first encounter most developers will have with your APIs. <a href="https://launchany.com/api-documentation/">Provide great documentation</a> to drive awareness and understanding. This should include a focus on: what your API offers, how to use it, and what to do when they are ready to start integrating.</p>
<p><strong>Help developers get started quickly:</strong> Developers who are new to your API do not have an easy journey. They must learn what capabilities are offered, determine if they solve the problem at hand, and how to get started using your API for the first time. Make it easy for developers to get started through this journey through quick start guides and case studies.</p>
<p><strong>Define a clear onboarding process:</strong> Think beyond reference documentation by offering a complete developer portal that guides integrators through the onboarding process. This includes an introduction to the API’s authorization approach, the capabilities addressed, how to onboard in a sandbox environment, and how to gain access to production.</p>
<p>Focusing on API adoption helps to build awareness of available APIs. It also prevents wasting time and resources to construct APIs that are rarely (or never) used by developers.</p>
<h2 id="wrap-up">Wrap-up</h2>
<p>All API programs start with good intentions. Over time, however, they can get out of control if left unchecked. For smaller organizations, having a very lightweight set of coordinating processes and a focus on encouraging API adoption will go a long way. For enterprise IT, it is critical to install a governance team that can help organize your API program, drive consistency, and help grow API integrations.</p>
<p>While it may be challenging at times to launch and sustain an API program, it is ultimately rewarding as you see your organization transform from a set of adhoc APIs and microservices to a healthy program with a clear roadmap and onboarding process.</p>James Higginbothamjames@launchany.comIt can be challenging to establish a healthy API program within your organization. But what happens when your teams start to produce a large number of APIs and microservices? Things can get out of hand quickly, resulting in APIs that go unused or rebuilt multiple times.What Skills Do Your APIs Offer?2016-04-01T02:19:09-05:002016-04-01T02:19:09-05:00https://launchany.com/what-skills-do-your-apis-offer<p>Much has been written about API design techniques – from choosing the right HTTP verb to guidance on response code usage and hypermedia dos and don’ts. We get caught up in the technical details of what our API should look like under the covers, while ignoring the humans that the APIs were designed to help.</p>
<p>We need to remember that APIs exist to help complete a job-to-be-done. Either the job requires the use of the API to start and finish the work, it requires the API for some portion of the work, or the job is to bridge systems and organizations through machine-to-machine communication.</p>
<p>So, how do your API endpoints participate in these jobs? Even better, how do you explain the capabilities of your API endpoints to those less familiar with the technical details of HTTP, GET, and POST? It is time to start communicating about our APIs in a new way. One that supports the human side of APIs. It is time to start talking about our API endpoints as skills.</p>
<h2>What skills do your APIs offer?</h2>
<p>If I were to <a href="/building-your-api-documentation-strategy-for-success/">look at your API documentation</a> – from your reference documentation in Swagger (now <a href="https://openapis.org/">OpenAPI</a>) to your getting started guides – what would I see? Would I see a bunch of content centered around your POSTs, GETs, PUTs, and DELETEs? Or, would I see the skills your API offers to get stuff done?</p>
<p>The worst offenders I have seen are API reference docs that like this:</p>
<p style="padding-left: 30px;">GET /organizations<br />
Description: Get all organizations</p>
<p>No kidding? The GET /organizations endpoint gets a list of all organizations?! Why do we allow ourselves to document our APIs this way? Instead of “Get all organizations”, <strong>we need to look for a better ways to communicate and share our API’s skills with our product team, our company, and our developer ecosystem</strong>.</p>
<h2>Meeting people where they are</h2>
<p>What skills do your APIs offer? Not the GET vs. POST. Not even hypermedia, though I find that aspect interesting for some API use cases. What does it offer to everyone involved?</p>
<p>For us to answer that, we must meet people where they are. What is interesting is that this isn’t the first time this theme has emerged in my life. For about five years, <a href="http://www.volunteercentered.com/">I wrote and coached</a> individuals on volunteer management. While the topic was related to churches, many of the principles translated to the non-profit sector in general.</p>
<p>I was always asked about how to recruit volunteers, keep them engaged, and ensure that they had a place to land once their season of involvement with the organization was done. My advice generally came down to the following: you need to meet them where they are at, examine the unique skills they bring, and find ways to help them make a difference. Everyone is designed differently. You, as the leader, are required to adapt to their gifts and passions. Not the other way around. Otherwise, volunteers will leave and never come back.</p>
<p><strong>For our APIs to be successful, we have to speak in terms that everyone on the team will understand.</strong> Help them realize their passions and what they want to do. You must adapt to the audience, not the other way around. And your documentation needs to reflect that as well.</p>
<h2>Finding new ways to communicate our API’s skills</h2>
<p>At this stage of my career, I’m an API consultant. I love helping teams understand how to align their business, product, and technology choices. My consulting focus is to help teams to think in APIs. I spend a considerable portion of the time teaching teams how to model and design APIs. I see myself as a product architect, helping teams to find what they do best (their capabilities), and find ways to build an API strategy around those capabilities.</p>
<p>Keith and I captured many of these steps in our book, <a href="http://theapidesignbook.com">“A Practical Approach to API Design”</a>. In the book and during our <a href="/api-training/">hands-on workshops</a>, we teach teams how to break down the jobs-to-be-done into steps. We then map those steps into API endpoints. The result is the beginnings of your API design, documentation, and vocabulary for how your API skills will be used – all centered around the skills of your API.</p>
<p>What we seem to lack is an easy way to map these endpoints and skills into the documentation, typically Swagger. <a href="http://tools.ietf.org/html/draft-amundsen-richardson-foster-alps-01">ALPs</a> may be a solution to this approach as it separates the semantics from the API design. I hope to explore more about this soon.</p>
<p>For now, I am recommending that teams adjust their way of communicating by focusing on API skills first. Begin to orient your discussions around them, so that everyone on the team can participate and understand the conversation at hand. Allow your project managers to understand the impact of a new endpoint by discussing the new skill or capability that it brings to the business. Next, integrate the skills into your documentation to provide better clarity and spark conversations outside of HTTP design details.</p>
<p>Kin Lane has been taking this approach with his <a href="http://kinlane.github.io/university-api-workshop/apis/">university API workshop</a>. He mapped out some Zapier triggers based on the skills or jobs that they perform:</p>
<p><img class="alignnone wp-image-1022" src="/images/uploads/Screenshot-from-2016-03-31-19-15-07.png" alt="Screenshot from 2016-03-31 19-15-07" width="451" height="333" srcset="/images/uploads/Screenshot-from-2016-03-31-19-15-07.png 598w, /wp-content/uploads/2016/03/Screenshot-from-2016-03-31-19-15-07-300x222.png 300w" sizes="(max-width: 451px) 100vw, 451px" /></p>
<p>Jeff Barr recently posted this tweet of how the AWS API is being used from Alexa to enable VoiceOps:</p>
<blockquote class="twitter-tweet" data-lang="en">
<p dir="ltr" lang="en">VoiceOps is here – “Alexa what’s the instance count?” <a href="https://t.co/0ZRnyQijyg">https://t.co/0ZRnyQijyg</a> <a href="https://t.co/AcJUcKWp1v">pic.twitter.com/AcJUcKWp1v</a></p>
<p>— Jeff Barr (@jeffbarr) <a href="https://twitter.com/jeffbarr/status/712002188004827136">March 21, 2016</a></p></blockquote>
<p><script src="//platform.twitter.com/widgets.js" async="" charset="utf-8"></script></p>
<p>The interesting thing here is the mapping between the job-to-be-done, the AWS API, and Alexa’s Skills Kit (ASK) that enables it all to work together. I hope to write more about this soon.</p>
<h2>Educating everyone on your API’s skills</h2>
<p>Call them skills. Call them activities. Call them capabilities. But let’s stop discussing our APIs in terms of endpoints made up of URLs and verbs. Instead, let’s start talking in terms of API skills and mention those URLs and verbs only when we need to be specific about the technical details. When we do this, we can start to educate everyone on the team about how APIs work, why improvements are necessary, and the reason why the product and business should care. Your product team and customers will appreciate it.</p>
<p>Thanks to <a href="http://apievangelist.com/">Kin Lane</a> and <a href="http://www.lorindabrandon.com/">Lorinda Brandon</a> for the additional inspiration on this article.</p>
<p>Photo credit: <a href="http://deaderv23.deviantart.com/art/Skills-Graffiti-doodle-575365572">Skills – Graffiti doodle by DeaDerV23</a></p>James Higginbothamjames@launchany.comMuch has been written about API design techniques – from choosing the right HTTP verb to guidance on response code usage and hypermedia dos and don’ts. We get caught up in the technical details of what our API should look like under the covers, while ignoring the humans that the APIs were designed to help. We need to remember that APIs exist to help complete a job-to-be-done. Either the job requires the use of the API to start and finish the work, it requires the API for some portion of the work, or the job is to bridge systems and organizations through machine-to-machine communication. So, how do your API endpoints participate in these jobs? Even better, how do you explain the capabilities of your API endpoints to those less familiar with the technical details of HTTP, GET, and POST? It is time to start communicating about our APIs in a new way. One that supports the human side of APIs. It is time to start talking about our API endpoints as skills. What skills do your APIs offer? If I were to look at your API documentation – from your reference documentation in Swagger (now OpenAPI) to your getting started guides – what would I see? Would I see a bunch of content centered around your POSTs, GETs, PUTs, and DELETEs? Or, would I see the skills your API offers to get stuff done? The worst offenders I have seen are API reference docs that like this: GET /organizations Description: Get all organizations No kidding? The GET /organizations endpoint gets a list of all organizations?! Why do we allow ourselves to document our APIs this way? Instead of “Get all organizations”, we need to look for a better ways to communicate and share our API’s skills with our product team, our company, and our developer ecosystem. Meeting people where they are What skills do your APIs offer? Not the GET vs. POST. Not even hypermedia, though I find that aspect interesting for some API use cases. What does it offer to everyone involved? For us to answer that, we must meet people where they are. What is interesting is that this isn’t the first time this theme has emerged in my life. For about five years, I wrote and coached individuals on volunteer management. While the topic was related to churches, many of the principles translated to the non-profit sector in general. I was always asked about how to recruit volunteers, keep them engaged, and ensure that they had a place to land once their season of involvement with the organization was done. My advice generally came down to the following: you need to meet them where they are at, examine the unique skills they bring, and find ways to help them make a difference. Everyone is designed differently. You, as the leader, are required to adapt to their gifts and passions. Not the other way around. Otherwise, volunteers will leave and never come back. For our APIs to be successful, we have to speak in terms that everyone on the team will understand. Help them realize their passions and what they want to do. You must adapt to the audience, not the other way around. And your documentation needs to reflect that as well. Finding new ways to communicate our API’s skills At this stage of my career, I’m an API consultant. I love helping teams understand how to align their business, product, and technology choices. My consulting focus is to help teams to think in APIs. I spend a considerable portion of the time teaching teams how to model and design APIs. I see myself as a product architect, helping teams to find what they do best (their capabilities), and find ways to build an API strategy around those capabilities. Keith and I captured many of these steps in our book, “A Practical Approach to API Design”. In the book and during our hands-on workshops, we teach teams how to break down the jobs-to-be-done into steps. We then map those steps into API endpoints. The result is the beginnings of your API design, documentation, and vocabulary for how your API skills will be used – all centered around the skills of your API. What we seem to lack is an easy way to map these endpoints and skills into the documentation, typically Swagger. ALPs may be a solution to this approach as it separates the semantics from the API design. I hope to explore more about this soon. For now, I am recommending that teams adjust their way of communicating by focusing on API skills first. Begin to orient your discussions around them, so that everyone on the team can participate and understand the conversation at hand. Allow your project managers to understand the impact of a new endpoint by discussing the new skill or capability that it brings to the business. Next, integrate the skills into your documentation to provide better clarity and spark conversations outside of HTTP design details. Kin Lane has been taking this approach with his university API workshop. He mapped out some Zapier triggers based on the skills or jobs that they perform: Jeff Barr recently posted this tweet of how the AWS API is being used from Alexa to enable VoiceOps: VoiceOps is here – “Alexa what’s the instance count?” https://t.co/0ZRnyQijyg pic.twitter.com/AcJUcKWp1v — Jeff Barr (@jeffbarr) March 21, 2016 The interesting thing here is the mapping between the job-to-be-done, the AWS API, and Alexa’s Skills Kit (ASK) that enables it all to work together. I hope to write more about this soon. Educating everyone on your API’s skills Call them skills. Call them activities. Call them capabilities. But let’s stop discussing our APIs in terms of endpoints made up of URLs and verbs. Instead, let’s start talking in terms of API skills and mention those URLs and verbs only when we need to be specific about the technical details. When we do this, we can start to educate everyone on the team about how APIs work, why improvements are necessary, and the reason why the product and business should care. Your product team and customers will appreciate it. Thanks to Kin Lane and Lorinda Brandon for the additional inspiration on this article. Photo credit: Skills – Graffiti doodle by DeaDerV23