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)
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.
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:
Self-service support hub: make sure users are able to find out things themselves.
Trust signal: a devportal needs to generate trust.
Documentation database for all its stakeholders. Documentation experience (DocX): what API docs do you need to provide along the user journey?
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), deprecations.
Deprecations 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
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.
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?
Adding an SDK wrapping introduces a complexity to the app that is hard to maintain over time, especially with many APIs to keep.
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.
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.
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.
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
Obvious: from monolithic to microservices — new APIs roadmap — dedicated engineering team — technical writer to document the APIs
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
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.
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.
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)
Standardization helps, the OpenAPI spec as a collaboration tool:
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.
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).
annotate your API code for Swagger
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.