ASC 2019 - API Specifications Conference

You have an awesome service, and you've crafted a beautiful REST API. You've got great API docs. What more could users possibly want?

This seems to be a common view of service teams, in my company and maybe also in yours.
I say: No one wants to call your API.

By that I mean, users may want the _result_ of your API, but they _do not_ want to deal with the details.

- How to craft the URL if it contains path parameters? That can be tricky!
- What credentials to use and how to pass them?
- Which headers to pass in the request? What headers to inspect in the response?
- How to construct a JSON request body from language objects?
- How to get language objects from a JSON response body?

In this talk, I'll discuss how to help your users avoid these and many other roadblocks to using your API by providing awesome client libraries, or SDKs, for your service.

In this talk I will present how the adoption of API description documents leads the design-first approach in software development at Adidas. I will go through the history of this change in the organization and how it helped to build processes and standards which create great Developer Experience, API visibility and Fast Delivery of applications. This will aim to demonstrate how API specification documents help adidas to go from black-box static systems into the world of hypermedia-driven distributed network of APIs.

API specifications are an essential tool for describing API behavior and relationships. It explains how an API functions and what results to expect when using the API. But sometimes - like a user story without a wireframe - it can be challenging to fully understand those interactions without seeing them in action. Short of coding the entire API, service virtualization can provide an interactive example of an API's features, functionality, and responses without all of the development overhead. In this talk, we will evaluate ways in which virtualization can be a useful tool in driving adoption of new APIs, provide opportunities for collaboration amongst teams, and foster a deeper understanding of the specification than can be gained from documentation alone.

Microservices and Event-Driven Architecture are being adopted in many companies nowadays. As the number of services increases, it becomes necessary to document and standardize the communication between services.

At Relayr GmbH we have dozens of services written in Node.js, Scala and other languages also. These services communicate with each other over different channels including Kafka and MQTT on many topics and messages types. We had JSON schemas defined within services to validate and test the payload. It was hard for everyone to keep track of all the types of messages, their payload and to know which types of messages each service is publishing/consuming.

We started using AsyncAPI to document every message including their payload, required and optional fields. AsyncAPI became the source of truth of all the Async communication between services. We came up with asyncapi-validator to validate every message at run time using AsyncAPI schema definition.

This talk will be about how we used AsyncAPI for better documentation and as the source of truth. We'll also see, how we used the asyncapi-validator to validate messages using AsyncAPI schema definition.