Ben Busse, product lead at DreamFactory, explains the importance of reusable
REST APIs. This talk describes lessons learned writing one-off APIs the bad way, important characteristics of a reusable
API, and how architects and developers can use reusable APIs in practice. With mobile applications taking over the enterprise, this talk provides practical guidance for a winning API strategy.
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. Other database specific features include:
• Pagination and sorting
• Complex logical operations
• Rollback and commit
•
Role based access controls
•
Record level access controls
• Stored functions and procedures
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. Here are some of the special cases that you might want to implement with server-side scripting:
•
Custom business logic
• Workflow triggers
•
Formula fields
•
Field validation
•
Web service orchestration
Conclusion
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.
- published: 16 Jun 2015
- views: 14214