REST Coder: Auto Generating Client Stubs and Documentation for REST APIs
- 1. REST Coder Auto Generating Client Stubs and Documentation for RESTful Services Hiranya Jayathilaka & Stratos Dimopoulos CS263 - Spring 2013 S
- 2. What to Expect S SOA, Web Services and APIs S The REST ecosystem – Machine readable API descriptions for REST S Introduction to REST Coder – Tools and architecture S Live Demos S Challenges and Future Work
- 3. Service Oriented Architecture S An architectural paradigm and a way of thinking about designing software systems. S A system is a structured collection of highly reusable modules known as services. S Language and platform neutral implementation model.
- 4. Services and APIs S Service S Meant to be combined with other services to build useful applications. S Has a well defined interface (contract). S API S The visible interface of a service.
- 5. SOAP vs. REST SOAP REST Governed by a collection of W3C and OASIS standards A collection of ideas from Roy Fielding’s Ph.D. dissertation Standard message formats, standard APIs, standard everything Flexible Heavyweight – Need a lot of code Lightweight – Just need some HTTP API support Slow – Consumes resources Fast – Conservative Decaying popularity Everybody loves REST
- 6. REST in Peace SOAP!
- 7. Service/API Ecosystem for REST Ecosystem Feature State-of-the-Art Service development Mature Lifecycle management Emerging Subscription management, SLA enforcement and monitoring Emerging Machine readable API descriptions No widely accepted standards API documentation Manual API discovery Manual API consumption Manual Automated reasoning Existing methods too complex for widespread use
- 8. Our Approach S A simple, structured, machine-readable API description language. S A collection of tools for auto-generating and processing API descriptions. S Automated API discovery and engagement S Automated API consumption S Automated API doc generation S Automated reasoning about APIs
- 9. API Description Language S Simple, structured language based on JSON S Captures – S Functional properties (resources, operations, security constraints etc.) S Data models (simple structured type system inspired by Thrift) S Non-functional properties (licensing information, SLA details, ownership details etc.)
- 10. REST Coder S A set of tools for auto generating API docs and client stubs from a given API description. S Three main components/tools. S HTML/JavaScript code generator S Sphinx API doc generator S Python client stub generator
- 11. HTML/JS Code Generator S Given an input API description, generates a set of API docs in HTML format. S Augments HTML-based API docs with JS/JQuery code to invoke the remote API on-line.
- 12. System Architecture JSON Description Code Generator (Java/Velocity) API Documentation/ Client (HTML/JQuery) Reverse Proxy (NodeJS / Express) REST API (Tomcat)
- 13. Sphinx API Doc Generator S Given an input API description, generates a collection of reStructred text (.rst) files and compiles them using Sphinx. S Generates an index page and a separate page for each resource and user-defined data type in the API description. S Automatically creates links between pages to provide easy navigation between related topics.
- 14. Python Client Stub Generator S Given an input API description, generates a Python (2.7) module that can be used as a client stub (proxy) to consume the API. S Useful in developing desktop apps, command-line tools, webapps and mashups in Python. S Generates a separate Python class for each resource in the API description. S Convert API docs into Python docstrings.
- 15. Challenges S Recursive type system is easy to understand but complex to generate code for. S Required vs. optional parameters. S Avoiding the generation of boilerplate code – Reusing generated code. S Handling different media types. S Managing symbols and identifiers during the code generation. S Handling incomplete API descriptions. S Cross-site API calls in JavaScript (Same origin policy)
- 16. Future Work S Auto generating code for secured (OAuth, BasicAuth) APIs. S Auto generating test cases. S Generating code that validates/enforces documented API pre-conditions and post-conditions (contracts). S Support for more media types. S Auto generating entire apps/mashups.
- 17. Questions?
- 18. References S M. Maleshkova, C. Pedrinaci, and J. Domingue, “Investigating Web APIs on the World Wide Web”, European Conference on Web Services (ECOWS) S D. Bianchini, V. De Antonellis, and M. Melchiori, “Semantics-enabled web APIs selection pattern”, In Proceedings of the 15th Symposium on International Database Engineering & Applications (IDEAS '11) S Jacek Kopecký, Karthik Gomadam, and Tomas Vitvar. 2008, “hRESTS: An HTML Microformat for Describing RESTful Web Services” In Proceedings of the 2008 IEEE/WIC/ACM International Conference on Web Intelligence and Intelligent Agent Technology S WADL - http://www.w3.org/Submission/wadl/ S Swagger - https://developers.helloreverb.com/swagger/