RestKitMapperConfig

RestKitMapper Configuration File

RestKitMapper configuration file is a Cocoa property list file with several sections containing configuration information. Please read detailed description for each section below.

Sections

• entity_attribute_mappings - contains mappings from server-side (JSON or XML) attributes to Core Data entity attributes for each configured entity
• primary_key_mappings - contains primary key definitions for each configured entity
• relationship_mappings - contains relationship information for configured entities
• path_mappings - contains dynamic mappings from request paths to mappings
• request_mappings - contains mappings for objects passed from client to server

Entity attribute mappings

Section name: entity_attribute_mappings
Type: dictionary of dictionaries. Top-level keys denote Core Data entity names.
Contents: mappings from server-side attributes to client-side attributes.
Sample entry:

Department
  id -> entityId
  name -> name
  description -> description

Primary key mappings

Section name: primary_key_mappings
Type: dictionary of arrays. Top-level keys denote Core Data entity names.
Sample entry:

Department
  Item 0 -> entityId

Relationship mappings

Section name: relationship_mappings
Type: dictionary of dictionaries. Top-level keys denote Core Data entity names.
Sample entry:

Employee
  dept
    target -> Department
    key_path -> dept
  secondary_dept
    target -> Department
    key_path -> secondary_dept
    fk_mapping
      secondaryDeptId -> entityId

Note: two different methods for relationship mapping are demonstrated above.

First method (dept mapping) is for situation when your JSON/XML data contains whole object graph (that is, dept attribute maps to embedded structure with department data that contains at least (!) primary key attribute and value). target attribute contains name of target relationship entity and key_path contains Employee entity relationship name for Department.

Second method can be used when you use 'flat' (normalized) structures and don't include department data into your employee data except for server-side foreign key value. target and key_path has the same meaning as in the first key, but to map the relationship you need to meet three important requirements:

1. You need to have secondaryDeptId attribute on your Employee entity in Core Data model
2. You need to map this attribute when mapping Employee from server to client (see Entity attribute mappings above)
3. You need to provide foreign key mapping between secondaryDeptId on Employee entity and primary key of Department entity (that's what fk_mapping attribute does)

Path mappings

Section name: path_mappings
Type: list of dictionaries. Every dictionary contains mappings for a particular path.
Sample entry:

Item 0
  uri -> /employees
  key_path -> employees_list
  matchers ->
    Item 0
      key_path -> type
      expected_value -> employee
      entity_name -> Employee

If you have mixed objects in your JSON/XML output, you may use matchers to distinguish one object type from another. If you don't, key_path and expected_value in matcher items may be omitted and all encountered data structures will be mapped to specified entity_name. Top-level key_path may be also omitted if your REST output doesn't designate any particular key as actual data container.

The above example will expect JSON structure like this:

{
  "employees_list": [
     { 
       "type": "employee", 
       "id": 1234, 
       "name": "John Doe", 
       "description": "No description provided",
       "dept": { "type": "department", "id": 987, "name": "IT Department" },
       "secondary_dept": 678
     }
  ]
}

Request mappings

Section name: request_mappings
Type: list of dictionaries
Sample entry:

Item 0
  uri -> /user/auth
  root_keypath -> user
  class_name -> UserLoginInfo
  attribute_mappings
    username -> username
    password -> password

This will map your UserLoginInfo Objective-C class (not necessarily Core Data class!) to JSON structure like this:

{ "user": { "username": "username", "password": "password" } }