Patreon/Realm-JSONAPI

Easily integrate Realm for iOS with a JSON-API compliant server

Realm-JSONAPI

Easily integrate your Realm models with a JSON:API compliant server

Table of Contents

1. Usage
2. Example
3. Documentation
4. Requirements
5. Installation
6. Author
7. License
8. Contributing

Usage

1. Define a Realm model

2. Define JSONtoModelMap (and we strongly recommend defaultAttributes and defaultRelationships as well)

3. Register the model early in the application's lifecycle via

   [[JSONAPIResourceRegistry sharedInstance] bindJSONType:@"your-model-type" toClass:[Model class]]

4. Parse server responses with

   [JSONAPIParserUtilities putJSON:serverResponseDict inRealm:[RLMRealm defaultRealm]]

5. Serialize your model to JSON with [model toJSON] (made accessible via #import <Realm_JSONAPI/RLMObject+JSONAPI.h>) and send it to the server

Example

Try out a full example project with

pod try Realm-JSONAPI

Typical usage in a single RLMObject subclass file looks something like this:

#import <Realm_JSONAPI/RLMObject+JSONAPI.h>

@interface User : RLMModel
@property NSString *uid;
@property NSString *name;
@property NSString *email;
@property NSString *avatarURL;
@end

@implementation User

+ (NSDictionary *)JSONtoModelMap {
    return @{
        @"id" : @"uid",
        @"full_name" : @"fullName",
        @"email" : @"email",
        @"image_url": @"avatarURL",
    };
}

+ (NSArray *)defaultRelationships {
    return @[];
}

+ (NSArray *)defaultAttributes {
    return @[
        @"full_name",
        @"email",
        @"image_url",
    ];
}

+ (NSString *)primaryKey {
    return @"uid";
}

+ (void)fetchUser:(NSString *)uid {
    NSString *baseURL = [NSString stringWithFormat:@"users/%@", uid];
    [APICall queueWithURL:[[self class] defaultURLDecoration:baseURL]
                   params:nil
                   method:HttpMethodGET
              andCallback:callback];
}

- (void)patchWithCallback:(APICompletionBlock)callback {
    NSString *baseURL = [NSString stringWithFormat:@"users/%@", self.uid];
    [APICall queueWithURL:[[self class] defaultURLDecoration:baseURL]
                   params:[self toJSON]
                   method:HttpMethodPATCH
              andCallback:callback];
}

Documentation

You can read the full docs at http://cocoadocs.org/docsets/Realm-JSONAPI

Requirements

Realm and a JSON:API-compliant server

Installation

Realm-JSONAPI is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod "Realm-JSONAPI"

Author

David Kettler, david@patreon.com

License

Realm-JSONAPI is available under the Apache 2.0 license. See the LICENSE file for more info.

Contributing

1. git clone git@github.com:Patreon/Realm-JSONAPI.git
2. cd Realm-JSONAPI
3. git checkout -b my-meaningful-improvements
4. Write beautiful code that improves the project, creating or modifying tests to prove correctness.
5. Commit said code and tests in a well-organized way.
6. Confirm tests pass by opening Example/Realm-JSONAPI.xcworkspace and running tests with Cmd+U (you may need to cd Example && pod install first)
7. git push origin my-meaningful-improvements
8. Open a pull request (hub pull-request, if you have hub)
9. Have a chill discussion with the community about how to best integrate your improvements into mainline deployments