S

REST CoderAuto Generating Client Stubs and Documentation for RESTful Services

Hiranya Jayathilaka & Stratos DimopoulosCS263 - Spring 2013

What to Expect

SOA, Web Services and APIs

The REST ecosystem – Machine readable API descriptions for REST

Introduction to REST Coder – Tools and architecture

Live Demos

Challenges and Future Work

Service Oriented Architecture

An architectural paradigm and a way of thinking about designing software systems.

A system is a structured collection of highly reusable modules known as services.

Language and platform neutral implementation model.

Services and APIs

Service Meant to be combined with other services to build

useful applications. Has a well defined interface (contract).

API The visible interface of a service.

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

REST in Peace SOAP!

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

Our Approach

A simple, structured, machine-readable API description language.

A collection of tools for auto-generating and processing API descriptions. Automated API discovery and engagement Automated API consumption Automated API doc generation Automated reasoning about APIs

API Description Language

Simple, structured language based on JSON

Captures – Functional properties (resources, operations, security

constraints etc.) Data models (simple structured type system inspired

by Thrift) Non-functional properties (licensing information, SLA

details, ownership details etc.)

REST Coder

A set of tools for auto generating API docs and client stubs from a given API description.

Three main components/tools. HTML/JavaScript code generator Sphinx API doc generator Python client stub generator

HTML/JS Code Generator

Given an input API description, generates a set of API docs in HTML format.

Augments HTML-based API docs with JS/JQuery code to invoke the remote API on-line.

System Architecture

Code Generator(Java/Velocity)

JSON Description

API Documentation/ Client

(HTML/JQuery)

Reverse Proxy(NodeJS / Express)

REST API(Tomcat)

Sphinx API Doc Generator

Given an input API description, generates a collection of reStructred text (.rst) files and compiles them using Sphinx.

Generates an index page and a separate page for each resource and user-defined data type in the API description.

Automatically creates links between pages to provide easy navigation between related topics.

Python Client Stub Generator

Given an input API description, generates a Python (2.7) module that can be used as a client stub (proxy) to consume the API. Useful in developing desktop apps, command-line

tools, webapps and mashups in Python.

Generates a separate Python class for each resource in the API description.

Convert API docs into Python docstrings.

Challenges

Recursive type system is easy to understand but complex to generate code for.

Required vs. optional parameters.

Avoiding the generation of boilerplate code – Reusing generated code.

Handling different media types.

Managing symbols and identifiers during the code generation.

Handling incomplete API descriptions.

Cross-site API calls in JavaScript (Same origin policy)

Future Work

Auto generating code for secured (OAuth, BasicAuth) APIs.

Auto generating test cases.

Generating code that validates/enforces documented API pre-conditions and post-conditions (contracts).

Support for more media types.

Auto generating entire apps/mashups.

Questions?

References

M. Maleshkova, C. Pedrinaci, and J. Domingue, “Investigating Web APIs on the World Wide Web”, European Conference on Web Services (ECOWS)

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)

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

WADL - http://www.w3.org/Submission/wadl/

Swagger - https://developers.helloreverb.com/swagger/