An introduction to REST Coder. REST Coder is a collection of tools for auto generating client stubs and API docs for RESTful Web services. Currently REST Coder supports auto generating client stubs in Python and JS, and auto generating API docs in HTML and Sphinx.
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
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.
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.
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/
