API Specifications Conference 2021

"The API-first design approach treats APIs as first-class citizens. The entire system or project is built around the idea that components connect via APIs. The first step is, therefore, to design the APIs and their connections.

However, there is a gap between the beautiful world of API specifications and the reality of agile development. This gap means that published API specifications are often incomplete, missing examples or simply outdated. The API specification meant to help developers can be a thorn in one’s side because keeping the specification in sync with its implementation is a manual process, tedious and prone to be forgotten during the rush to deliver.

We show how this gap can be bridged effectively using the API specification as the only source of truth driving the API implementation with proven tools enabling automation.

After this session, attendees will have all the tools they need to keep their API specifications from falling out of date ever again.

How can we help API platform teams ensure that their organizations make and use secure, reliable, and easy-to-use APIs?

Organizations make and use lots of APIs -- often they don’t even know the full extent of the APIs that they make and use. This creates security and reliability risks, duplicated efforts, and divergent patterns that make APIs harder to use and products harder to build.

There’s no silver bullet solution -- there’s no one API pattern or methodology that fits all organizations. Usually there’s not even one that works for all the teams and APIs of a single organization. APIs grow organically and independently and variety is an inescapable reality.

Making APIs better is hard work, but we believe that it starts with knowledge: knowledge of the APIs our teams are making, knowledge of the APIs our teams want to make, knowledge of the APIs our teams are using, knowledge of the APIs our teams want to use, and even knowledge of the APIs that our teams can’t or shouldn’t use because they are deprecated, unreliable, exposing us to security threats, or creating business risks for our organization.

In this session, we want to discuss the requirements for a platform for collecting this knowledge and doing the work of making APIs better. What are its key features? How might we use them?

"In any digital or platform transformation, APIs play a pivotal role. Setting up the right tools to build a successful program can be confusing, costly and time-consuming. Jason will share what he’s learned from Stoplight’s customers, as well as his experience leading these types of API programs. Creating practical methods of governing APIs to produce a consistent developer experience is often where programs fail out of the gate. We’ll explore how design-first patterns allow for “shift left” approaches further than most would assume.
-Style guides
-Linting against style guides
-Docs as part of API feedback
-Tactile feedback with API mocks
-Unify vocabulary/grammar

APIs enable applications to be integrated seamlessly. However, creating APIs, managing them when their version changes, publishing APIs to a developer portal and a number of such API Management related tasks are not seamless. Each of these tasks will have to be planned and executed by skilled people. Testing APIs also need utmost focus and effort.

In this world of automation, there is a possibility to automate almost everything and that includes automating API management as well. In this session we will present how using custom resources and Operators, API Management can be automated and integrated into the development process. Service developers can create custom resources that represent their APIs/services. Operators can monitor and act on those resources to publish APIs to an API Management system/catalog or a to a developer portal. We will explore ideas and prototypes on how APIs can be declaratively deployed and managed. With more interest from the Open Source community, this way of managing APIs can become a standard that can be adopted across the industry.

The main business value of APIs is to allow teams to collaborate by publishing and consuming APIs. If APIs are designed and documented as products, then they allow teams to collaborate more effectively because no meetings and no specific coordination are required. In order for this to work, APIs must be treated as more than just technical interfaces. Their value has to be clearly described and documented, allowing producing teams to be clear about the value that they provide, and allowing consuming teams to understand the value that is made available to them. We have developed and implemented a small set of OpenAPI extensions that focus on describing the value of an API. By representing an API's value directly in OpenAPI, tooling can be be built around these extensions, and API managers freely and openly exchange information about API value across different tools.

It's not uncommon to see JSON Schema schemas that are thousands of lines long, sometimes even tens of thousands of lines long. We would never write our code like that and we don't need to write schemas like that either. In this talk, we will cover the keywords, concepts, and patterns for maintaining large schemas or large collections of schemas. We'll tackle problems like how to breakdown and organize schemas, how to bundle schemas, how to make large schemas efficient, how to get better error messages from large schemas, and more.