Breeze and RESTful WebAPI

Question

Question:

What value does breeze provide when I need to implement my own POST/PUT/GET endpoints per entity in WebAPI?

Background:

This seems to be a common implementation of a serverside Breeze controller:

[BreezeController]
public class TodosController : ApiController {

    readonly EFContextProvider<TodosContext> _contextProvider =
        new EFContextProvider<TodosContext>();

    // ~/breeze/todos/Metadata
    [HttpGet]
    public string Metadata() {
        return _contextProvider.Metadata();
    }

    // ~/breeze/todos/Todos
    // ~/breeze/todos/Todos?$filter=IsArchived eq false&$orderby=CreatedAt
    [HttpGet]
    public IQueryable<TodoItem> Todos() {
        return _contextProvider.Context.Todos;
    }

    // ~/breeze/todos/SaveChanges
    [HttpPost]
    public SaveResult SaveChanges(JObject saveBundle) {
        return _contextProvider.SaveChanges(saveBundle);
    }

    // other miscellaneous actions of no interest to us here
}

I'm in the middle of building a RESTish API that, up to this point, has endpoints like:

GET /api/todo/1
PUT /api/todo
POST /api/todo

It seems like Breeze requires the endpoints to be much simpler (for better or worse) - just a bunch of GETS and a SaveChanges POST endpoint.

This leads me to think that Breeze makes rapid development with a single web client, well, a breeze... but as soon as you have anonymous clients, you have to force them into whatever breeze interface conventions you've created in your client, which seems to defeat the purpose of RESTful API design. Is this the case?

Answer 1

Breeze is, first and formost, a client-side JavaScript framework. If you're not using Breeze on the client, the benefits of Breeze.WebApi are limited to

• Enhanced OData query support ($select and $expand support, extended $orderby)
• Save interception points (beforeSaveEntity and beforeSaveEntities events)
• Save result handling (updated entity keys, concurrency columns)
• Metadata extraction and serialization

As you've surmised, Breeze has a different philosophy from REST regarding CRUD operations.

Breeze is designed for clients who may want to C/U/D many resources, of different types, in a single transaction. This allows users to manipulate the data in complex ways without hitting the server, then saving their changes when they are ready. For example, one could create a new Order, move two OrderLineItems from one Order to another, delete a third OrderLineItem, modify the quantity on a fourth, and then SaveChanges(). Breeze even supports using localStorage to work completely disconnected from the server. Once reconnected, the changes can all be saved.

REST was designed to operate on one resource at a time. Each C/U/D operation must be performed against the server immediately so that the response code can be acted upon. It works well for applications with simple update needs, but not for data-entry applications. While transactions can be supported in REST, they are cumbersome at best.

Having said that, your server-side Breeze API is not limited to what you see in the Todos example. Breeze supports Named Saves, which allows you to have different endpoints for different operations. You can also use Save Interception to ensure that your save bundle only contains the types that it should. And naturally, there's nothing preventing you from exposing both APIs on your server, and having both fed by the same persistence layer.

If you have to decide between them, you should start with your users. Real users (not developers) don't care about REST, they care about what the application can do. Ultimately, REST gives your application all the semantics of HTTP, and Breeze gives it all the semantics of a relational or object database. Which one to expose to your users should depend upon the use cases you need to support.