Giter Club home page Giter Club logo

jsonapi-ios's Introduction

JSONAPI - iOS

Build Status

A library for loading data from a JSON API datasource. Parses JSON API data into models with support for auto-linking of resources and custom model classes.

Updates

Version Changes
1.0.0-rc1 Rewrote core of JSONAPI and JSONAPIResource and all unit tests to be up to spec with JSON API spec 1.0.0-rc3. Removed JSONAPIResourceLinker. Added JSONAPIErrorResource
0.2.0 Added NSCopying and NSCoded to JSONAPIResource; Added JSONAPIResourceFormatter to format values before getting mapped - more info
0.1.2 JSONAPIResource IDs can either be numbers or strings (thanks danylhebreux); JSONAPIResource subclass can have mappings defined to set JSON values into properties automatically - more info
0.1.1 Fixed linked resources with links so they actually link to other linked resources
0.1.0 Initial release

Features

  • Parses datasource into manageable objects of JSONAPIResource
  • Allows resource types to be created into subclasses of JSONAPIResource using JSONAPIResourceModeler
  • Set mapping for JSONAPIResource subclass to set JSON values into properties

Installation

Drop-in Classes

Clone the repository and drop in the .h and .m files from the "Classes" directory into your project.

CocoaPods

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

pod 'JSONAPI', '~> 1.0.0-rc1'

Usage

JSONAPI

JSONAPI parses and validates a JSON API document into a usable object. This object holds the response as an NSDictionary but provides methods to accomdate the JSON API format such as meta, linked, and (NSArray*)resourcesForKey:(NSString*)key.

JSONAPIResource

JSONAPIResource is an object that holds data for each resource in a JSON API document. This objects holds the "id", "href", and "links" as properties but also the rest of the object as an NSDictionary that can be accessed through (id)objectForKey:(NSString*)key. There is also a method for retrieving linked resources from the JSON API document by using (id)linkedResourceForKey:(NSString*)key.

Resource mappings

(NSDictionary*)mapKeysToProperties can be overwritten to define a dictionary mapping of JSON keys to map into properties of a subclassed JSONAPIResource. Use a "links." prefix on the JSON key to map a linked JSONAPIResource model or array of JSONAPIResource models

Formatter

JSONAPIResourceFormatter is used to format values before getting mapped from mapKeysToProperties.

Below is an example to register a "Date" function to format a date in a NSString object to an NSDate object before its mapped to the JSONAPIResource instance.

[JSONAPIResourceFormatter registerFormat:@"Date" withBlock:^id(id jsonValue) {
    NSDateFormatter *dateFormatter = [[NSDateFormatter alloc] init];
    [dateFormatter setLocale:[[NSLocale alloc] initWithLocaleIdentifier:@"en_US_POSIX"]];
    [dateFormatter setDateFormat:@"yyyy-MM-dd'T'HH:mm:ssZ"];

    NSDate *date = nil;
    NSError *error = nil;
    if (![dateFormatter getObjectValue:&date forString:jsonValue range:nil error:&error]) {
        NSLog(@"Date '%@' could not be parsed: %@", jsonValue, error);
    }

    return date;
}];
Usage
@interface ASubclassedResource

@property (nonatomic, strong) NSString *firstName;
@property (nonatomic, strong) NSDate *date;
@property (nonatomic, strong) NSArray *authors;
@property (nonatomic, strong) NSArray *comments;

@end

@implementation ASubclassedResource

- (NSDictionary *)mapKeysToProperties {
    // Maps values in JSON key 'first_name' to 'firstName' property
    // Maps values in JSON key 'date' to 'date' property using the 'Date' formatter
    // Maps linked resource in JSON key 'author' to 'author' property
    // Maps linked resource in JSON key 'comments' to 'comments' property
    return @{
             @"first_name" : @"firstName",
             @"date" : @"Date:date",
             @"links.author" : @"author",
             @"links.comments" : @"comments"
             };

@end

JSONAPIResourceModeler

JSONAPIResourceModeler is used for configuring what type of JSONAPIResource subclass that resource types are created into.

Examples

Parsing - Basic

NSString *json = @"{\"data\":[{\"id\":1,\"type\":\"posts\",\"name\":\"A post!\"},{\"id\":2,\"type\":\"posts\",\"name\":\"Another post!\"}]}";

// Parses JSON string into JSONAPI object
JSONAPI *jsonApi = [JSONAPI JSONAPIWithString:json];

// Iterates over JSONAPIResources for "posts"
NSArray *posts = jsonApi.resources;
for (JSONAPIResource *post in posts) {
    // Prints post name
    NSLog(@"\"%@\"", [post objectForKey:@"name"]);
}

Parsing - Using subclassed JSONAPIResource classes, and model mappings

This example shows how a response can be mapped directly into properties of a sublcasses JSONAPIResource

NSString *json = @"{ \"data\": [{ \"type\": \"posts\", \"id\": \"1\", \"title\": \"JSON API paints my bikeshed!\", \"links\": { \"self\": \"http:\/\/example.com\/posts\/1\", \"author\": { \"linkage\": { \"type\": \"people\", \"id\": \"9\" } }, \"comments\": { \"linkage\": [ { \"type\": \"comments\", \"id\": \"5\" }, { \"type\": \"comments\", \"id\": \"12\" } ] } } }], \"included\": [{ \"type\": \"people\", \"id\": \"9\", \"first-name\": \"Dan\", \"last-name\": \"Gebhardt\", \"twitter\": \"dgeb\", \"links\": { } }, { \"type\": \"comments\", \"id\": \"5\", \"body\": \"First!\", \"links\": { \"author\": { \"linkage\": { \"type\": \"people\", \"id\": \"9\" } } } }, { \"type\": \"comments\", \"id\": \"12\", \"body\": \"I like XML better\", \"links\": { \"author\": { \"linkage\": { \"type\": \"people\", \"id\": \"9\" } } } }] }";

// Loads "people" into `PeopleResource`, "posts" into `PostResource`, and "comments" into `CommentResource`
[JSONAPIResourceModeler useResource:[PeopleResource class] toLinkedType:@"people"];
[JSONAPIResourceModeler useResource:[PostResource class] toLinkedType:@"posts"];
[JSONAPIResourceModeler useResource:[CommentResource class] toLinkedType:@"comments"];

// Parses JSON string into JSONAPI object
JSONAPI *jsonApi = [JSONAPI JSONAPIWithString:json];

// Gets posts from JSONAPI that will be an array of PostResource objects
NSArray *posts = jsonApi.resources;

// Parsing using JSONAPI and modeled resources (PostResource, PeopleResource, CommentResource
for (PostResource *post in posts) {

    PeopleResource *author = post.author;
    NSLog(@"\"%@\" by %@", post.name, author.name);

    NSArray *comments = post.comments;
    for (CommentResource *comment in comments) {
        NSLog(@"\t%@", comment.text);
    }
}

PostResource.h, PostResource.m

@interface PostResource : JSONAPIResource

- (PeopleResource*)author;
- (NSArray*)comments; // Array of CommentResource
- (NSString*)name;

@end

@implementation PostResource

- (NSDictionary *)mapKeysToProperties {
    // Maps values in JSON key 'name' to 'name' property
    // Maps linked resource in JSON key 'author' to 'author' property
    // Maps linked resource in JSON key 'comments' to 'comments' property
    return @{
             @"name" : @"name",
             @"links.author" : @"author",
             @"links.comments" : @"comments"
             };

@end

PeopleResource.h, PeopleResource.m

@interface PeopleResource : JSONAPIResource

- (NSString*)name;

@end

@implementation PeopleResource

- (NSDictionary *)mapKeysToProperties {
    // Maps values in JSON key 'name' to 'name' property
    return @{
             @"name" : @"name"
             };

@end

CommentResource.h, CommentResource.m

@interface CommentResource : JSONAPIResource

- (NSString*)text;

@end

@implementation CommentResource

- (NSDictionary *)mapKeysToProperties {
    // Maps values in JSON key 'text' to 'text' property
    return @{
             @"text" : @"text"
             };

@end

Author

Josh Holtz, [email protected], @joshdholtz

License

JSONAPI is available under the MIT license. See the LICENSE file for more info.

jsonapi-ios's People

Stargazers

 avatar  avatar

Watchers

 avatar  avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.