Slide 1

Slide 1 text

Building Better APIs: Documentation API Blueprint – Dredd – Apiary

Slide 2

Slide 2 text

An API is only as good as its documentation.

Slide 3

Slide 3 text

Common Challenges

Slide 4

Slide 4 text

No Documentation

Slide 5

Slide 5 text

Disparate Documentation and Functionality

Slide 6

Slide 6 text

Development is blocked by API readiness

Slide 7

Slide 7 text

Not knowing what/when API changed

Slide 8

Slide 8 text

Documentation First Approach Think of it like TDD for APIs

Slide 9

Slide 9 text

Slow down; plan your API

Slide 10

Slide 10 text

Write good documentation

Slide 11

Slide 11 text

Test code against documentation

Slide 12

Slide 12 text

Provide mocks for Developers

Slide 13

Slide 13 text

Tools

Slide 14

Slide 14 text

API Blueprint Documentation Syntax

Slide 15

Slide 15 text

No content

Slide 16

Slide 16 text

MSON Markdown Syntax for Object Notation

Slide 17

Slide 17 text

No content

Slide 18

Slide 18 text

JSON MSON

Slide 19

Slide 19 text

No content

Slide 20

Slide 20 text

Dredd API Testing Utility $ dredd ./apiary.apib 'http://localhost:3000'

Slide 21

Slide 21 text

Apiary Hosted Documentation, Mock Server, Test/Traffic Inspector

Slide 22

Slide 22 text

No content

Slide 23

Slide 23 text

No content

Slide 24

Slide 24 text

No content

Slide 25

Slide 25 text

Demo

Slide 26

Slide 26 text

Resources

Slide 27

Slide 27 text

API Blueprint
 https://apiblueprint.org Dredd
 http://dredd.rtfd.org Apiary
 https://apiary.io Slides
 https://speakerdeck.com/galenandrew/building-better-apis Example Documentation
 http://docs.dialexastarterapi.apiary.io General

Slide 28

Slide 28 text

API Blueprint Examples
 https://github.com/apiaryio/api-blueprint/tree/master/examples MSON Tutorial
 https://apiblueprint.org/documentation/mson/tutorial.html MSON Examples
 https://github.com/apiaryio/mson/tree/master/examples API Blueprint

Slide 29

Slide 29 text

Hooks
 https://dredd.readthedocs.io/en/latest/hooks/ Response 204 Bug
 https://github.com/apiaryio/dredd/issues/468#issuecomment-218130203 Dredd

Slide 30

Slide 30 text

Apiary CLI
 https://help.apiary.io/tools/apiary-cli/ Enhancing Apiary Workflow
 https://help.apiary.io/api_101/enhancing-apiary-workflow/ Apiary

Slide 31

Slide 31 text

Thank you!