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.
| 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 |
- Parses datasource into manageable objects of
JSONAPIResource - Allows resource types to be created into subclasses of
JSONAPIResourceusingJSONAPIResourceModeler - Set mapping for
JSONAPIResourcesubclass to set JSON values into properties
Clone the repository and drop in the .h and .m files from the "Classes" directory into your project.
JSONAPI is available through CocoaPods, to install it simply add the following line to your Podfile:
pod 'JSONAPI', '~> 1.0.0-rc1'
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 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.
(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
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;
}];
@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 is used for configuring what type of JSONAPIResource subclass that resource types are created into.
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"]);
}
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);
}
}
@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
@interface PeopleResource : JSONAPIResource
- (NSString*)name;
@end
@implementation PeopleResource
- (NSDictionary *)mapKeysToProperties {
// Maps values in JSON key 'name' to 'name' property
return @{
@"name" : @"name"
};
@end
@interface CommentResource : JSONAPIResource
- (NSString*)text;
@end
@implementation CommentResource
- (NSDictionary *)mapKeysToProperties {
// Maps values in JSON key 'text' to 'text' property
return @{
@"text" : @"text"
};
@end
Josh Holtz, [email protected], @joshdholtz
JSONAPI is available under the MIT license. See the LICENSE file for more info.