Snow Crash - The API Blueprint Parser

Cb2527e0c321fc1eb6753c06f45da93c?s=47 Z
April 24, 2014

Snow Crash - The API Blueprint Parser

Pyvo, Brno, Czech Republic April 2014

Cb2527e0c321fc1eb6753c06f45da93c?s=128

Z

April 24, 2014
Tweet

Transcript

  1. SNOW CRASH API Blueprint Parser Zdenek Nemec – @zdne Apiary.io

  2. SNOW CRASH ! • Language • Parser • Project &

    Users • What didn’t work out
  3. API BLUEPRINT

  4. API BLUEPRINT • Documentation oriented Web API description language •

    2 verions: • 1.0: cURL-like HTTP transcription (a.k.a. Legacy format) • 2.0(1A): Markdown (a.k.a. New format)
  5. Mock > Use > Implement Documentation Automated testing

  6. LEGACY (1.0) HOST: http://www.google.com/ --- Sample API v2 --- ---

    Welcome to our API. Comments support [Markdown](http://daringfireball.net/projects/markdown/ syntax) syntax --- ! -- Shopping Cart Resources -- ! List products in your shopping cart. Contains product IDs, quantity and other useful informations. GET /shopping-cart > Accept: application/json < 200 < Content-Type: application/json { "items": [ { "url": "/shopping-cart/1", "product":"2ZY48XPZ", "quantity": 1, "name": "New socks", "price": 1.25 } ] }
  7. LEGACY (1.0) • PEG grammar • PEG.JS parser • Simplicity,

    just need to write the grammar • Works on the client side • Limited support for error handling & reporting
  8. NEW FORMAT (1A) HOST: http://www.google.com/ # Sample API v2 Welcome

    to our API. Comments support [Markdown](http://daringfireball.net/projects/markdown/ syntax) syntax ! ## GET /shopping-cart List products in your shopping cart. Contains product IDs, quantity and other useful informations. ! + Response 200 (application/json) { "items": [ { "url": "/shopping-cart/1", "product":"2ZY48XPZ", "quantity": 1, "name": "New socks", "price": 1.25 } ] }
  9. NEW FORMAT (1A) • Plain Markdown • Couple of semantic

    assumptions over the plain Markdown • Used by GitHub, Stack Overflow, ZenDesk … • Rich error handling & reporting support
  10. PARSER

  11. TECHNOLOGY

  12. C++11 “A light-weight abstraction programming language”

  13. None
  14. C++11 • Reasons: • Platform independence vs. language-agnostic • Underlaying

    “standard” library for Markdown parsing • C++11 is really cutting edge language… • … maybe too much … • Very limited support on Linux / GCC at the time of writing
  15. GYP • Generate Your (own) Project • Makefile replacement (Makefile

    generator) • Python + JSON
  16. ARCHITECTURE

  17. Markdown Parser Blueprint Parser API Blueprint Markdown AST Blueprint AST

    AST Serialization JS / Python / Ruby / .NET Sundown AST Renderer
  18. SUNDOWN • The search for a standard Markdown parser •

    Sundown (C) - deprecated • Redcarpet (RUBY / C) - used by GH, pretty terrible • Hoedown (C) - aspiring standard Markdown parser
  19. AST

  20. AST • Markdown AST (stack, C++) • Blueprint AST (tree,

    C++) • Blueprint AST serialization • vnd.apiblueprint.ast.raw+json • vnd.apiblueprint.ast.raw+yaml
  21. PROJECT & USERS

  22. CHALLENGES • Language • Language design (Markdown limitations) • On-boarding

    a documentation • Maintenance & Support • Planning & future development • Parser • Who are the parser users? • What is the parser output? • Maintenance & Support • Planning & future development • How to handle deprecated syntax?
  23. OPEN

  24. OPEN as in OpenSSL

  25. OPEN SOURCE PROJECT

  26. OPEN SOURCE • GitHub projects: • API Blueprint specification •

    Snow Crash • AST serialization format • + bindings to other languages • GitHub Issues • Stack Overflow • Google Groups • Email • Twitter • Apiary support
  27. PARSER USERS • Two different groups: • Writers of API

    blueprints • Developers of tools relying on API Blueprint • Two different parser outputs: • For writers during writing (warnings & errors) • For tools using the API Blueprint (AST)
  28. WRITING A BLUEPRINT • How and where is a blueprint

    written? • How to communicate syntax errors and semantics warnings? • What to communicate? • “OMG ME EXPLODE” vs. “Print the specification”? • Source Maps • Inspired by LLVM/CLANG error reporting !
  29. WRITING A BLUEPRINT

  30. SOURCE MAPS • Line number is not enough • Best

    to pinpoint complete blocks of source code • Character index:offset (:72:2;78:2) • Mind bytes vs characters
  31. DEVELOPING FOR API BLUEPRINT • Seemingly many ASTs • C++

    AST from the parser • AST serialization • + language-specific binding AST • AST is contract with API Blueprint tools developers • Challenge: • Specific AST tailored for a particular tool • Generic AST 1:1 capturing the source blueprint • Closed vs. Open Source
  32. GENERIC & SPECIFIC AST Blueprint Parser Blueprint AST Parser Harness

    Blueprint Parser Blueprint AST Composite AST
  33. WHAT DIDN'T WORK OUT

  34. WHAT DIDN’T WORK OUT • In the beginnings I have

    forget about blueprint writers • Had to add implementation Source Maps after hand • Suboptimal Markdown AST (stack vs. tree) • The language itself is still under documented • Still looking for great C++ developers
  35. Q&A

  36. REFERENCE • Apiary – http://apiary.io • API Blueprint – http://apiblueprint.org

    • Snow Crash – http://github.com/apiaryio/snowcrash • C++11Style – http://channel9.msdn.com/Events/ GoingNative/GoingNative-2012/Keynote-Bjarne-Stroustrup- Cpp11-Style