Docs-First API Design Lorna Mitchell, IBM Analytics Software Architecture, London 2016

Starting an API Project @lornajane

API Design Understand requirements and audience, then make decisions • Style: REST, RPC, something else? • Format(s): JSON or XML (or HTML or yaml ...) • Authentication: pick a standard, e.g. OAuth @lornajane

Documentation As Communication @lornajane

Documentation Enables Discussion • All stakeholders can interact with documentation • Documenting details (including endpoints, code samples, error handling) at this point helps iron out questions early • Be strict about what's in scope Pro-tip: use this approach for internal interfaces too @lornajane

Choosing Documentation Tools @lornajane

Choosing Documentation Tools • Quick to create • Easy to deploy • Painless to maintain/update/evolve @lornajane

Documentation Tool: Slate My favourite is Slate https://github.com/lord/slate • Markdown to static HTML • Well organised • Built-in support for code samples in multiple languages Also used by http://docs.cloudant.com @lornajane

Documentation Tool: Slate @lornajane

Writing Great Documentation @lornajane

Great Documentation Ingredients • Overview • Data format(s) and validation • Authentication and rate limits • Error behaviour • Pagination • Where to go for help @lornajane

Documentation as Education Every API is someone's first API • No such thing as too much information! Link to other reference materials, feel free to include diagrams • Include detailed examples for each endpoint • A quick-start tl;dr for the more experienced works well @lornajane

Overview Documentation @lornajane

Slate Markdown #  Cloudant Basics If it's your first time here, scan this section before you scroll further. The sections on [Client Libraries](libraries.html#-client-libraries), [API Reference](api.html#-api- and [Guides](guides.html#-guides) assume you know some basic things about Cloudant. ## HTTP API All requests to Cloudant go over the web, which means any system that can speak to the web, can speak to Cloudant. All language-specific libraries for Cloudant are really just wrappers that provide some convenience and linguistic niceties to help you work with a simple API. Many users even choose to use raw HTTP libraries for workin @lornajane

API Reference This is the per-endpoint documentation and should include: • High level description • Documented default values and behaviour • Examples for curl plus one or more target programming languages @lornajane

API Reference @lornajane

Slate Markdown ## Databases Cloudant databases contain JSON objects. These JSON objects are called [documents](document.html#documents). All documents must be contained in a database. ### Create > Create a database ```http PUT /$DATABASE HTTP/1.1 HOST: $ACCOUNT.cloudant.com ``` @lornajane

API Description Languages • http://swagger.io/ with Swagger UI and many other tools • formed the basis of Open API Spec https://github.com/OAI/OpenAPI-Specification • https://apiary.io/ also with excellent tools, supports API Blueprint and Open API Spec • http://raml.org/ another API description language with great tool support @lornajane

Open API Spec: JSON or YAML { "swagger": "2.0", "info": { "version": "1.0.0", "title": "Swagger Petstore", }, "host": "petstore.swagger.io", "basePath": "/v1", "schemes": [ "http" ], "consumes": [ "application/json" ], "produces": [ "application/json" ], @lornajane

Open API Spec: JSON or YAML ... "paths": { "/pets": { "post": { "summary": "Create a pet", "operationId": "createPets", "tags": [ "pets" ], "responses": { "201": { "description": "Null response" }, "default": { "description": "unexpected error", "schema": { "$ref": "#/definitions/Error" } ... @lornajane

Open API Spec: Petstore Example @lornajane

Open API Spec: Petstore Example @lornajane

Tutorials Tutorials are a vitally important part of your ecosystem! • Write as many of your own tutorials as you can • Share and promote links to tutorials published elsewhere • Tutorials give developers examples they can use pieces from to build something new • Great example: https://www.twilio.com/docs/tutorials @lornajane

How The Story Ends @lornajane

From Docs to Shipping With finalised docs, the rest is easy (ish) Next steps: • Create tests (I use https://www.runscope.com/) including the documented failure behaviours • Very rapidly ship the API in the last 20% of the time this project takes! @lornajane

Resources • My book! PHP Web Services from O'Reilly • API docs post from @apievangelist http://lrnja.net/2dKwwUd • Cloudant docs source: https://github.com/cloudant-labs/slate • Contact me: [email protected] @lornajane