Building Reusable REST API Services (Part 3 of 4) | Dreamfactory

Table of contents

My first post in this series of four discussed the problems and pitfalls of creating your own REST APIs. After that we looked at some of the ineffective ways that companies try to deal with the API complexity problem. Now, I want to talk about the advantages of reusable web services for general-purpose application development.


The Possible Dream 

Wait up for a second: how do we know it’s even possible to build a reusable REST API platform in the first place? Our company has always built new services for each new project. That’s how we have to do it, right?

Think for a moment about ODBC and JDBC. These are the programmer interfaces that connect PHP and Java to SQL; they are used widely and are almost never modified for a particular project. This is a good example of a general-purpose interface for a complex back-end database. What if someone wrote a comprehensive REST API for any back-end data source or external service?

Consider the platform libraries on Microsoft Windows and Apple OS X that are designed for application development. These are APIs that support a huge number of development scenarios. There might be some application that can’t be written because of a missing API, but this is a rare situation compared to the long tail of applications that are written every day for Mac and Windows.

Now, the old-timers in the audience might think this is related to Service-Oriented Architecture. But there’s a difference: SOA is primarily used for server-side integration and usually requires a big software development effort. Ask modern developers what they think about SOA, and they will tell you, “I love that show!” In other words, SOA wasn’t designed for the new world of mobile applications. We need to combine SOA capabilities with re-usable back-end services delivery to address the needs of modern developers.

Reusable and Flexible Interfaces, Done Right

Reusable interfaces need to be flexible by design. For example, filter string parameters should enable a developer to dynamically query any SQL database or NoSQL document store. The service should support arrays of objects and related objects returned in the same transaction. This supports a huge number of access patterns “out of the box” without the need for further customization.

The services also need to cover many different usage scenarios in a comprehensive manner. Just considering the SQL interface, we need support for record-level access control, rollback and commit, data pagination, download limits, array sorting, metadata operations, schema discovery, and SQL views. There are ANSI corner cases —such as date and time formats, and stored procedures— that need to be handled in a consistent manner across different types of SQL databases.

Special cases need to be supported in an organized fashion. A server-side scripting and customization engine should modify requests and responses to handle formula fields, workflow triggers, special access controls, field validation, and custom usage limitations. The scripting engine can be used to implement custom services when necessary. Access to external web services is another way to extend the functionality of a reusable REST API services platform.


Making Comprehensive and Reusable APIs Work for You

Everything changes when a company adopts a strategy based on comprehensive and reusable interfaces. System administrators set up the back-end infrastructure and specify user access rights, and then application designers can safely build anything they want on top of that platform. This “decouples” client-side application development from server-side security, user management, and administration.

Client-side developers can use the same REST API for each new project. They can now tap into a universal data access layer to power their applications — the back-end work is already taken care of for them. They might use different parameters or data objects, but the programming style is the same. A well-designed API can also minimize the differences between SQL, NoSQL, and file storage. Add filter string to file storage and you get NoSQL. Add object enforcement and metadata to NoSQL and you get SQL. Consistent and well-designed services provide a much easier way to learn the API and write applications.

The applications written on a service platform also benefit from the virtualization provided by the service layer. Services are no longer tied to specific pieces of backend infrastructure. Moving an application from development to testing and on to production is easy. The service platform can be installed anywhere, so applications can be moved between clouds and data centers with ease.

A Reusable Conclusion

In this blog post, I have tried to explain why using a comprehensive REST API platform is much better than developing your own web services for each new project. The advantages are profound for server-side administrators, client-side developers, the applications that are written, and the company as a whole. My next blog post will expand on the target area a little, and look at the peripheral issues surrounding REST API platforms.

I’d like to hear from you developers and enterprise architects out there. How would you apply this approach in your environment? What do you think are the pros, cons, and possibilities of a reusable REST API platform?

Read part 4 of 4 in this series, "A REST API is Not Enough for Mobile App Integration."