Document the API

Document the API Alec Clews ASTC Annual Conference October 2018 Slides at https://tinyurl.com/alecthegeek-api-docs

Agenda ● What are APIs and why should I care? ● What's different about API docs? ● How should API docs be structured? High level content plan ● Some important messages on content and reference material ● What tools do I need?

Who is Alec? Old school software nerd Consulting, docs, code, testing, support, speaking, ... Works as the technical integration manager at PaperCut Software "The API guy" "Developer Relations" or "Developer Evangelism" Loves technology, sometimes too much! and beer and coffee... @alecthegeek alecthegeek https://www.linkedin.com/in/alecclews/

Who needs API docs? ● Second and Third Party Developers: ○ Customers ○ Business Partners ○ Independent software vendors ○ Other teams in your organisation (but we'll ignore them)

& why are API docs important? ● ● They will help your product or service be more successful. For example ○ Uber taxi application integrates with Google Maps ○ Re-Leased Property Mgt Software integrates with Xero If they get stuck they'll either ○ Not bother to use your product ○ Call your support desk

How do APIs enable success? ● No software exists in isolation ○ Customers and partners can integrate your system with other systems ● Extend the value of your product ○ Third parties can deliver solutions you can't ○ Pushing your brand into new markets ● Your ecosystem becomes deeply engaged with you and your product ● Your brand is supported with a quality API programme delivery

Application Programming Interface ● Contract between two pieces of software a.k.a specification ○ What can the client request? ○ What will the server do? ○ What will the server send back?

What is an API contd: API calls can take place in many places between software components ● Inside a single program ○ e.g. word processor editing module and spell checking library ● Between two programs on one computer ○ The fitness app on your smartwatch and the sensor firmware ● Across the network ○ e.g. between your phone and the Google Maps data servers

How are APIs used? ● Today most visible API use is across the network ○ Cloud servers doing stuff for: other cloud servers; on premise services; smart phones; desktop computers etc. ● But sometimes not. Consider the API on your smart watch ● Network API traffic is often across https (post, get,...) ○ Example of Specific API protocols build on top of https ■ ● RESTful, XML-RPC, gRPC, GraphQL... Pub/Sub for many to many asynchronous message exchange

So API Docs? Note - DITA information types are still relevant: ● Concept ● Topic ● Reference Mostly the same as product docs, but also a little different We start with the same questions: 1. 2. 3. 4. Who needs this and what are they trying to do? How can they achieve this? What information do they need? What is the most effective way to present this information? NOTE: The following notes assume a public web API with a wide audience.

Who? On a public API it can be ANYONE 1. Might not use the same written/spoken language as you 2. Have different objectives to the ones you imagined 3. Have a wide range of experience and knowledge 4. Use many different programming languages and libraries

What are they trying to achieve? Often something you cannot currently imagine! You think it's an accounting interface, someone else will have different ideas With a wide range of technologies So set the expectation on what is possible and what is sensible. Document clear boundaries

Content Themes Your Audience Needs Accurate, precise & current information Because APIs often follow a continuous deployment model outside your release schedule Understand what's achievable & the effective way to do it APIs are like a Lego set, not a doll's house Concepts and Scenarios -- the complete lifecycle(s) of Devs usually don't use your product and don't solutions understand it. They need context Working examples Developers will work faster starting with a working example Reference material -- API Specifications Programming needs precise, detailed and accurate information

Important Message One ● API Reference Docs alone are NOT GOOD ENOUGH ○ ● Just throwing Swagger or similar docs onto a website is not helpful! We also need ○ What, Why and How (Concept) ○ Getting started guides (Task) ○ Security information (Task and reference) ○ Complex use cases (Task) ○ Error recovery (Task and reference)

Important Message Two ● ● Demonstrate & Discuss complex use cases Document how things can go wrong and how to handle it You can't control the environments in which the integrations run. Assume Murphy's Quantum Law is in play: Anything that can, could have, or will go wrong, is going wrong, all at once. Paul Dickson, in The Official Rules (1982) ● Provide complete examples Simple examples will not help developers create real world solutions

Important Message Three Security in the Internet age is important API security is important! Make sure your API is secure DOCUMENT YOUR API SECURITY Shared secrets, username and password, JWT, TLS, ….

Effective Presentation & Content Suggestion Because Web pages or developer portal Easy to update, easy to access Complete code examples Development is a practical craft Lots of diagrams Make complex relationships & details clear "Proper" authoring tools are perhaps not best choice Fast turnaround API Docs sit near the code Help product teams to help you

Work with the product team Your API documentation is: 1. 2. Closely linked to the corresponding product code Contains a lot of technical content Keep the docs close to the code: 1. 2. Get the developers maintaining as much of the material as possible Follow the developer life cycle and make updates as easy as code change See also Docs as Code

Tools and formats ● Something you can use with your devs. ○ ● Your current doc tool may not be suitable... Plain text based helps more people contribute ○ e.g. Markdown or reStructuredText ● Code snippets from working code. Automatically include code changes ● Create diagrams from text ○ ● API reference generator tools. ○ ● E.g. Plantuml, Graphviz E.g. Swagger Automatic checking, formatting, generation & publication

Creating Diagrams from text @startuml collections Clients participant Server database Database Clients -> Server: Request and details Server --> Database: Query Server <-- Database: Data Server --> Server: Processing alt Success Clients <- Server: Status and information else Failure Clients <- Server: Error codes and information end @enduml PLANTUML

Further information Some places to start: https://apithedocs.org/ http://www.writethedocs.org/guide/api/about-api-documentation/ https://pronovix.com/blog/infographic-what-developer-portal More Advanced information: https://github.com/alecthegeek/doc-api-old-skool/wiki/Article https://www.openapis.org/about for RESTful APIs