API THE DOCS, PARIS

One-day conference about API documentation and developer portals. Explore the latest best practices, strategies and new trends.
April 24th, 2018

The State of Banking APIs Portals in the PSD2 Forced Innovation Context

Mehdi Medjaoui

Lead API Economist at API Academy

Because of PSD2 regulation, all EU banks are obliged to open APIs in a forced innovation context. Mehdi presents 8 different banking approaches to API portals (RBC, Teller, HSBC, Credit Agricole, BBVA, Deutsche Bank, Fidor, Capital One).

Top 5 demands developers and CTOs ask for

  • Reliability, transparency and performance
  • Testing Sandbox reproducing real API behavior
  • Up-to-date documentation, with sample codes
  • Great Developer experience (seamless onboarding, legal process in the background)
  • User personas (fake-real user account acting like real customers over time)

Takeaways

  • Banks are far from Fintechs like Stripe, Square etc…
  • Even the advanced ones don’t match developers’ expectations.
  • There is design gap for Developer experience products.
  • There is a huge opportunity for consulting helping banks being sexy for developers.

Talk summary

Mehdi's slides





Architecting Developer eXperience: What Docs Does a Developer Portal Need?

Kathleen De Roo

Technical writer at Pronovix

How can you inspire and motivate the developers who use your APIs to become advocates? In this talk, Kathleen takes us on a journey full of practical examples taken from 38 public-facing developer portals.

Developer portals have four main tasks to do:

  1. Self-service support hub: make sure users are able to find out things themselves.
  2. Trust signal: a devportal needs to generate trust.
  3. Documentation database for all its stakeholders. Documentation experience (DocX): what API docs do you need to provide along the user journey?
  4. DevRel Tool. Developer experience (DX): what are the practices to reduce friction & engage users ?

Overall conclusion:

Take care of developer experience and documentation experience and your business will benefit from it.

Talk summary

Kathleen's slides



Big Things Come in Small Packages: API Information in Release Notes

Ken Davies

Technical author at Microdec

What is a release note exactly? It's a documentation type: new features, bug fixes, change in the way features are to be used, known issues, upgrade paths (to the quickest way to the latest version), deprications.

Deprications are less often talked about. Software moves on, or some functions are not needed any more.

Semantics are important: bugfix or resolved issue?

API specific release notes:

  • change of syntax
  • change of elements
  • under-the-hood changes
  • extra info on benefits
  • what behaviour change can happen

Challenges for the technical writer:

  • Too much change, too little time to learn all those new things.
  • Unclear/insufficient information.
  • Noise from devs/other departments, confusing.
  • Distillation of lots of info is a lot of work.
  • Difficult personalities (paranoid, grumpy,...). Falsely positive feedback.
  • Teams in silos (unclear helpdesk tickets, clients want information).

Writing release notes forces communication, raises questions around business goals and technical testing. Brings home the need for documentation again.

Talk summary

Ken's slides



Ken's presentation



To SDK or Not to SDK?

Lukas Rosenstock

Software developer (mostly PHP, some JS), technical writer, API consultant, and entrepreneur. Building CloudObjectsIO

Are SDKs really necessary, are they worth the cost and effort? What are the advantages for API consumers and for API providers?

Contra SDK:

  • Adding an SDK wrapping introduces a complexity to the app that is hard to maintain over time, especially with many APIs to keep.

Pro SDK:

  • Beginner-friendly.
  • Standard way per each language, support is easier.
  • More robust and less load because there won't be so many wrong (false + or -) API calls.
  • Client-side logic.
  • Shows active involvement to the community.

Furthermore, Lukas explains:

  • The 4 patterns of an SDK strategy: provider-supported — community-contributed — consumer-driven — HTTP is the SDK,

  • Good SDKs design: API design first — open source is a must — make SDK development part of the API testing, "Respect the target platform's approach first, and the consistency within your API second",

  • The pros and cons of auto-generated SDKs: standardized approach vs not necessarily adding business-specific value,

  • How to document APIs and SDKs (approaches: API first, SDK second — SDK first, API second — integrated — tutorials vs references: take care of consistency) via examples taken from the Stripe, Twilio, Algolia, Sendgrid, AWS, and Google developer portals.

Takeaways:

  • Provide SDKs if you have the resources and believe there's additional value or if you want to support beginners.
  • Design both APIs and SDKs well and respect them on your portal.
  • SDKs, once out there, will shape the DX of your API, so keep an eye on and help with the community-developed ones too.
  • SDK development is a great opportunity for API testing.

Talk summary



Lukas's slides



Lukas's presentation



Starting from scratch: we have APIs, now what?

Eva Casado de Amezua

Developer Community Manager at Typeform

What goes on internally before launching a public-facing developer portal? What problems do you need to tackle? What are the implications of certain ideas and decisions? What comes next?

Goals: a solid suite of APIs, good reference docs, engaged developers

How?

  • Obvious: from monolithic to microservices — new APIs roadmap — dedicated engineering team — technical writer to document the APIs

Result:

  • To-do-list: what to keep, what to give up in initial phase?

  • The platform team becomes a separate business unit that reports directly to the founders and investors.

    • Not so obvious: learn how to approach developers (via marketing) — buy-in from leadership team — real-life testing (internal hackathon: engineers team up with non-engineers to test the APIs and the API docs) — depricate old APIs

    • Long-term plans: a platform team that manages all processes related to the developer platform — a developer portal beyond the API references — a DX model — focus on relations within the company to be able to push the product

    • Results of the first stage: A developer portal with API references and an SDK — get started section — troubleshooting — a basic community page

    • Plans: sandbox — open source docs (on GitHub) — changelog

    • Road improvements: developer relations — partnerships & integrations — innovation — feedback loop

Talk summary

Eva’s slides



Eva’s presentation



How we reduced complexity in our DX by combining multiple properties in a single portal: developer.worldpay.com

Stella Crowhurst

Director of content strategy at Worldpay

Nick Bradley

Lead API writer at Worldpay



Story continued from 2016 Agile the Docs conference.

Resources and budget from different stakeholders for a proper DX portal

  • Consolidate hubs.
  • Improve the developer experience.
  • Normalize hub for administrators (large backend, many API developer engineers).
  • Innovate.

Planning steps

  1. Internal developers and customers' devs: What is good DX?
  2. Developer personas for the hub: A/ experienced dev B/ not educated in WP's services, just needs a payment method integrated fast, C/ decision makers.
  3. Architecture workshop: backend to frontend, what CMS to use, information flow considering the personas.

Consolidation phase

  • templates, style guides, brought all docs into a similar feel.

New implementations for DX improvement

  • Provide a quickstart environment for new users.
  • Changed from madcap flare (not flexible enough for them) to markdown.
  • Open Sandbox.
  • Shifted from docs-as-code to docs-in-code.
  • DevLab: open innovation area.
  • Merged with Vantage, who had a large dev community in the US, they grew that further (rather than fostering two separate ones).
  • Binary or multiple choice side filters for APIs for different users.
  • Docs must be translated to several languages.

Technical details for DX improvement

  • Search, analytics: AngularJS Pro vs static site?
  • Restful, HATEOAS (developer can explore the whole API in an interactive sandbox).
  • Devbot to answer technical questions, also provide feedback to support team on what is missing from the docs.
  • Teach devs how to write for the customers (rather than to themselves), the tech writers become editors.

Talk summary

Stella’s slides



Stella’s presentation



Moving from GitHub Wiki to a Dedicated Documentation Server

Karen Sawrey

Technical Writer at CossackLabs



Task: move 3 documentation sets from GitHub to their own servers

The main ready-made platforms have security issues that a cryptography company cannot afford to have, so they decided to set up their own docs server from scratch. Lots of documents, have to explain a lot before people are even ready to try the crypto part. Building the platform - collect references on what it should look like

Main problems and solutions

  • GitHub migration tools are buggy or clunky -- own developers made custom tools for exporting and cleaning.
  • Relinking after content migration couldn't be automated.
  • Increase readability - developers were used to GitHub.
  • Make the community aware of the new server.
  • Inside feedback --» fix --» beta version.
  • Keep entry points & minimal info on GitHub for people to find the new server. RSS feed for their GitHub Wikis.
  • "There is no final version." — documentation must evolve constantly.

Talk summary

Karen’s slides



Karen’s presentation



Security considerations in API docs

Bridget Khursheed

Global Documentation Manager at KAL



  • How can you maximize security in API docs?
  • How are we, as technical writers, affected?
  • What vulnerabilities might docs expose in a PSD2 environment?

The current situation

  1. The landscape is shifting: "every company is a software company."
  2. Your API is already a target: API attacks are lucrative, mature and well-defined. Public APIs are well documented.
  3. Spectrum of vulnerability: hacked by bad guys — accidentally auto-published API — hacked by good guys — hacked by students who tag your API — picked up in PEN testing or in security audit plug holes.
  4. Attacks via social engineering (e.g. phishing or software tools that stalk your data) — software to scrape information (e.g. GitRob) — marketplace (e.g. via MaaS).
  5. APIs that give the game away: how much and what information do we make public? Be careful with cultural giveaways or auto-generated tools.
  6. Be professional: GitRob can help find sensitive information in GitHub repositories.
  7. Security is a consideration for your API.
  8. Imminent targets: PSD2 offers opportunities for organized crime.

Best practices

  • Train yourself in API security and social engineering — become cyber security aware.

  • Include:

    • for developers/security policy: writing restrictions — secure authentication — regular security audit/PEN test,
    • for documentarians: OPSEC obfuscation (e.g. make code examples less clear, avoid examples that follow company culture) — check backup files for inappropriate content — don’t have features that encourage users to be insecure — handle auto-gen with care — learn to code.

Bridget provides us, throughout her talk, with hands-on examples and further references to dive more deeply into the topic of cybersecurity.

Talk summary

Bridget’s slides



Bridget’s presentation



Going to Infinity and Beyond Documentation with OpenAPI

Taylor Barnett

Lead Community Engineer at Stoplight



The OpenAPI Specification, a standard, structured approach for describing APIs, can be used for more than writing/generating reference documentation: you can also apply it for e.g. contract testing, prototyping, client SDKs. Taylor explains.

Self-documenting APIs do not exist, there will always be manual work:

  • description of endpoints
  • guides and tutorials (use references with eg. DapperDox, to create examples that auto-update)
  • DX

Standardization helps, the OpenAPI spec as a collaboration tool:

  • simpler writing
  • standard terminology
  • get certain things done faster

The OpenAPI spec enhances DX:

  • Design-first: Open API helps create consistency for users
  • Mocking: dynamically generate examples from the specification
  • Testing: for accuracy (DREDD), against a style guide (SPECCY)
  • Feedback: “Making a spec public is a centerpiece to get feedback” — Kin Lane

Going to infinity: explore further what can be done with the help of OpenAPI, such as linting and style guides.

Talk summary

Taylor’s slides



Taylor’s presentation



Deploying OpenAPI Within an Existing API

Anthony Sansone

Senior technical writer at MongoDB



Goal: automate the specification and concentrate talents in developing tutorials. This decision may look obvious in hindsight, but they had to do some research before coming to that conclusion: Writing for Scale: Streamlining API Documentation Maintenance

This talk describes the why and how of automatically generating your API specification.

In every tooling case, automation relies upon creating a YAML configuration file: routes, methods, parameters, error messages, and so on for each endpoint. Each tool provides editors, linters and the like to create and validate these files.

MongoDB chose Swagger: well supported and well adopted. Starting with an existing API with almost 200 endpoints across dozens of classes, there is not full automation to import. Swagger has:

  • Editor: Edit your OAS YAML file in the browser.
  • UI: Display your OAS YAML file as documentation.
  • Inspector: Test APIs and generate OAS specification from existing APIs.
  • CodeGen: Automatically generate SDKs for your Cloud API in 15 different programming languages.
  • You can modify your API code with Swagger’s annotations and your application generates the OpenAPI specification file for you.

Existing tools to generate the API specification file in six different programming languages With Swagger-Core, the docs team needs only to annotate the existing code (Jersey/JAX-RS for our REST API code).

  1. annotate your API code for Swagger
  2. re-deploy app
  3. compile, download JSON file

Tech writer's development environments set up exactly as of their API developers', to enable working with the codebase in a manner consistent with their development practices.

An unexpected benefit of choosing to work within the API codebase: you learn how the code is organized.

For all further technical details –and there is a lot!– look up Anthony's slide deck, with speaker's notes.

Talk summary

Anthony’s slides



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

Conference sponsors: