API THE DOCS, LONDON
One-day conference about API documentation and developer portals. Explore the latest best practices, strategies and new trends.
November 9th, 2018

Introduction to OAS

Lorna Jane Mitchell

Developer advocate at Nexmo

API documentation is key, but "sometimes developers and documentation just don’t mix." Developer eXperience is giving developers what they need to succeed, and OpenAPI specification (OAS) can help in that.

OAS

  • Is a good choice for describing RESTful APIs in a machine readable-way,

  • Enhances DX: an API spec is reusable and this can be super powerful,

  • Is a result of teamwork: product owners, writers, engineers should co-write it.

New APIs or existing ones?

  • Retrofitting an existing API into OAS is not always easy, but it’s doable and valuable,

  • Spec-first API design: cheaper and effective way to design a new API starting on actual development, with all the stakeholders included in the conversation (product owner, writer, engineer).

Anatomy of OAS

  • Tree structure, like a ToC with chapter headings, subheadings,

  • Json or yaml file holds the description,

  • Add (standardized) metadata now for discoverability in a future API ecosystem ,

  • Lots of APIs? Group and re-group using your tagging system.

Tools

  • ReDoc: render the yaml to your branding, the front-end is entirely separate from the spec content,

  • Source control! Commit the description file when it's working,

  • See further Lorna Jane's presentation on editing-, validation- and preview tools.

Talk summary

Lorna's slides



Lorna's presentation

The Trials and Tribulations of the API Style Guide

Andrew Johnston

Technical writer at Shopify

The relationship of the resources may be complex. Organizational and product marketing considerations will dictate the content (mental models).

Casing conventions are necessary for comprehensive navigation.

Depending on your APIs, may group by area of functionality or by product marketing technology.

A devportal's content is not just transactional, it is relational. "Inconsistency in your documentation patterns slowly erodes your developers' trust, even if they don't tell you."

Style guides

  • Writing without a style guide can cause inconsistency which can lead to losing the developers’ trust,

  • A model is needed, especially if your team starts to grow, and there are more writers with different levels of experience.

Style guide playbook

  • Research on best practices and decide on your own house style

  • Examples style guides:

  • Publish

The software developer’s job is to ensure the API is working.

The developer evangelist and product marketer are to sell the API.

The technical writer has to ensure that the APIs are documented efficiently and consistently.

Talk summary

Andrew's slides



Andrew's presentation

Content Strategy for DevPortals

Emmelyn Wang

API Strategist at Axway

The likelihood of a purchase drops sharply as the number of decision makers increases

  • Devportals spectrum options — to buy (might not meet all the requirements, implementation is needed) or to build (starting from scratch, choosing stack, allocating resources),

  • Consider the competition and understand the business landscape.

Content strategy — solutions

  • Long-tail keywords: engineering/developer-focused results,

  • Engagement with the dev community: publishing and maintaining relevant content is key,

  • Long-term strategy: engagement is far deeper than a financial transaction, it’s relational.

Software architecture — solutions

  • Design-first approach is less expensive,

  • Provide a safe place to share information, — Slack is moderated, has community guidelines and people can discuss questions with experts (professional developers),

  • Continuity of care (it is quite possible that a devportal content strategy is more about service),

  • Test DevPortal interaction — physical prototypes foster conversations about how we interact,

  • Measure impact: customer and developer journey mapping.

API maturity and resources define the content lifecycle: no portal or pre-devportal (API references only) → rebuild devportal (relaunch) → optimize devportal

Takeaways:

  • The API specification should be the core of your API content strategy,

  • Provide business context (through strategic partnerships) and technology context (speed, performance),

  • Map out where traffic is coming from and where it goes. Crosslink between the two where it makes sense,

  • Ask developers what they want and stay true to deliver what they tell you,

  • Your content strategy needs to match your business and is a direct reflection of your relationship with your developers,

  • Content strategy for DevPortals is all about delivering a high value experience to win and to keep customers,

  • Measure impact,

  • One of the ways to achieve high value experience is through the highest quality DX with high availability, digital experience, security and business intelligence,

  • Don’t just offer giveaways, let the quality of the content and engagement drive the value,

  • Goal of a great devportal: make it evolve from “a devportal” to “my developer portal”,

  • The best way to recognize your developer community is to invest in them over time.

Talk summary

Emmelyn's slides



Emmelyn's presentation

HMRC Developer Hub - An Experience Report

Tony Heap

Business Analyst at HM Revenue & Customs

Mick Schonhut

Technical Writer at HM Revenue & Customs

Tony and Mick started their presentation with demoing their Developer Hub — home page, getting started, general documentation examples, API docs list, API docs example.

How they write?

  • Writing style — finding a common language,

  • Following style-guides (GOV.UK, HMRC and Developer Hub),

  • Ideally pair-writing — less efficient with asynchronous collab tools (GDocs),

  • Choosing RAML over Swagger and JSON schema,

  • Convert RAML to HTML,

  • Consistency across different teams.

Feedback and iteration

  • Feedback tools — heatmaps (HotJar), surveys, beta banner feedback, pop-up polls.

End to end doc needs — beyond the API

  • Diversity in audience (entrepreneurs, product owners, business analysts, architects, lead devs) generates extra content needs (timelines, usage scenarios, end to end user journey),

Their approach to API development: design, delivery, governance, HMRC’s API Service Process and Standard, GDS (currently only internal) API design best practices.

Takeaways:

  • Feedback and user research are essential,

  • Documentation quality actually matters — it can make a difference to API consumers,

  • Developers' experience, standards, programming language, thinking style etc is on a wide spectrum,

  • A complex API needs extensive contextual documentation — end-to-end user journey,

  • Ease and speed of doc updates matter — need a lightweight CMS (docs-as-code), GitHub, markdown processor.

Talk summary

Tony and Mick's slides



Tony and Mick's presentation

The API BizDev Portal

Sophie Rutard

Head of API Euler Hermes at Euler Hermes

Why we need more than only great DX: discovering the devportal fast then going into development is not the whole story.

Key requirement: non-technical demo of the API’s business value

A large number of people are involved in the entire process with different needs and experiences:

Key business needs/requirements

  • Non-technical demonstration of the API’s business value,

  • Functional API catalog,

  • Inspirational use cases beyond the API,

  • Exact API solution suggestions to enhance a certain process within the business user interface,

  • Easy communication channel,

  • Support for estimation of project efforts and business case calculation,

  • Second level support — clearly defined contracts.

Key needs/requirements of developers

  • Tutorials: easy introduction to the business context,

  • Detailed explanation of key legal requirements,

  • Highlight business consequences of functional errors,

  • Clear link between API docs and related functional use cases to make IT and business really together in this.

The BizDevPortal’s characteristics:

  • Has a mixed team of business and IT experts,

  • Enhances end-to-end UX,

  • Complies with legal requirements,

  • Is backed by professional support when needed.

Takeaways:

  • Know who your stakeholders are and address them in a language that is familiar to them.
  • If the business people don’t buy in, the developer won’t even get to look at your devportal.
  • The BizDevPortal needs to support the collaboration between developer and business experts: only then will the project succeed.

Talk summary

Sophie's slides



Sophie's presentation

API Design for Microservices Using Apiary

Luis Weir

Chief Architect at Capgemini UK

APIs are doors to information and functionality. They’re an organisation’s main entrance to digital services and offerings.

What can help?

  • API design-first approach with continuous testing and feedback,

  • Microservices are APIs,

  • Strong emphasis on domain-driven design.

Why Apiary?

  • Covers the whole API lifecycle (design, mock, validate).

Benefits of API-design first

  • Avoid rework by implementing feedback-loop in the earliest phase of the API lifecycle,

  • Parallel development: decouple App dev from Service dev,

  • Up-to-date API documentation.

Talk summary

Luis' slides



Luis'presentation

VMware's Journey to Deliver Developer Portals as a Service

Richard Thomchick

Product Manager at VMware

The Evolution of VMware APIs

  • The need for a scalable solution: from vSphere to the Hybrid Cloud
  • The strategy: make APIs and documentation that enables the developers to create hyper cloud-related solutions,
  • Direction to go: automation and streamlining of the available resources

Richard’s presentation included a demo of the VMware’s API explorer, which is

  • Open source,
  • API driven,
  • container friendly,
  • provides deep-linking search across the APIs — useful if the APIs are not known but the operations.

Customers’ reaction: the API explorer felt like much more an entire developer microportal.

Streamlining Content Management: DxPress

  • Developer Experience Press — it’s like WordPress for Developer Content
  • A subservice content management system

What’s next? VMware {code} 2.0

  • One developer experience, accessible from any device, on the web and in-product

How to achieve it

  • Validated research upfront: making sure you are talking to the right audience and correctly identify their most-pressing issues, then create the solution which actually addresses their problems,
  • Lean UX design: kind of like user-centric design, with lots of prototyping and learning as fast as possible based on feedback,
  • Constant contact: keep users involved and communicate — probably the most important piece of the puzzle,
  • Relentless automation: CI/CD option,
  • Beware of "dependency hell" (a microservice issue, or issue working in a big company),
  • Avoid over-engineering (a caveat of a microservice architecture): don’t build a rocket ship for a trip to the greengrocer,
  • Customers and developers need a single source of truth for API documentation,
  • Be lean and agile.

Talk summary

Richard's slides



Richard's presentation

Is GraphQL Really "Self-documenting"?

James Scott

Technical Writer at Moogsoft

What is the problem?

  • Developers think GraphQL is self-documenting,
  • Twitter: lots of devs think very positive things about the self-documenting / self-describing features/aspects of GraphQL,
  • What does self-documenting mean? — written and structured in such a way it can be understood without documentation or prior-knowledge.

Beware:

  • Interpretation is subjective,
  • Homographs: words that spell the same, but are pronounced differently or have multiple meanings.

What is GraphQL?

  • 2012: First internal release at Facebook
  • 2015: Open-sourced GraphQL
  • Data query language for APIs
  • Can retrieve data using a query
  • Can modify data using mutation
  • Users can specify the exact data they want — no over-fetching of data in the results
  • Exposes a single endpoint to do all of these things
  • Problems: the documentation GraphQL produces is not that human-readable

Key principle: thinking in graphs, where a graph is like a tree.

Advice from the co-creator Lee Byron

  • APIs are rather a design problem than a technical one,
  • If there is no documentation, it doesn’t matter how good the API is,
  • What makes an API work well: mapping to your internal mental model, then providing explanation of those linkages and details,
  • GraphQL doesn’t do that for you, but provides some clear space to fill (the types, the fields, introspection where you can add descriptions),
  • From this aspect GraphQL can be self-documenting.

GraphQL Voyager: explore your API as if it was an interactive graph and the schema, how things relate to each other.

What is the answer?

  • Provide the onboarding (hand-holding) documentation,
  • Provide documentation specific to the API: query and mutation examples, specific use cases,
  • Naming is crucial — choose appropriate names for your fields/types use good descriptions in the schema,
  • Test: ‘Would a (beginner) engineer understand this?’,
  • Avoid using code names and server-side lingo.

GraphQL can be self-documenting as in self-explanatory: providing you spaces to fill.

Talk summary

James' slides



James' presentation

All Resources Are Equal, but Some Are More Equal than Others - Documenting Hypermedia APIs

Nick Bradley

Lead API Writer at Worldpay

Brief introduction to Hypermedia

  • Hypermedia — generally refers to anything that isn’t simply hypertext (e.g.: images, video),
  • In this context: hyperlinks,
  • HATEOAS (Hypermedia as the engine of application state) — an architecture designed to allow the consumers to manage state using hypermedia hyperlinks, which get returned in the response,
  • HAL (Hypertext application language) is a hypermedia convention, used to standardize the response and to help the client in consuming the hyperlinks everytime.

How is it different from REST?

  • REST is a flatter line of resources, URLs known upfront,
  • HATEOAS: hypermedia driven APIs, URLs generated dynamically by previous requests — they represents an action, not just a resource.

Why a hypermedia API?

  • Worldpay created their own specification instead of Open API
  • With standard REST APIs there could be problems making invalid requests (URLs for logically invalid actions already known upfront) — unacceptable with payment services
  • With HATEOAS for example a refund request’s link is only generated once the funds have already been settled.

Documentation

  • API specification files for discoverability,
  • API reference documentation: generated from API specification files,
  • API guide: conceptual docs and education,
  • User guide: focus on (business) concepts and use cases.

The resource tree maps out how each resource can be reached. For each resource its own json file, this gives more space for adding examples.

Where next?

  • More interactive assets,
  • Sandbox/playground,
  • Open source the specification and UI.

Takeaways

  • HATEOAS is not for everyone, you have to make sure that it fits to your use case,
  • Discoverability helps ease the pain: the hypermedia links allow users to click through the API docs and see it in action — as if they were making the request,
  • Listing out all of the action links: with hypermedia, users can see what their next actions are and what are they linked to,
  • Education is key — it prevents wrong integration,
  • Creating your own specification is also an option,
  • It’s all about actions and trees, URLs are generated automatically.

Talk summary

Nick's slides



Nick's presentation

How to Create the API Document from Real API and Localization

Atsushi Nakatsugawa

CEO at Moongift

Localization

  • Easy to misunderstand the documentation if you are not a native speaker,
  • English speaking rate is low in Japan (12%),
  • Cost of the documentation translation and update is high and difficult (English to Japanese),
  • Translation vs localization.

GitHub Wiki

  • GitHub wiki is a good service, but not suitable for API docs and hard to maintain,
  • It is dividing code and documentation,
  • Does not support pull request workflow and localization,
  • Creating documentation on wiki which covers everything and always up-to-date: almost impossible.

Localization with GitHub Wiki

  • Workflow: copy the original English document to a Japanese page, and translate it by hand
  • After a new release: need to search for what has been changed and update that part of the translation
  • Maintenance is really tough, while the halfway documented APIs make the job of the developers hard.

Documenting in code with comments

  • It is a good solution (connects code and documentation),
  • But programmers are not necessarily able to write proper documentation and too many comments are distracting.

Atsushi’s workflow

  1. Having an API
  2. Generating Swagger yaml from curl command: curlToSwagger
  3. Generating Markdown from Swagger: Swagger2Markdown
  4. Creating .po files for translating, then updating them — English and Japanese MD files at the same time
  5. Static Site Generator: MkDocs (most swagger based document generators don’t support localization)

Talk summary

Atsushi's slides



Atsushi's presentation

The Ultimate API Publisher’s Guide

Joyce Lin

Developer Evangelist at Postman

Types of APIs

  • Public APIs are available to the broader developer community,
  • Partner APIs might be shared as web services with clients or you might be the client consuming the service,
  • Private APIs are for services that you share internally within your team.

Postman 2018 API Survey

  • More than half of all APIs are internal (private) APIs,
  • Most developers spend more than 10 hours a week working on APIs,
  • Developers gain most of their knowledge about APIs on the job/from colleagues.

Three steps in the developer journey

  1. Building awareness
  2. Gaining adoption
  3. Maintenance of accurate and up-to-date documentation

Building awareness for (Public APIs)

  • Focus on SEO/SEM,
  • Community engagement,
  • Strategic partnerships.

Building awareness (Private APIs)

  • Purpose of documentation,
  • Single source of truth: putting all of your APIs and documentation in one place,
  • Agile software development.

Gaining API adoption (both Private and Public APIs)

  • Guide the onboarding,
  • Organize and reference,
  • Interactive demos,
  • Tutorials and guides,
  • Provide sample code.

Maintaining up-to-date and accurate documentation (both Private and Public APIs)

  • Definition of done: part of project management tracking,
  • Versioning API documentation,
  • Continuous improvement with feedback.

Takeaways

  • Know your target audience (n00b, expert, buyer, non-technical),
  • An API is a technical abstraction for consuming a service, and the documentation is the abstraction which allows humans to use the API,
  • The documentation is a part of the API,
  • Providing context is so important: not everyone shares the same basis of knowledge (curse of knowledge),
  • Possible solutions to improve your documentation: additional tools, better workflow, SDK, better examples, standardization, sample code, real world use cases,
  • Make it easy for the community to report issues and provide feedback.

Talk summary

Joyce's slides



Joyce's presentation

I Try to Use Your API, You Won't Believe What Happens Next (live testing)

Cristiano Betta

Developer Advocate at Box

Cristiano held a live API experience review, started his session with looking for candidates who meet the criteria:

  • Have a public API,
  • Anyone can sign up for it free and can play with it.

The goal of his review session was to find out how the onboarding works and how easy it is to get started.

During the demo he created a friction log, where he added examples of pleasure, frustration and pain he experienced, extended it with his suggestions.

He reviewed PipeDrive’s APIs from these aspects:

  • How easy is it to find the dev docs,
  • How smooth is the signup,
  • Design,
  • How easy is it to get an API token and make an API call,
  • How easy is it what the product does before you get started,
  • Get started guide,
  • Example responses, response definitions, descriptions,
  • After successfully making an API call, is it easy to find out exactly what has been done and what the parameters are?

Talk summary

Cristiano's slides



Cristiano's presentation

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

Conference sponsors: