Skip to content

Commit 1ef7f96

Browse files
author
Josh Holtz
committed
Merge branch 'json-api-v1.0-final' of github.com:joshdholtz/jsonapi-ios into json-api-v1.0-final
2 parents 99be79e + 462385f commit 1ef7f96

File tree

1 file changed

+29
-173
lines changed

1 file changed

+29
-173
lines changed

‎README.md

Lines changed: 29 additions & 173 deletions
Original file line numberDiff line numberDiff line change
@@ -9,16 +9,16 @@ A library for loading data from a [JSON API](http://jsonapi.org) datasource. Par
99

1010
Version | Changes
1111
--- | ---
12+
**1.0.0** | We did it team! Resources now use `JSONAPIResourceDescriptor` for more explicit definitions. **HUGE** thanks to [jkarmstr](https://github.com/jkarmstr) for doing all the dirty work
1213
**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`
1314
**0.2.0** | Added `NSCopying` and `NSCoded` to `JSONAPIResource`; Added `JSONAPIResourceFormatter` to format values before getting mapped - [more info](#formatter)
1415
**0.1.2** | `JSONAPIResource` IDs can either be numbers or strings (thanks [danylhebreux](https://github.com/danylhebreux)); `JSONAPIResource` subclass can have mappings defined to set JSON values into properties automatically - [more info](#resource-mappings)
1516
**0.1.1** | Fixed linked resources with links so they actually link to other linked resources
1617
**0.1.0** | Initial release
1718

1819
### Features
19-
- Parses datasource into manageable objects of `JSONAPIResource`
20-
- Allows resource types to be created into subclasses of `JSONAPIResource` using `JSONAPIResourceModeler`
21-
- Set mapping for `JSONAPIResource` subclass to set JSON values into properties
20+
- Allows resource types to be created into subclasses of `JSONAPIResource`
21+
- Set mapping for `JSONAPIResource` subclass to set JSON values and relationships into properties
2222

2323
## Installation
2424

@@ -30,198 +30,54 @@ Clone the repository and drop in the .h and .m files from the "Classes" director
3030
JSONAPI is available through [CocoaPods](http://cocoapods.org), to install
3131
it simply add the following line to your Podfile:
3232

33-
pod 'JSONAPI', '~> 1.0.0-rc1'
33+
pod 'JSONAPI', '~> 1.0.0'
3434

3535
## Usage
3636

3737
### JSONAPI
3838
`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`.
3939

4040
### JSONAPIResource
41-
`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`.
41+
`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.
4242

4343
#### Resource mappings
44-
`(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
45-
46-
#### Formatter
47-
`JSONAPIResourceFormatter` is used to format values before getting mapped from `mapKeysToProperties`.
48-
49-
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.
50-
51-
````objc
52-
53-
[JSONAPIResourceFormatter registerFormat:@"Date" withBlock:^id(id jsonValue) {
54-
NSDateFormatter *dateFormatter = [[NSDateFormatter alloc] init];
55-
[dateFormatter setLocale:[[NSLocale alloc] initWithLocaleIdentifier:@"en_US_POSIX"]];
56-
[dateFormatter setDateFormat:@"yyyy-MM-dd'T'HH:mm:ssZ"];
57-
58-
NSDate *date = nil;
59-
NSError *error = nil;
60-
if (![dateFormatter getObjectValue:&date forString:jsonValue range:nil error:&error]) {
61-
NSLog(@"Date '%@' could not be parsed: %@", jsonValue, error);
62-
}
63-
64-
return date;
65-
}];
66-
67-
````
44+
`+ (JSONAPIResourceDescriptor*)descriptor` should be overwritten to define descriptors for mapping of JSON keys and relationships into properties of a subclassed JSONAPIResource.
6845

6946
##### Usage
7047

7148
````objc
7249

73-
@interface ASubclassedResource
50+
@interface ArticleResource : JSONAPIResourceBase
7451

75-
@property (nonatomic, strong) NSString *firstName;
52+
@property (nonatomic, strong) NSString *title;
53+
@property (nonatomic, strong) PeopleResource *author;
7654
@property (nonatomic, strong) NSDate *date;
77-
@property (nonatomic, strong) NSArray *authors;
7855
@property (nonatomic, strong) NSArray *comments;
7956

8057
@end
8158

82-
@implementation ASubclassedResource
83-
84-
- (NSDictionary *)mapKeysToProperties {
85-
// Maps values in JSON key 'first_name' to 'firstName' property
86-
// Maps values in JSON key 'date' to 'date' property using the 'Date' formatter
87-
// Maps linked resource in JSON key 'author' to 'author' property
88-
// Maps linked resource in JSON key 'comments' to 'comments' property
89-
return @{
90-
@"first_name" : @"firstName",
91-
@"date" : @"Date:date",
92-
@"links.author" : @"author",
93-
@"links.comments" : @"comments"
94-
};
95-
96-
@end
97-
98-
````
99-
100-
### JSONAPIResourceModeler
101-
102-
`JSONAPIResourceModeler` is used for configuring what type of JSONAPIResource subclass that resource types are created into.
103-
104-
## Examples
105-
106-
### Parsing - Basic
107-
108-
```` objc
109-
110-
NSString *json = @"{\"data\":[{\"id\":1,\"type\":\"posts\",\"name\":\"A post!\"},{\"id\":2,\"type\":\"posts\",\"name\":\"Another post!\"}]}";
111-
112-
// Parses JSON string into JSONAPI object
113-
JSONAPI *jsonApi = [JSONAPI JSONAPIWithString:json];
114-
115-
// Iterates over JSONAPIResources for "posts"
116-
NSArray *posts = jsonApi.resources;
117-
for (JSONAPIResource *post in posts) {
118-
// Prints post name
119-
NSLog(@"\"%@\"", [post objectForKey:@"name"]);
120-
}
121-
122-
123-
````
124-
125-
### Parsing - Using subclassed JSONAPIResource classes, and model mappings
126-
This example shows how a response can be mapped directly into properties of a sublcasses JSONAPIResource
127-
128-
```` objc
129-
130-
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\" } } } }] }";
131-
132-
// Loads "people" into `PeopleResource`, "posts" into `PostResource`, and "comments" into `CommentResource`
133-
[JSONAPIResourceModeler useResource:[PeopleResource class] toLinkedType:@"people"];
134-
[JSONAPIResourceModeler useResource:[PostResource class] toLinkedType:@"posts"];
135-
[JSONAPIResourceModeler useResource:[CommentResource class] toLinkedType:@"comments"];
136-
137-
// Parses JSON string into JSONAPI object
138-
JSONAPI *jsonApi = [JSONAPI JSONAPIWithString:json];
139-
140-
// Gets posts from JSONAPI that will be an array of PostResource objects
141-
NSArray *posts = jsonApi.resources;
142-
143-
// Parsing using JSONAPI and modeled resources (PostResource, PeopleResource, CommentResource
144-
for (PostResource *post in posts) {
145-
146-
PeopleResource *author = post.author;
147-
NSLog(@"\"%@\" by %@", post.name, author.name);
148-
149-
NSArray *comments = post.comments;
150-
for (CommentResource *comment in comments) {
151-
NSLog(@"\t%@", comment.text);
152-
}
59+
@implementation ArticleResource
60+
61+
static JSONAPIResourceDescriptor *__descriptor = nil;
62+
63+
+ (JSONAPIResourceDescriptor*)descriptor {
64+
static dispatch_once_t onceToken;
65+
dispatch_once(&onceToken, ^{
66+
__descriptor = [[JSONAPIResourceDescriptor alloc] initWithClass:[self class] forLinkedType:@"articles"];
67+
68+
[__descriptor setIdProperty:@"ID"];
69+
70+
[__descriptor addProperty:@"title"];
71+
[__descriptor addProperty:@"date"
72+
withDescription:[[JSONAPIPropertyDescriptor alloc] initWithJsonName:@"date" withFormat:[NSDateFormatter RFC3339DateFormatter]]];
73+
74+
[__descriptor hasOne:[PeopleResource class] withName:@"author"];
75+
[__descriptor hasMany:[CommentResource class] withName:@"comments"];
76+
});
77+
78+
return __descriptor;
15379
}
15480

155-
````
156-
157-
#### PostResource.h, PostResource.m
158-
159-
```` objc
160-
161-
@interface PostResource : JSONAPIResource
162-
163-
- (PeopleResource*)author;
164-
- (NSArray*)comments; // Array of CommentResource
165-
- (NSString*)name;
166-
167-
@end
168-
169-
@implementation PostResource
170-
171-
- (NSDictionary *)mapKeysToProperties {
172-
// Maps values in JSON key 'name' to 'name' property
173-
// Maps linked resource in JSON key 'author' to 'author' property
174-
// Maps linked resource in JSON key 'comments' to 'comments' property
175-
return @{
176-
@"name" : @"name",
177-
@"links.author" : @"author",
178-
@"links.comments" : @"comments"
179-
};
180-
181-
@end
182-
183-
````
184-
185-
#### PeopleResource.h, PeopleResource.m
186-
187-
```` objc
188-
189-
@interface PeopleResource : JSONAPIResource
190-
191-
- (NSString*)name;
192-
193-
@end
194-
195-
@implementation PeopleResource
196-
197-
- (NSDictionary *)mapKeysToProperties {
198-
// Maps values in JSON key 'name' to 'name' property
199-
return @{
200-
@"name" : @"name"
201-
};
202-
203-
@end
204-
205-
````
206-
207-
#### CommentResource.h, CommentResource.m
208-
209-
```` objc
210-
211-
@interface CommentResource : JSONAPIResource
212-
213-
- (NSString*)text;
214-
215-
@end
216-
217-
@implementation CommentResource
218-
219-
- (NSDictionary *)mapKeysToProperties {
220-
// Maps values in JSON key 'text' to 'text' property
221-
return @{
222-
@"text" : @"text"
223-
};
224-
22581
@end
22682

22783
````

0 commit comments

Comments
 (0)