- Mehdi Medjaoui: The State of Banking APIs Portals in the PSD2 Forced Innovation Context
- Kathleen De Roo: Architecting Developer eXperience: What Docs Does a Developer Portal Need?
- Ken Davies: Big Things Come in Small Packages: API Information in Release Notes
- Lukas Rosenstock: To SDK or Not to SDK?
- Eva Casado de Amezua: Starting from scratch: we have APIs, now what?
- Stella Crowhurst: How we reduced complexity in our dev experience by combining multiple properties in a single portal
- Karen Sawrey: The Bad, the Ugly, and the Good. Moving from GitHub Wiki to a Dedicated Documentation Server
- Bridget Khursheed: Security considerations for API docs
- Taylor Barnett: Going to Infinity and Beyond Documentation with OpenAPI
- Anthony Sansone: Deploying OpenAPI within an Existing API
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.
Mehdi's slides
First talk at #apithedocs Paris is @medjawii talking about APIs in banking and their developer portals pic.twitter.com/46d0DBiBkE
— Kristof Van Tomme (@kvantomme) April 24, 2018
Our #API team is at @mozilla offices to attend @APItheDocs. @medjawii shares his experience about bank developer portal. #uxdesign pic.twitter.com/LMiY15PGkz
— dailymotionEng (@dailymotionEng) April 24, 2018
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:
- 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?
- 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.
Kathleen's slides
What your API overview pages should answer @kat_deroo #APItheDocs pic.twitter.com/NIdGEwjhKX
— Taylor Barnett (@taylor_atx) April 24, 2018
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), 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
- 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.
Ken's slides
Ken's presentation
Next is @Ken_Davies from @MicrodecPlc with a talk about release notes! #apithedocs #writethedocs pic.twitter.com/hVR7D1NO44
— Kristof Van Tomme (@kvantomme) April 24, 2018
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.
Lukas's slides
Lukas's presentation
"One strategy: what if HTTP was the SDK?", @LukasRosenstock at @APItheDocs Paris, @mozilla #API #APIthedocs
— dailymotionEng (@dailymotionEng) April 24, 2018
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
-
Eva’s slides
Eva’s presentation
Eva @1KHats totally rocked with her talk. So. Much. Useful. Info. Wow.
#APITheDocs #apithedocsparis @APItheDocs pic.twitter.com/Myjo55lu4T
— Karen Sawrey (@krnswry) April 24, 2018
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
- Internal developers and customers' devs: What is good DX?
- 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.
- 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.
Stella’s slides
Stella’s presentation
Example roadmap for creating a consistent API experience with users part of the process #APItheDocs pic.twitter.com/ijgSf43cEa
— Taylor Barnett (@taylor_atx) April 24, 2018
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.
Karen’s slides
Karen’s presentation
Here @krnswry making it easy and fun to understand the challenges of creating your own documentation server #apithedocs pic.twitter.com/0ULZKvaQxy
— Eva (@1KHats) April 24, 2018
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
- The landscape is shifting: "every company is a software company."
- Your API is already a target: API attacks are lucrative, mature and well-defined. Public APIs are well documented.
- 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.
- 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).
- APIs that give the game away: how much and what information do we make public? Be careful with cultural giveaways or auto-generated tools.
- Be professional: GitRob can help find sensitive information in GitHub repositories.
- Security is a consideration for your API.
- 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.
Bridget’s slides
Bridget’s presentation
Security considerations for API docs - @khursheb pic.twitter.com/X0VzPPkHlt
— Kristof Van Tomme (@kvantomme) April 24, 2018
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.
Taylor’s slides
Taylor’s presentation
Going to infinity and beyond documentation with OpenAPI - by @taylor_atx from @stoplightio #apithedocs pic.twitter.com/p9D3ZiMejS
— Kristof Van Tomme (@kvantomme) April 24, 2018
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).
- annotate your API code for Swagger
- re-deploy app
- 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.
Anthony’s slides
Last talk of #apithedocs Paris by @atsansone from @mongoDB - Deploying OpenAPI within an Existing API pic.twitter.com/vMh9jKWXEQ
— Kristof Van Tomme (@kvantomme) April 24, 2018
Original recording of the conference by Kristof Van Tomme, Creative Commons Attribution Share-Alike License v3.0.