Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Docs-First API Design

Docs-First API Design

Avatar for Lorna Mitchell

Lorna Mitchell

October 20, 2016
Tweet

More Decks by Lorna Mitchell

Other Decks in Technology

Transcript

  1. 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
  2. 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
  3. Choosing Documentation Tools • Quick to create • Easy to

    deploy • Painless to maintain/update/evolve @lornajane
  4. 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
  5. Great Documentation Ingredients • Overview • Data format(s) and validation

    • Authentication and rate limits • Error behaviour • Pagination • Where to go for help @lornajane
  6. 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
  7. 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
  8. 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
  9. 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
  10. 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
  11. 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
  12. 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
  13. 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
  14. 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
  15. 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