REST API Design – Using Data Transfer Objects vs Exposing Complex Data Models

Architecturedesignlanguage-agnosticrest

We are working on an MVVM application. Jersey (backend) exposing a REST interface and AngularJS (frontend) being the only consumer of this interface. The application uses a complex database model (data model), which is different from the model presented to the user in the browser (view model).

Currently we have came across the following dilemma:

to introduce Data Transfer Object (DTO) classes that will contain all the required attributes to invoke complex business logic operations on our model
expose the existing complex data model without introducing DTO classes

Approach 1 will allow to simply the clients of the REST interface, as they will not have to understand the data model and will only have to provide the values of all the required attributes in the DTO classes. However, this approach requires an introduction of a mapping layer in the backend, from/to the data model to/from the view model.

Approach 2 results in less code in the backend, but will probably make the code in the frontend more complex as it will have to do the mapping of user input to the existing data model.

From the REST design perspective approach 2 seems to be better, but is exposing the data model in REST always the best solution?

Best Answer

expose the existing complex data model without introducing DTO classes

One major flaw of this approach is that of coupling data access layer with API. It can go very bad very quickly if those models are used elsewhere except API. I currently work on a project where both web interface and JSON API (kind of REST, but not quite) use the same Hibernate entities - it is fragile, since every change in one place affects the other. Reusability just doesn't work this way, I guess.

Sometimes you just have to have DTOs when models just don't fit into API. For example, if you have some tricky validation rules or some data you want to hide from API clients. You can go nuts with annotations, and yet it will not always work.

I also work on other project which also have both JSON API and web interface, but API uses it's own data access layer (jOOQ). It works fine, despite the fact there are two ways to access the data. It's just easier to write custom queries for API and fill the data into DTOs to begin with than to have some layer of "transformers" from data entities to DTOs. It also works much faster than any ORM and eliminates the whole class of problems related to lazy fetching and "Open Session/EntityManager in View" pattern.

So, I recommend using DTOs, and also considering using separate non-ORM data access layer for API. ORM is good for web interfaces (and probably RPC-style APIs), but seems to cause a lot of troubles with REST - it is related to the idea of CQRS.

Related Solutions

Design – Where to define view-specific data objects in Rails

I think the equivalent of the Data Transfer Object you mention is called a presenter in the Rails ecosystem.

On projects with few presenters, I have seen them placed in the /lib directory, but you might as well create an /app/presenters directory.

Also check out this blog post on presenters by Steve Klabnik.

REST Design – Handling Nested Objects

It depends on the experience you want the programmer to have as well as complexity and performance impact in your application.

If the single object is large, and the consumer of the API does not need all the data upfront, then you might want to break it into multiple chunks, and have them call back if they want a related object.
With larger objects, processing and performance on the server may increase, which might itself be an issue, so you may want to keep that lowered.
On the other hand, if your object is really "incomplete" without the sub-objects, then you could consider sending them down in one go.

I do not think PK is necessarily a standard term that is understood by people other than those who deal with databases. For REST APIs, more suitable names might be EntryId, OrderId, MachineId etc., or more genericically Id and ObjectId, etc.

Also, you do not always need to send ObjectIds for the nested elements, the API itself will reveal the relationships (that is kind of the purpose of rest), and thus, from your example, the entry would like this:

entry{
  Id: "42",
  prop1: '_',
  prop2: '_',
}

If someone wanted to find all the orders for an entry, they will issue something like this:

https://www.example.com/entries/42/orders

This will get all the orders for the entry # 42 (with paging etc. if needed).

You might want to see this page for REST URL best practices, and this page for links to other best practices on Rest APIs. You might also want to look at OData since that deals primarily with data and is built on top of REST APIs. Do remember to obviously validate and get other opinions.

Best Answer

Related Solutions

Design – Where to define view-specific data objects in Rails

REST Design – Handling Nested Objects

Related Topic