I’ll Take My RESTful Services Well-Done

Last decade was SOA services. This decade is REST services. These days it seems just about everyone is doing REST — but are they doing it well? From all the evidence, it seems most enterprise IT organizations are struggling with the transition from SOA to REST. And it turns out that the mobile platform is usually at the epicenter of that struggle.

Mobile App Development Readiness Review

We often perform assessments for enterprise IT organizations to help them identify areas of risk related to their mobile development practices. As part of what we call a Mobile App Development Readiness Review, we conduct a four week assessment covering everything from business and mobile strategies, through architecture and design, execution, testing, delivery, and implementation.

Whenever I conduct one of these reviews, one of the first things I look for is the health of the service layer. After all, most mobile apps can’t do much without a good backend service layer.

Taking an Inventory of the API

The question I usually start with is, “Can you provide me an inventory of your service APIs?” You might be surprised that most companies can’t do this. They can produce a bunch of APIs that are spread all over the place, documented poorly or not at all, and that typically have numerous orphans or single use services. The spaghetti has moved from the code to the service layer, and as a result, opportunities for reusing shared services are often missed — in many cases, internal consumers are not even aware of the existence of the API. The best way to avoid these kinds of problems is to build a discipline around the holistic management of the entire collection of enterprise services.

Most large enterprises currently have a mix of legacy SOA services and newer, RESTful services. I generally view the ratio of this mix is an indicator of how much progress an organization has made in modernizing their service layer.

Drilling Into the Details

Once the API inventory is complete, I begin digging into the details of selected portions of the REST service layer, looking at design, reusability, documentation, consistency, usability, and maturity level. The following are criteria we use to evaluate an organization’s REST services:

Restful Maturity

RESTful maturity was first described in a presentation by Leonard Richardson, and has become know as the Richardson Maturity Model, made famous by Martin Fowler’s article.

• Enterprises should be targeting at least Level 2 or 3 on Richardson’s Maturity Model. Anything else scores immature and represents an opportunity for improvement.
• RESTful APIs should be logical (not based on implementation details). All services should be resource-based (as opposed to RPC-like) and based on domain models that reflect the natural business partitions at an enterprise.
• RESTful service designs should always start with logical business domain models. The nouns in the model serve as the basis for naming the resources in the REST API. That doesn’t completely rule out service calls with verb-form names, but those are typically the exception rather than the rule.

Domain Modeling

Defining an enterprise-wide domain model is a perilous task. But defining domain models that map to the natural business partitions in an enterprise is both reasonable and attainable. These domain models provide the blueprint for RESTful service resource APIs. Services can be built to provide these resources on both an as-needed and client-driven basis. Services can evolve to map to these blueprints.

• RESTful services should be loosely coupled. Services APIs should never expose implementation specific details or explicitly name architectural components. Tight coupling of clients to service APIs limits the ability to make architectural changes. All APIs should remain as logical abstractions over their implementation details.
• RESTful services should be reusable by multiple clients, now and in the future. Service APIs that are capable of being used by only a single client are barely useful services — in fact, they’re really nothing more than glue code. Narrow-focused APIs miss the opportunity to vend business data and logic in a way that can meet future needs. An over-reliance on single-use services can turn an architecture into a spaghetti-like mess.
• RESTful services should be documented in a consistent way to make it easier for consumers to understand and reuse the services.

The Benefits of Well-Done RESTful Services

I’ve seen organizations that follow the above guidelines reap tremendous benefits, some of which are as follows:

1. A domain-based RESTful service layer is easier to evolve than one based on SOAP. A well-done domain model represents business concepts that have evolved over the life of the system. (Flexibility to evolve should remain one of the top architectural priorities of the RESTful service layer. Do everything possible to ensure that the service layer can change over time without breaking existing clients.)
2. A well-done RESTful service layer is easy to use and reuse, especially if it adds business value. (Do everything possible to make it easy for clients to consume the service.)
3. A well-done, domain-based RESTful service layer will reduce architectural sprawl — in other words, it will organize the spaghetti. The result should be more like manicotti — wrapped up in nice little bundles that naturally align to each other and are independently consumable.
4. A well-done service layer also makes it possible for the business, rather than the technology organization, to define which data to vend (both internally and externally) — provided the business organization works closely with IT in defining the logical domain model.

> Reverse Engineering a Domain Model

If you find yourself reverse engineering a legacy database, you’re already in trouble. One thing to pay particularly close attention to is ensuring that implementation details don’t leak into the logical domain model. Business domain modeling is hard to do well, and usually requires the skills of a trained analyst who is also adept at working with the business.

A Great Example

The FHIR (Fast Healthcare Interoperability Resources) API is a relatively new API for collecting and exchanging patient record information. It’s a great starting point if you’re looking for a good example of a well-done, domain-based, RESTful service API. The FHIR Resource Index is particularly useful as a demonstration of how a domain model can be used to clearly identify a set of related resources.