Broker

Broker maps remote resources to local Core Data resources via JSON responses. Using a few simple design standards, you can automatically map JSON attributes to NSManagedObject attributes with little effort.

All this fun stuff is done with a few rules.

1. Name your local object attributes the same as remote attributes. For example, if your remote Employee has a “firstName” attribute, don't name your local NSManagedObject Employee attribute “first_name”. If you want, Broker has the flexibility to map remote names to local ones, but why add the extra code?
2. Use a unique object identifier. Each object you want to persist should have a unique attribute to easily identify it. For example, Employee might have an employeeId. Without this, there isn't a way to safely guarantee one single persisted object.

Installation

Broker follows standard patterns for iOS static library design.

1. Add the Broker.xcodeproj file to your project.
2. Add Broker as a target dependency in your targets Build Phase tab.
3. Add libBroker.a to your targets Link Binary With Libraries build phase.
4. Build your app.

Now you should be able to import Broker headers following this pattern.

#import <Broker/Broker.h>

Getting Started

Create and configure a new BKController. This should be a long lived object, perhaps stored on your App Delegate or an otherwise appropriate location.

BKController *controller = [BKController controller];

Register your NSManagedObject with the controller in your main Core Data context. What this does is temporarily creates an Employee object in your context, traverses all it's properties and relationships, and builds an internal description of what makes an Employee object based on NSEntityDescription and NSAttributeDescription. These descriptions are used to transform JSON into the registered entity. This example assumes you have an Emoloyee object in your Core Data model with at least an employeeId attribute.

[controller.entityMap registerEntityNamed:@"Employee"
                           withPrimaryKey:@"employeeId"
                  andMapNetworkProperties:@"id"
                        toLocalProperties:@"employeeId"
                                inContext:context];

Note that we are mapping a network property, id, to a local property, employeeId. Sometimes your API may use different attribute names than what you have in your Core Data. Broker allows you to map between the two.

Now you are ready to process some JSON. By passing in the main NSManagedObjectContext into the BKController, you are spinning up a child context in which all the work will be done. After the work is done, the context pushes it's changes to the main context. From there, you can choose to either save or not, but this example includes a proper save pattern.

- (void)processEmployeeJSON:(id)json 
	withController:(BKController *)controller
	 inContext:(NSManagedObjectContext *)context
{
		__weak NSManagedObjectContext *weakContext = context;
	    [controller processJSONObject:json
                    	asEntityNamed:@"Employee"
                      		inContext:context
                  	  completionBlock:^{
                       [weakContext performBlock:^{
   						 [context save:nil];
					   }];
                   }];
}

Broker and JSON API Design

Broker is built to handle specific styles of JSON responses.

List of things

Broker can process a list of similar things. For example, a JSON response containing a list of Employee objects.

[
    {
        "name": "Andrew",
        "department": "Engineering",
        "employeeId": 1
    },
    {
        "name": "Sarah",
        "department": "Engineering",
        "employeeId": 2
    },
    {
        "name": "Steve",
        "department": "Marketing",
        "employeeId": 3
    }
]

Broker cannot process a mixed list of things, like Employee's and Departments.

[
    {
        "name": "Andrew",
        "department": "Engineering",
        "employeeId": 1
    },
    {
        "name": "Engineering",
        "departmentId": 2
    },
]

Instead, you should return similar objects it as nested lists, which you can process separately.

[
    {
        "employees": [
            {
                "name": "Andrew",
                "department": "Engineering",
                "employeeId": 1
            }
        ]
    },
    {
        "departments": [
            {
                "name": "Engineering",
                "departmentId": 2
            }
        ]
    }
]

A Single Thing

Broker can process a single thing. For example, a single Employee.

{
    "name": "Andrew",
    "department": "Engineering",
    "employeeId": 1
}

A Nested Thing on a Thing

Broker can process a nested thing. For example, an Employee with a Department.

{
    "name": "Andrew",
    "employeeId": 1,
    "department": {
        "name": "Engineering",
        "departmentId": 1
    }
}

A Nested List of Things on a Thing

Broker can process a nested list of things on a thing. For example, a Department with a list of Employees.

{
    "name": "Engineering",
    "departmentId": 1,
    "employees": [
        {
            "name": "Andrew",
            "departmentId": 1
        },
        {
            "name": "Sarah",
            "employeeId": 2
        }
    ]
}

Unique Objects

Broker uses a “primary key” convention to enforce object uniqueness. NSManagedObjects must have a primary key to be registered with Broker. For example, an Employee could have a unique employeeId attribute. Once we have a primary key, we can use a simple find or create pattern to guarantee uniqueness. Without specifying a primary key, you could end up with duplicate objects.

DISCLAIMER: If you are working with JSON where you might have more than a few thousand entities at once, the find-or-create pattern in it‘s current form will be slow. I’m working on a faster pattern.