RestExpress API Application Layers

Here’s a quickie video describing the application layers of a RestExpress application when one of the Maven Archetypes is used to create a new RestExpress project.

To summarize: Visibility or “awareness” goes down. Meaning that a layer can call (or know about) the layer immediately below it, but an application layer cannot call the layer above it or a layer deeper than the next immediately lower. In other words, if there’s database orchestration code in the Service Layer or Controller, that’s poor design. And conversely, if there’s HTTP header, request or response manipulation in the ServiceLayer or Persistence Layer, that’d be bad.

Layer #1: Controller/HTTP Layer

HTTP layer where requests, headers and responses are manipulated and processed.
Handles serialization of request body to domain model.
And deserialization from domain model to response.
Makes call to only the Service Layer (layer #2).

Layer #2: Service Layer

Business logic.
Calls methods on domain model to orchestrate business logic and domain functionality.
Calls Persistence Layer to store and read domain model instances.
Returns domain model instances to the Controller/ HTTP Layer.

Layer #3: Persistence Layer

Sometimes call DAL (data access layer) or DAO (data accessor object).
Called Repository by Eric Evans in his Domain Driven Design (DDD) book.
Creates an interface to perform queries and database operations.
“Serializes” and “deserializes” domain model instances to/from the database.

RestExpress Still Top Performing MongoDB REST Framework

Benchmark results Round six of the TechEmpower.com Web Framework benchmarks were published on July 2, 2013, which show RestExpress 0.9.2 as still the best performing REST Framework against MongoDB (2.2.4) for single-query, CRUD-style operations. At 63,209 responses per second on an i7-2600K (with 8GB memory) and 7,547 responses per second on an AWS EC2 m1.large instance, it ranked 10th and 11th respectively, overall. But was the highest-ranked framework using MongoDB as it’s back-end store.

Another test, which makes 20 queries per request, showed RestExpress to also rank well for MongoDB-backed services, ranking top the list for EC2 and second only to NodeJS on the i7.

As RestExpress 0.9.2 is using Netty 3.6.x, it’s conceivable that there will be significant performance increases realized when the upgrade to Netty 4.0.x is completed. But the performance numbers are still very encouraging.

Read the full report here… http://www.techempower.com/benchmarks/

What to Use as Identifiers (IDs) in REST APIs

TIP: Publicly exposed identifiers (IDs), such as those exposed in your RESTful URLs, should not expose underlying technology. And in most cases, should not contain business meaning.

For a long time it’s been good practice to ensure that primary keys in your database tables do not contain business semantics so that it doesn’t change when the business meaning changes. We’ve all seen the cases where either SSN, phone number, or email address utilized as a primary key turns out to be a bad choice.

If you’re familiar with this practice, then it’s not news to you that IDs exposed in REST APIs generally have the same rules–a URL is supposed to uniquely identify a resource and not change over time.

The Problem

The catch is that often we end up exposing our underlying technology in those identifiers. Consider the case where we have a URL like /users/12345, where the 12345 is a user identifier. Is that the underlying database column, perhaps MySQL, where the user_id column is a long or AUTOSEQUENCE? Problemo when you reimplement your user resources in MongoDB and decide to use the MongoDB ObjectID which looks something like 4e20885deabfa3a2586b5fb1.

Even more subtle is when we expose a mixture of some MySQL tables, MongoDB documents, Cassandra keyspaces, or Redis objects and expose their IDs in URLs. Your RESTful APIs can look quite cluttered and be confusing to your consumers.

The Proposal

Nearly all databases, whether NoSQL or relational, now support the concept of a UUID (universally-unique identifier). It is a 16-byte (128-bit) binary representation, when displayed as a string is 32 hexadecimal digits, displayed in five groups separated by hyphens for a total of 36 characters (32 alphanumeric characters plus four hyphens). For example (see the wikipedia link above for more detail):

550e8400-e29b-41d4-a716-446655440000

While those 36 characters are cumbersome to type, using a Type 4 (random) UUID as primary keys, row keys, etc. in databases makes things appear much more cohesive where unique identifiers are exposed in your RESTful APIs. And besides, most of the time the ID is simply used by a JavaScript or other consumer that doesn’t care how long the IDs are in your URL.

One More Thing

Don’t like all those characters and hyphens in your URL? Well, you can Base64 encode your UUIDs before displaying them in URLs and Base64 decode them on the way back in–except that Base64 is not URL safe! So you have to either URL encode/decode them or use a URL-safe Base64 encoder/decoder (like that available in RestExpress’s own RepoExpress UuidConverter). This will get your UUIDs down to 22 characters instead of the normal 36.

Recommendation: IDs generated by an API are in the form of web-safe, base64-encoded UUIDs, which are 22 characters in length. For example, “abcdEFh4520juieUKHWgJQ” instead of “550e8400-e29b-41d4-a716-446655440000.”

Feedback? What are your thoughts and experiences. Please offer your comments below…

Instant REST Services with RESTExpress Q&A

This is a follow-on to my last two posts, Introduction to REST (Revisited) and RESTExpress Overview and Tutorial, with this short video being the Q&A after the presentation. In it, the video talks about authentication, authorization, and some of the RESTExpress features around sorting, filtering and performance. It’s a quickie, but it’s always nice to understand what others are asking… and some answers to those questions.

[youtube http://youtu.be/z5u4rZTK8o0]

RESTExpress Overview and Tutorial

In my last post, Intro to REST (Revisited), as well as discussing the six constraints of the REST architectural style, the video discussed the background for the Java Rest Service Framework, RESTExpress and introduces a sample project. The video below is part two of the presentation, where we dive in and create a real, working service suite using RESTExpress around a blogging system that uses MongoDB for its back-end store. The reference implementation demo’d during the presentation is available on GitHub and supports linking, pagination, filtering and sorting of collection results returned (for blogs, entries, and comments).

This video goes into a bit of depth on how all that gets accomplished in your service suites with a minimum of coding.

[youtube http://youtu.be/hHDO6soGehc]

If you haven’t heard, RESTExpress is a lightweight micro-framework (along with some other micro-frameworks) that support rapid development of highly scalable, high performance REST services supporting JSON and XML payloads. It is an active open source project that is gaining momentum. You can get more information at the resources below: