Building Better APIs: Documentation

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/Traﬃc 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 Workﬂow  https://help.apiary.io/api_101/enhancing-apiary-workﬂow/ Apiary

Slide 31

Slide 31 text

Thank you!