Reusable APIs

REST API complexity is an important problem for companies building mobile applications. The tendency to build new APIs for each new project has negative consequences over time.

Adopting a REST API platform strategy with reusable and general-purpose services addresses this problem and provides many benefits in terms of more agile development and quicker time to value. In this paper I have tried to provide some of the lessons we learned about constructing reusable REST APIs while developing the DreamFactory platform — I hope this provides a useful template as your enterprise embarks on mobile application development.

# Characteristics of a Reusable API

There are some basic characteristics that any reusable REST API needs to have. The API needs to support both HTML5 and Native Mobile access patterns. Requests and responses should include JSON or XML with objects, arrays, and sub-arrays. Noun based endpoints should be automatically generated depending on the database schema. All HTTP verbs (GET, PUT, DELETE, etc.) need to be implemented for every use case. Support for web standards like OAuth, CORS, GZIP, and SSL is also important.

There needs to be a consistent URL structure for accessing any backend data source. The File Storage API should be a subset of the NoSQL API, which should be a subset of the SQL API. Parameter names should be reused across services where possible. This presents developers with a familiar interface for any data source. The API should include interactive documentation that allows developers to quickly experiment with different parameters.

In general, the structure of the request URL and associated parameters needs to be very flexible and easy to use, but also comprehensive in scope. Looking at the example below, there is a base server, an API version, the backend database, and a particular table name in the request URL string. Then the parameters specify a complex filter with a field name, operator, and value. Lastly an additional parameter sorts the returned JSON data array.

A huge number of application development scenarios can be implemented just with the filter parameter. This allows any subset of data to be identified and operated on. For example, objects in a particular date range could be loaded into a calendar interface with a filter string. Complex logical operations should also be supported. The filter string interface needs to protect against SQL Injection attacks.

The DreamFactory API platform supports operations on arrays of objects, but you can also specify related objects as a URL parameter. This allows complex documents to be downloaded from a SQL database and used immediately as a JSON object. The data can be edited along with the related objects. When committed back to the platform, all of the changes are updated including parent, child, and junction relationships. This flexibility supports a huge number of very efficient data access patterns.

The vast majority of application development use cases can be supported with a reusable REST API right out of the box. For special cases, a server-side scripting capability can be used to customize existing services or create entirely new ones. DreamFactory uses the V8 JavaScript engine for this purpose.