Slide 1

Slide 1 text

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

Slide 2

Slide 2 text

Starting an API Project @lornajane

Slide 3

Slide 3 text

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

Slide 4

Slide 4 text

Documentation As Communication @lornajane

Slide 5

Slide 5 text

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

Slide 6

Slide 6 text

Choosing Documentation Tools @lornajane

Slide 7

Slide 7 text

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

Slide 8

Slide 8 text

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

Slide 9

Slide 9 text

Documentation Tool: Slate @lornajane

Slide 10

Slide 10 text

Writing Great Documentation @lornajane

Slide 11

Slide 11 text

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

Slide 12

Slide 12 text

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

Slide 13

Slide 13 text

Overview Documentation @lornajane

Slide 14

Slide 14 text

Slate Markdown # ![alt tag](images/cloudantbasics_icon.png) 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

Slide 15

Slide 15 text

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

Slide 16

Slide 16 text

API Reference @lornajane

Slide 17

Slide 17 text

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

Slide 18

Slide 18 text

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

Slide 19

Slide 19 text

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

Slide 20

Slide 20 text

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

Slide 21

Slide 21 text

Open API Spec: Petstore Example @lornajane

Slide 22

Slide 22 text

Open API Spec: Petstore Example @lornajane

Slide 23

Slide 23 text

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

Slide 24

Slide 24 text

How The Story Ends @lornajane

Slide 25

Slide 25 text

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

Slide 26

Slide 26 text

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