APIDAYS PARIS 2018: API the Docs Track
A track that focuses on the latest best practices, strategies and new trends relevant to API documentation and internal developer portals
December 11

The Design of Everyday APIs

Arnaud Lauret

The API handyman, Author of The Design of Everyday APIs, Senior API architect at Natixis

In his talk Arnaud draws parallels between the design of everyday objects and APIs. He focuses on the purpose, usability and constraints of the APIs.

Purpose First and foremost: to be an interface for developers - users shouldn’t be concerned about an API’s workings instead of what they can achieve with it Even great documentation cannot save a badly designed API

Usability Design objects to be straightforward and predictable for the user's satisfaction.

Straightforward design requires:

  • Representations - must understand naming at first sight, carefully chosen data that is really useful for users,
  • Interactions - request minimal and straightforward input, clear error feedback, and success feedback,
  • Flows - improve on input and feedback to prevent errors.

Predictable design means:

  • Consistent - self-consistent, consistent within an organization, consistent to common practices and standards
  • Adaptable - pagination , sort, filter, content negotiation, internationalization, data selection
  • Discoverable - metadata, hypermedia, protocol

Constrained

By user context: latency/granularity, frequency/webhooks, streaming, volume/batch, bulk

By provider: scalability/rate limiting, performance/asynchronous, not 24/7/ no go

With enough time and money these can be solved in an ideal world - not where we live

Keywords to take away: empathy and context

Arnaud's slides



Arnaud's presentation

Learning the OAuth dance (without stepping on anyone’s toes)

Anabella Spinelli

Software Engineer at Typeform

Anabella describes "the OAuth dance" by explaining her first encounter with it and what she and her team at Typeform learned from this experience.

2 main use cases

Authentication - login

Feature integration - the app will request data on a recurrent basis to provide a new, enhanced feature. This application needs to be registered in the provider’s platform to know who is asking for information: need a redirect URI

4 steps in the OAuth dance

Authorize

The app identifies itself through the user’s browser (public channel) requesting for specific information to be sent to a specific place

Consent

If everything’s OK with the above request Typeform will generate a consent screen. Interaction from Typeform to the user through the user’s browser. It contains: basic info, requested scopes, accept or cancel call to actions (pain point: error screen was blank - user cannot know what the problem is)

Redirection

From Typeform to My app’s redirect URI endpoint through the user’s browser a temporary code is sent to be used in the final step.

Token

Token request from app straight to Typeform without the browser. It contains client secret, temporary code, redirect URI.

Token granted from Typeform straight to the app without the browser.

How is the token used?

When the app wants something from Typeform, the unique token identifies:

  • which user does the data belong to

  • which app is requesting it and

  • whether it has the permissions to request that data.

Learnings

  • Test your guides with junior devs to find your blind spots - documentation should be aimed at this group

  • Have descriptive error states

  • Give people a map they can follow

  • Provide dev tools

Anabella's slides



Anabella's presentation

Disagree with “I Agree”. Enforcing better GDPR compliance through the language of API documentation

Karen Sawrey

Technical Writer/Editor at Cossack Labs

Karen summarizes the points to remember when you want to make your site GDPR compliant.

GDPR: enforces a security standard on documentation

APIdocs: something that can make GDPR more doable, more understandable for your users

The vicious circle of ignored documentation: Docs are hard to read -› People don’t read docs -› Why bother? Nobody reads docs anyway

GDPR on the surface

Use human language that users actually want to read

Intend to be concise and informative

Describe clearly what you are taking from people, what kind of data interaction is taking place

The secret life of docs beyond the surface:

  • Database storing emails and passwords

  • If you store your users’ data you are responsible for them - even if users are being “irresponsible” and use the same password for various sites - it is you responsibility in the first place to secure their passwords on your site

  • Use simple words in explanations

  • Keep your sandbox user data clean

  • Use warnings about security measures

  • Inform users about GDPR

Takeaway

There is no silver bullet for GDPR - you have to think for yourself - what data you need for what - minimize stored data

Karen's slides



Karen's presentation

An API Is Not Enough: Crafting a Developer Experience

Adam Kalsey

Webex Developer Relations at Cisco

Adam gives us the six principles for cracking a great developer experience both on internal and external developer portals.

Be user-centric: you can only provide a great developer experience (DX) if you have a deep understanding of the goals of your users.

Good/Great DX is your competitive advantage- so many substitutes for a developer product (other product, open source, even build one for themselves - overconfidence of the developer)

Reduce onboarding efforts - helps both provider and developer, on internal and external portal: saves time and effort

Internally it can also motivate tool building

6 principles of creating great DX

1. Easy to understand

  • What it is and isn’t designed for - documentation should be authentic and trustworthy - don’t market

  • Use terminology that your users do - don’t try to be unique with it - don’t make them learn you

2. Easy to use

  • Ease of signup

  • Tryout option without commitment - don’t use gatekeepers (keys, documentation, sandbox)

  • Provide in several programming languages

3. Easy to build

  • SDKs, code samples (use multiple styles), make the right thing the easy thing

  • Have consistency both in docs and in API design - API style guide

4. Easy to get help

  • Error messages in docs to make sure they’re easy to find

  • Release notes

  • Status page - honest and overcommunicating

5. Easy to trust

  • Uptime - trustworthy, honest

  • Clear communication about business plans

6. Easy to maintain

  • For the provider

  • Has to be baked into the product design

Adam's slides



Adam's presentation

Architecting Developer eXperience: Banking and FinTech Developer Portals Case Studies

Kathleen De Roo

Information Architect and Technical Content Writer at Pronovix

Developer eXperience (DX) can play a crucial role in achieving business goals, but how can an organization motivate the developers who use its APIs?

Kathleen examines 23 public-facing developer portals in the banking and fintech industry: what features can reduce API friction?

According to the 6 stages of the downstream developer journey, you can opt for:

  • Landing page, API catalogue (stage 1: discover & research),

  • Blog, use cases, try-out & test options, trust signals like changelog, legal documentation (stage 2: evaluate),

  • Onboarding process elements, onboarding documentation, self-service support elements (stage 3: get started),

  • API references, FAQ pages, support options in 1 place, community page, discussion forum (stage 4: develop & troubleshoot),

  • Developer documentation, blog (guest post, interview), ask for feedback, events (stage 5: celebrate),

  • Release notes, status page, versioning info, legal documentation, revealing future plans (stage 6: maintain).

Throughout her talk, Kathleen gives us hands-on examples of tips and tricks, best practices and patterns.

Kathleen's slides



Kathleen's presentation

Putting the Kit back in the SDKs

Darrel Miller

Senior Program Manager - Graph Developer Tooling at Microsoft

People either love or hate SDKs

  • Feel limited - no flexibility - if they are tied to a single use case
  • Designing for flexibility requires complexity
  • You need to provide multiple languages - code generation is a double-edged sword - easy to do but also easy to be poorly architected

What we really need is a kit - be able to pick and choose the parts that we want to use - users need to have choices

KIT components

Native library

  • Request, HTTP interface, response

Core library

  • Middleware: components for applying to crosscutting concerns
  • Client factory: create native client library with desired configuration and middleware
  • Common content: common container models for collections, paging, batch, multi-part
  • Response handler: handling standard response codes and deserialization of payloads

Generated library

  • Service client: provide simple, language native interface for common use cases
  • API Models: services types for simplified payload handling
  • Request Builder: provide discovery mechanisms for resources and parameters

Workflow

  • Tasks: support for scenarios where a coordinated set of HTTP requests achieve a common goal

Takeaways:

  • Generated code is only a small part of SDKs
  • SDKs can and should add value to all developers
  • Don’t hide the HTTP model

Darrel's slides



Darrel's presentation

The Lord of API Designs

Arnaud Lauret

The API Handyman, Author of The Design of Everyday APIs, Senior API Architect at Natixis

Even the best design intentions can fail.

The problem:

  • Well-designed APIs get updated,
  • The ever increasing amount of public and private APIs,
  • Inconsistency between APIs and within the API itself.

Resulting in:

  • Users losing time,

  • The API providing organization losing users and money.

The solution:

  • Do not try to reinvent the wheel as an API designer,

  • Follow an API style guide with defined rules to ensure consistency:

    • How should an API look like and behave?
    • How do you design an API?
    • How do you update an API?
    • How do you handle the API lifecycle?

Workflow connected to set up an API style guide:

  • Write:

    • Rules based on existing APIs,
    • Rules based on existing API style guides,
    • Talk to fellow API designers.

  • Raise awareness: share and promote,

  • Update, improve (allow contributions),

  • Enforce and control:

    • Tools can help (OpenAPI Initiative, Zalando’s Zally (linter), define own rules),
    • Humans are still needed.

Rules require governance.

Arnaud's slides



Arnaud's presentation

Beyond API Documentation: Designing a Hub for a Better Developer Experience

Sylvain Maudit

Lead API Evangelist/Engineering Manager at dailymotion

In his presentation Sylvain shares how dailymotion, as an API provider, decided to go beyond API documentation to design a hub for a better developer experience for its community.

How to create a great developer experience?

Basis

Good product and good documentation

  • Powerful, accessible worldwide APIs
  • Ensure sustainable third-party integrations
  • Up-to-date and automated API reference

Add extra layers

  • Understand your community and their different needs
  • Provide the right type of content for each type of users: newbie/follower of API community, expert/contributor of the API community, influencer/leader)
  • Provide team portraits - of the people who work behind the scenes - create trust
  • Become a community hub - use every communication channel at your disposal to talk about your products
  • Engage community members in the conversation - share their opinions with the rest of the community
  • Provide the best kind of support for developers: people with both engineering and support skills

Sylvain's slides



Sylvain's presentation

Platform: How to Product?

Jessica Ulyate

Technical Product Owner at HelloFresh

How do you apply product management to an internal platform team? Jessica shares some practical tips that her team has implemented successfully.

Why?

  • Teams that focus on internal developers can supercharge the productivity of the rest of the organization,
  • Make the customers of the platform team, the developers, more efficient at the things they’re doing.

How?

Product management, in Jessica’s opinion, combines stakeholders, processes, communication and a vision.

  • Define your stakeholders:

    • Who uses your product?
    • List your projects.

  • Communicate well:

    • Tell a story when writing documentation: readme as recipe; release notes as brochure with benefits; error message as good Stack Overflow answer,
    • Write and communicate honestly about e.g. undocumented bugs.

  • Implement predictable and transparent team processes to tackle work,

  • Use your vision on the project to prioritize what is important, and remove what is not:

    • Start somewhere, e.g. divide the team into functional areas,
    • Experiment to see what really works.

Jessica's slides



Jessica's presentation

Client Library Automation, Inside Out

Avital Tzubeli

Developer Evangelist at Kaltura

External developers love the ease of using API client libraries in various languages, but what about your internal developers? Don’t they deserve an easy time as well?

Learn how to best automate your API Client Library Generation in order to efficiently save time and resources for your developers Avital presented a use case on what Kaltura does to make developers’ lives easier by offering client libraries.

Steps to follow:

  • Predict: what libraries are going to be needed, determine the most useful languages
  • Define: (Open API, XML schema
  • Share: generate the libraries

Avital's slides



Avital's presentation

Reference docs are not enough… even for internal developer portals

István Zoltán Szabó (Steve)

Senior Technical Writer at Pronovix

A devportal (both internal & external) is a place for all stakeholders of your APIs, it is to assist in achieving your business goals. It is the place where you expose your API documentation.

Documentation types on developer portals:

  • Reference docs contain all technical info on endpoints, referring to the specification,
  • Supporting docs improve understanding the APIs, via e.g. concepts, how-tos, tutorials, glossaries, FAQ, API description.

The API description page provides an intro to the API:

  • Why?

    • Helps to decide which API to use (explaining most important functions and features, benefits, requirements, example of common fields of operations),
    • Targets — apart from developers — also decision makers,
    • Helps to keep the docs consistent (which builds trust),
    • Improves DX on both external and internal portals (e.g. regarding onboarding, information gathering).

  • How?
    Steve introduces an API description page template for the technical writer and the workflow that goes with it:

    • Before writing: get a thorough understanding of the API (interview the API developers, reference documentation),
    • Writing phase with the following template sections (not all mandatory): API name, description, version number, category / tags, benefits, what is it?, why use it?, how does it work?, how to use it?, requirements, pricing.
    • After writing: review by developer, add non-textual content & call-to-actions.

István's slides



István's presentation

Original recording of the conference by Kristof Van Tomme, Creative Commons Attribution Share-Alike License v3.0