I’ll Take My RESTful Services Well-Done

Leroy Mattingly


4 min read
A photograph of well done steak on a plate

Mobile App Development Readiness Review

Taking an Inventory of the API

Drilling Into the Details

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.

A table with information about RESTful maturity
  • 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.

Newsletter Form
  • Where the future is going: sniffing out all of Apple’s clues
    Where the future is going: sniffing out all of Apple’s clues
    See more: Where the future is going: sniffing out all of Apple’s clues
    Small orange arrow symbol
  • Consider the Following – Part 2
    Consider the Following – Part 2
    See more: Consider the Following – Part 2
    Small orange arrow symbol
Abstract graffiti-style artwork with vivid colors and dynamic shapes.
Simple Form

Connect with our team.


An error has occured, please try again.

Try again