API Strategy & Practice Conference 2018

The Open API Spec and other API description formats have made a big impact on API designers and consumers. While they've improved how machines talk to each other, they have missed some important human opportunities in APIs. Machines need to think in endpoints, while the human who sees the results of an API call thinks in use cases.

Running over 1,000 APIs in production for millions of users makes the human side of API clear. They want to pull new contracts from their CRM or add new orders to a shopping cart. In some APIs it may take multiple endpoints to fulfill a use case. And there are almost always endpoints that meet a machine need and don't support users directly.

In this entertaining talk, API veteran Adam DuVander will share how far we've come with API descriptions, examples of how they're missing human needs, and some ideas to bring use cases into our API description workflows.

To paraphrase a James Bond movie, "Swagger is not enough".

You've done the work to set up OpenAPI specification REST calls for your APIs (Inaccurately known as Swagger). You have reference information. But you discover that few users are actually trying REST calls on your system. You're wondering: "What else do I need?"

This presentation will describe the Minimal Viable Documentation (MVD) for RESTful APIs, also known as "What do I need for my developer portal?"

Based loosely on Kristof Van Tomme's presentations on Developer Experience, Mike will describe the MVD for a developer portal, what will help your developers try out your APIs.

Mike will discuss characteristics of:

* `Landing Pages` that describe the API
* `Tutorials` that help the user get started
* `Details`, or reference information satisfied by the OpenAPI specification
* `Work in Progress` such as blogs and release notes that show active development

My draft slides are available at https://slides.com/mike-1/minimum-viable-documentation/#/

After spending so much time on the design, development, and testing of your API, you can't just stop there. API development isn't complete until your endpoints are well-documented and discoverable to your end user.

The most beautiful API is only as good as it's documentation, and good documentation drives adoption. And on the flip-side, if more developers document their APIs clearly and consistently, the time saved for the end user increases exponentially.

Whether you're communicating with the broader community or a tight-knit team, Joyce will share a framework for covering all the bases of API documentation.

Don't fret... this isn't an anti-REST talk! Rather, it's challenging the mindset that the consumers of our APIs need to be strong programmers... or programmers at all.

Zapier is one of the best API tools out there, but the only place on the homepage that acronym shows up is buried in their name. Clearbit is ostensibly an API company, however you now have to scroll pretty far past Salesforce and Intercom integrations to get to their section of SDKs. Slack is the hottest API platform out there, but good luck finding anything that starts with "https://" in their docs.

An APIs simply exist as a way to extend what you can do on a platform. Maybe that means programming an API call. However, increasingly, people are using APIs in new, non-programming ways. The best APIs don't care how you use them... they just care that you're using them.

The Watson Cloud team at IBM have built a system to generate SDKs and API Reference documentation from OpenAPI descriptions of the IBM Watson Cloud services. They developed a methodology that includes standards for API design and description, based on OpenAPI but with extensions to capture special API or SDK features, along with a validator that ensures compliance to these standards. They built tools using the Swagger Codegen framework that generate product-quality SDKs that incorporate best practices for API design, code structure, documentation, and extensibility in each target language, and API reference documentation focused around these SDKs. Their methodology and tools enable them to achieve this result for less internal effort than would be possible with existing tools. This talk will describe their system in hopes that it will help others generate usable SDKs and documentation.

So I’m provoking you with my title. The API definition wars are over. We’re all in OAS seventh heaven. We’re complacent.

But why were we establishing specs in the first place? We want to make our customers happy by NOT FREAKING BREAKING THEM right?

But we still hear that we are? So what are we missing?

I’ll talk about a basket of ways you can break your customers whilst still adhering to your API spec perfectly.

Attendees will leave very worried that they may have broken their customers and just maybe determined not to do it again.

A key to improving APIs as they are developed and following launch is listening to developers, representing engineers and communities, prioritizing new features and capabilities. It also helps to consider how services and content can be accessed more creatively, anticipating how developers may appreciate the different ways their code and approach may need to adapt to working with APIs. Having designed APIs and built partnerships, apps and new services around others, Chuck has been deeply involved with both sides of integrations.

Through exploration of music theory, and examination of inspirational interfaces and mechanical occurrences around us, this presentation takes a unique look at new ways platform content, services and data can be offered to enable developers to build better.

Thinking about a complete API strategy for your company could quickly become overwhelming. But you can divide and conquer. As starters, have you thought about your Webhook strategy? Wouldn't be easier to start by offering webhooks to your customers and after getting some usage data and do some research start planning your APIs?
Simply pinging your users when something happens seems like a no-brainer, right?
Thanks to webhooks you can quickly connect with other Saas applications and services, and it will even get you integrated with connectors like Zapier. But, what are the things you have to keep in mind when building a webhook strategy?
In this talk, we will go through recommendations to deliver the best Webhook experience inspired by services that are doing it right, both from a technical perspective and from a DX point of view how webhooks should be part of your overall API strategy.