In general, this presentation is about API Documentation plus a quick introduction to RAML and it's new version 1.0.

1. A
Quick
Introduc.on

2. About me
API
Documenta.on
Meetup
2016,
London
• European
Ci.zen
• Technology
=
Love
• Developer
• Sporty
(at
least
some.mes)
• Not
a
Brit
• and
more
…
Chris.an
Vogel
Community
PM
/
Evangelist
MulesoO
@Chris.anVogel_

3. Remember?
API
Documenta.on
Meetup
2016,
London

4. Bo.om-­‐up
API
Documenta.on
Meetup
2016,
London

5. Top-­‐down
API
Documenta.on
Meetup
2016,
London
Specifica(on

6. Today?
API
Documenta.on
Meetup
2016,
London
Pure
documents
BoRom
up
Top
down

7. Make Your Choice
API
Documenta.on
Meetup
2016,
London
and
more

8. RAML
API
Design
First

9. RAML
API
Documenta.on
Meetup
2016,
London
A new open spec
for RESTful APIs
that's as clean
and as structured
as REST itself
RESTful API Modeling Language
the RAML Workgroup:
raml.org

10. RAML: Human Readable
API
Documenta.on
Meetup
2016,
London

11. Choose your format!
API
Documenta.on
Meetup
2016,
London
API
Console

12. Choose your format!
API
Documenta.on
Meetup
2016,
London
Slate

13. Choose your format!
API
Documenta.on
Meetup
2016,
London
HTML
PDF
Word
or
others

14. RAML
Write
once.
Use
many.
Crea.ve
laziness
encouraged.

15. RAML: Common Pa.erns
API
Documenta.on
Meetup
2016,
London
Resource Types
• Collection
• Collection Member
• Document
Traits
• Secure
• Paged
Define Share Reuse

16. RAML: Common Pa.erns
API
Documenta.on
Meetup
2016,
London
resource type
schema
trait

17.
RAML
1.0
WHAT’S
NEW

18. Data
Models
complex
schemas
and
examples
become
simply
typed
models
that
can
be
used
for
code
genera.on,
clear
interpreta.on,
example
genera.on,
and
yes
–
even
mul.-­‐format
schema
genera.on.
OR
API
Documenta.on
Meetup
2016,
London

19. Data
Models
data
models
are
easily
pulled
in
to
other
models,
used
as
schemas/
examples,
and
can
even
be
stored
in
libraries
and
namespaced!
API
Documenta.on
Meetup
2016,
London

20. Libraries
resourceTypes,
traits,
schemas,
examples,
data
types
(models),
and
more
can
all
be
stored
in
libraries,
which
can
then
be
pulled
into
the
RAML
spec
in
a
namespaced
format
–
leang
you
reuse
what
you
want,
and
ignore
what
you
don’t.
API
Documenta.on
Meetup
2016,
London

21. Overlays
your
API
doesn’t
just
live
in
one
environment,
so
neither
should
your
design,
documenta.on,
or
tests.
Overlays
let
you
“extend”
your
RAML
spec
for
your
development,
QA,
and
produc.on
environments.
Original
Spec
Overlay
seang
Produc.on
Values
API
Documenta.on
Meetup
2016,
London

22. Annota.ons
vendor
extensions
shouldn’t
be
a
pain,
and
in
RAML
–
they’re
just
“new”
proper.es
in
your
spec.
Plus
you
can
use
libraries
and
overlays
to
keep
annota.ons
separate
from
your
main
spec,
meaning
they
are
only
visible
to
the
vendor
you
want
using
them,
and
out
of
the
way
of
your
developers/
tech
writers/
CEO!
API
Documenta.on
Meetup
2016,
London

23. And
a
lot
more…

24. Plus+

25. API
Workbench
a
brand
new
IDE
to
design
APIs
online
AND
offline,
built
on
top
of
GitHub’s
Atom
project,
meaning
collabora.on
and
versioning
have
never
been
easier!
Finally,
a
tool
for
developers
to
design
APIs
with!
API
Documenta.on
Meetup
2016,
London

28. What else?
API
Documenta.on
Meetup
2016,
London
#
of
downloads
API
Workbench
13.7k
#
of
project
views
750k

29. RAML.org
APIWorkbench.com
@ramlapi
raml-­‐org/raml-­‐spec
API
Documenta.on
Meetup
2016,
London