Snow Crash - The API Blueprint Parser

Pyvo, Brno, Czech Republic April 2014

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”
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