Nashville, TN
September 24 - 26, 2018
Click Here For Information & Registration

Sign up or log in to bookmark your favorites and sync them to your phone or calendar.

Describing and Understanding APIs [clear filter]
Wednesday, September 26


What API Descriptions Are Missing - Adam DuVander, EveryDeveloper
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.

avatar for Adam DuVander

Adam DuVander

Principal Developer Strategist, EveryDeveloper
Adam DuVander is a developer communicator and cheerleader. He helps companies reach and engage with developers through authentic content. Previously he worked for some of the best API and developer companies, including Zapier and SendGrid. Many still find his writing at ProgrammableWeb... Read More →

Wednesday September 26, 2018 11:10am - 11:30am
Davidson Ballroom B 1/2
  • Skill Level Any


Minimum Viable Documentation for RESTful APIs - Mike Jang, ForgeRock
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/#/

avatar for Mike Jang

Mike Jang

Senior Staff Technical Writer, ForgeRock
As a senior technical writer for ForgeRock, Mike Jang spends much of his time documenting how deployers can modify JavaScript to customize web applications. He still has to help maintain over 200 curl commands in product documentation. He has also written a couple dozen technical... Read More →

Wednesday September 26, 2018 11:40am - 12:00pm
Davidson Ballroom B 1/2


If an API Falls in a Forest, and No One Is Around to Use it, Is it Still an API? - Joyce Lin, Postman
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.

avatar for Joyce Lin

Joyce Lin

Developer Advocate, Postman
Joyce Lin is a Developer Advocate at Postman, an API Development Environment (ADE) used by more than 5 million developers to access 130 million APIs every month. Based in San Francisco, she likes coding, cats, and second lunches. In her free time, she enjoys laughing at her own j... Read More →

Wednesday September 26, 2018 12:10pm - 12:30pm
Davidson Ballroom B 1/2


The Young and the RESTless - Gregory Koberger, ReadMe
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.


Gregory Koberger

CEO, ReadMe
Gregory Koberger is the founder of ReadMe, an API company focused on usability and design. He weaves together his background as a programmer and designer to make sure APIs are friendly and simple. He's spoken at API Strat in the past, along with conferences like API Mixtape and Write... Read More →

Wednesday September 26, 2018 2:00pm - 2:20pm
Davidson Ballroom B 1/2


Generating Product-Quality SDKs and API Reference Documentation - Michael Kistler, IBM
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.

avatar for Mike Kistler

Mike Kistler

Senior Technical Staff Member, IBM Corp
Mike Kistler is a Senior Technical Staff Member in the IBM Cloud Division in Austin, TX. He joined IBM in 1982 and has held technical and management positions in various product groups, IBM Research, and now in the IBM Cloud Division. He received his BA in Computer Science from Susquehanna... Read More →

Wednesday September 26, 2018 2:30pm - 2:50pm
Davidson Ballroom B 1/2


Your API Spec Isn’t Worth the Paper It’s Written On - Gareth Jones, Microsoft
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.

avatar for Gareth Jones

Gareth Jones

API Architect, Microsoft Corp.
Seasoned software development leader and keynote speaker with a strong architectural bias. Passionate about the developer experience. Created the highly lauded OneNote API. Currently working as an API Architect for Microsoft Education, building and driving a coherent API surface... Read More →

Wednesday September 26, 2018 3:10pm - 3:30pm
Davidson Ballroom B 1/2


Approaching APIs More Creatively Through Music and Other Inspirational Elements Around Us - Chuck Freedman, Red Seat Media
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.

avatar for Chuck Freedman

Chuck Freedman

Developer Relations Lead, Bose
Chuck Freedman is dedicated to driving platform success and adoption across all industries, delivering and enabling product, partner and platform integrations most recently with voice, entertainment content, AI, machine/deep learning and cloud. An enthusiast and inspirational force... Read More →

Wednesday September 26, 2018 3:40pm - 4:00pm
Davidson Ballroom B 1/2


Webhooks Done Right - Nicolas Grenié, Typeform
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.

avatar for Nicolas Grenié

Nicolas Grenié

Developer Advocate, Typeform
Nicolas is a Developer Advocate at Typeform, living between Barcelona and San Francisco. Nicolas built his first website in 2000 using Microsoft Word, and since then did not stop learning about programming. He likes to build projects involving APIs and connecting people together... Read More →

Wednesday September 26, 2018 4:10pm - 4:30pm
Davidson Ballroom B 1/2