Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
A	
  Quick	
  Introduc.on	
  
About  me
API	
  Documenta.on	
  Meetup	
  2016,	
  London	
  
•  European	
  Ci.zen	
  
•  Technology	
  =	
  Love	
  
• ...
Remember?
API	
  Documenta.on	
  Meetup	
  2016,	
  London	
  
Bo.om-­‐up
API	
  Documenta.on	
  Meetup	
  2016,	
  London	
  
Top-­‐down
API	
  Documenta.on	
  Meetup	
  2016,	
  London	
  
Specifica(on	
  
Today?
API	
  Documenta.on	
  Meetup	
  2016,	
  London	
  
Pure	
  
documents	
  
BoRom	
  
up	
  
Top	
  
down	
  
Make  Your  Choice
API	
  Documenta.on	
  Meetup	
  2016,	
  London	
  
and	
  more	
  
RAML	
  
API	
  Design	
  First	
  
RAML
API	
  Documenta.on	
  Meetup	
  2016,	
  London	
  
A new open spec
for RESTful APIs
that's as clean
and as structur...
RAML:  Human  Readable
API	
  Documenta.on	
  Meetup	
  2016,	
  London	
  
Choose  your  format!
API	
  Documenta.on	
  Meetup	
  2016,	
  London	
  
API	
  
Console	
  
Choose  your  format!
API	
  Documenta.on	
  Meetup	
  2016,	
  London	
  
Slate	
  
Choose  your  format!
API	
  Documenta.on	
  Meetup	
  2016,	
  London	
  
HTML	
  
PDF	
  
Word	
  
or	
  others	
  
RAML	
  
Write	
  once.	
  	
  Use	
  many.	
  	
  Crea.ve	
  laziness	
  encouraged.	
  
RAML:  Common  Pa.erns
API	
  Documenta.on	
  Meetup	
  2016,	
  London	
  
Resource Types
•  Collection
•  Collection Mem...
RAML:  Common  Pa.erns
API	
  Documenta.on	
  Meetup	
  2016,	
  London	
  
resource type
schema
trait
 
RAML	
  1.0	
  
WHAT’S	
  NEW	
  
Data	
  Models	
  
complex	
  schemas	
  and	
  examples	
  become	
  simply	
  typed	
  models	
  that	
  can	
  be	
  
u...
Data	
  Models	
  
	
  
data	
  models	
  are	
  easily	
  pulled	
  in	
  to	
  
other	
  models,	
  used	
  as	
  schema...
Libraries	
  
resourceTypes,	
  traits,	
  schemas,	
  examples,	
  data	
  types	
  (models),	
  and	
  more	
  
can	
  a...
Overlays	
  
your	
  API	
  doesn’t	
  just	
  live	
  in	
  one	
  environment,	
  so	
  neither	
  should	
  your	
  
de...
Annota.ons	
  
vendor	
  extensions	
  shouldn’t	
  be	
  a	
  pain,	
  and	
  in	
  RAML	
  –	
  they’re	
  just	
  “new”...
And	
  a	
  lot	
  more…	
  	
  
Plus+	
  
API	
  Workbench	
  
a	
  brand	
  new	
  IDE	
  to	
  design	
  APIs	
  online	
  AND	
  offline,	
  built	
  on	
  top	
  ...
What  else?
API	
  Documenta.on	
  Meetup	
  2016,	
  London	
  
#	
  of	
  downloads	
  
API	
  Workbench	
  
13.7k	
  
#...
RAML.org	
  
APIWorkbench.com	
  
@ramlapi	
  
raml-­‐org/raml-­‐spec	
  
API	
  Documenta.on	
  Meetup	
  2016,	
  London...
API Documentation Meetup 2016, London
API Documentation Meetup 2016, London
Upcoming SlideShare
Loading in …5
×

API Documentation Meetup 2016, London

288 views

Published on

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

Published in: Software
  • Be the first to comment

API Documentation Meetup 2016, London

  1. 1. A  Quick  Introduc.on  
  2. 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. 3. Remember? API  Documenta.on  Meetup  2016,  London  
  4. 4. Bo.om-­‐up API  Documenta.on  Meetup  2016,  London  
  5. 5. Top-­‐down API  Documenta.on  Meetup  2016,  London   Specifica(on  
  6. 6. Today? API  Documenta.on  Meetup  2016,  London   Pure   documents   BoRom   up   Top   down  
  7. 7. Make  Your  Choice API  Documenta.on  Meetup  2016,  London   and  more  
  8. 8. RAML   API  Design  First  
  9. 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. 10. RAML:  Human  Readable API  Documenta.on  Meetup  2016,  London  
  11. 11. Choose  your  format! API  Documenta.on  Meetup  2016,  London   API   Console  
  12. 12. Choose  your  format! API  Documenta.on  Meetup  2016,  London   Slate  
  13. 13. Choose  your  format! API  Documenta.on  Meetup  2016,  London   HTML   PDF   Word   or  others  
  14. 14. RAML   Write  once.    Use  many.    Crea.ve  laziness  encouraged.  
  15. 15. RAML:  Common  Pa.erns API  Documenta.on  Meetup  2016,  London   Resource Types •  Collection •  Collection Member •  Document Traits •  Secure •  Paged Define Share Reuse
  16. 16. RAML:  Common  Pa.erns API  Documenta.on  Meetup  2016,  London   resource type schema trait
  17. 17.   RAML  1.0   WHAT’S  NEW  
  18. 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. 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. 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. 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. 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. 23. And  a  lot  more…    
  24. 24. Plus+  
  25. 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  
  26. 26. What  else? API  Documenta.on  Meetup  2016,  London   #  of  downloads   API  Workbench   13.7k   #  of  project   views   750k  
  27. 27. RAML.org   APIWorkbench.com   @ramlapi   raml-­‐org/raml-­‐spec   API  Documenta.on  Meetup  2016,  London  

×