loganwright/Polymer

#import <Foundation/Foundation.h>
#import <Genome/Genome.h>

@interface SpotifyArtist : NSObject <GenomeMappableObject>
@end

#import <Foundation/Foundation.h>
#import <Genome/Genome.h>

@interface SpotifyArtist : NSObject <GenomeMappableObject>
@property (strong, nonatomic) NSURL *externalSpotifyUrl;
@property (nonatomic) NSInteger numberOfFollowers;
@property (strong, nonatomic) NSArray *genres;
@property (strong, nonatomic) NSURL *url;
@property (copy, nonatomic) NSString *identifier;
@property (strong, nonatomic) NSArray *images;
@property (copy, nonatomic) NSString *name;
@property (nonatomic) NSInteger popularity;
@property (copy, nonatomic) NSString *type;
@property (strong, nonatomic) NSURL *uri;
@end

mapping[@"<#propertyName#>"] = @"<#associatedJsonKeyPath#>";

mapping[@"<#arrayPropertyName#>@<#ClassName#>"] = @"<#associatedJsonKeyPath#>";

propertyMap(@"<#propertyName#>", [<#classType#> class])

#import "SpotifyArtist.h"

@implementation SpotifyArtist
+ (NSDictionary *)mapping {
    NSMutableDictionary *mapping = [NSMutableDictionary dictionary];
    // Note keypaths in associated JSON
    mapping[@"externalSpotifyUrl"] = @"external_urls.spotify";
    mapping[@"numberOfFollowers"] = @"followers.total";
    mapping[@"genres"] = @"genres";
    mapping[@"url"] = @"href";
    mapping[@"identifier"] = @"id";
    // Note array type specification
    mapping[@"images@SpotifyImageRef"] = @"images";
    mapping[@"name"] = @"name";
    mapping[@"popularity"] = @"popularity";
    mapping[@"type"] = @"type";
    mapping[@"uri"] = @"uri";
    return mapping;
}
@end

#import <Foundation/Foundation.h>
#import <Genome/Genome.h>

@interface SpotifyImageRef : NSObject <GenomeObject>
@property (nonatomic) NSInteger height;
@property (nonatomic) NSInteger width;
@property (copy, nonatomic) NSURL *url;
@end

#import "SpotifyImageRef.h"

@implementation SpotifyImageRef
+ (NSDictionary *)mapping {
    NSMutableDictionary *mapping = [NSMutableDictionary dictionary];
    mapping[@"height"] = @"height";
    mapping[@"width"] = @"width";
    mapping[@"url"] = @"url";
    return mapping;
}
@end

#import <Foundation/Foundation.h>
#import <Polymer/PLYEndpoint.h>

#import <Foundation/Foundation.h>
#import <Polymer/PLYEndpoint.h>

@interface SpotifyBaseEndpoint : PLYEndpoint
@end

#import "SpotifyEndpoints.h"
#import "SpotifyArtist.h"

@implementation SpotifyBaseEndpoint
- (NSString *)baseUrl {
    return @"https://api.spotify.com/v1";
}
@end

@implementation GHBaseEndpoint
- (NSSet *)acceptableContentTypes {
    return [NSSet setWithObjects:@"text/html", @"application/json", nil];
}

- (AFHTTPRequestSerializer<AFURLRequestSerialization> *)requestSerializer {
    return [AFJSONRequestSerializer serializer];
}

- (NSDictionary *)headerFields {
    NSMutableDictionary *headerFields = [NSMutableDictionary dictionary];
    headerFields[@"Accept"] = @"application/vnd.github.v3+json";

    NSString *token = [storage accessToken];
    if (token) {
        NSString *tokenHeader = [NSString stringWithFormat:@"Token %@", token];
        headerFields[GHNetworkingHeaderKeyAuthorization] = tokenHeader;
    }

    return headerFields;
}

- (NSString *)baseUrl {
    return @"https://api.github.com";
}
@end

#import <Foundation/Foundation.h>
#import <Polymer/PLYEndpoint.h>

@interface SpotifyBaseEndpoint : PLYEndpoint
@end

// Note subclass
@interface SpotifySearchEndpoint : SpotifyBaseEndpoint
@end

#import "SpotifyEndpoints.h"
#import "SpotifyArtist.h"

@implementation SpotifyBaseEndpoint
- (NSString *)baseUrl {
    return @"https://api.spotify.com/v1";
}
@end

@implementation SpotifySearchEndpoint
- (Class)returnClass {
    return [SpotifyArtist class];
}
- (NSString *)endpointUrl {
    return @"search";
}
- (NSString *)responseKeyPath {
    return @"artists.items";
}
@end

PLYEndpoint *ep = [SpotifySearchEndpoint endpointWithParameters:@{@"q" : @"beyonce", @"type" : @"artist"}];
[ep getWithCompletion:^(id object, NSError *error) {
    NSArray *artists = (NSArray *)object;
    NSLog(@"Got artists: %@ w/ error: %@", artists, error);
}];

PLYEndpoint *ep = [SpotifySearchEndpoint endpointWithParameters:@{@"q" : @"beyonce", @"type" : @"artist"}];
[ep getWithCompletion:^(NSArray *artists, NSError *error) {
    NSLog(@"Got artists: %@ w/ error: %@", artists, error);
}];

- (NSString *)baseUrl {
  return @"http://api.somewebservice.com";
}

- (NSDictionary *)headerFields {
  NSMutableDictionary *header = [NSMutableDictionary dictionary];
  header[@"Accept"] = @"application/vnd.somewebservice.com+json; version=1";
  header[@"Authorization"] = [NSString stringWithFormat:@"Token token=%@", MY_TOKEN];
  return header;
}

- (NSSet *)acceptableContentTypes {
  return [NSSet setWithObjects:@"application/json", @"text/html", nil];
}
override var acceptableContentTypes: Set<NSObject> {
    return Set(["application/json", "text/html"])
}

- (Class)returnClass {
  return [Post class];
}

- (NSString *)endpointUrl {
  return @"posts/:identifier";
}

PostsEndpoint *pe = [PostsEndpoint endpointWithSlug:@{@"identifier" : @"17"}];
[pe getWithCompletion: ... ];

@interface Post : NSObject

@property (copy, nonatomic) NSString *identifier;

@end
```

Now, if we passed the Post as a slug into our endpoint like this, it would be automatically populated:

```ObjC
Post *post = ...;
PostsEndpoint *ep = [PostsEndpoint endpointWithSlug:post];
[ep getWithCompletion: ... ];
```

If our `post` object declared above has an identifier of `352` then we would be sending a get request to the endpoint `http://someBaseUrl.com/posts/352`

#####3. Multiple Object Types

In some situations, we want to pass a variety of objects to an endpoint and define more specifically how that endpoint should be populated with the slug.  For these situations, you can override `valueForSlugPath:withSlug` to define what value should be used to populate the url.  Our endpoint might look like this:

```ObjC
@implementation PostsEndpoint
/*
...
*/
- (id)valueForSlugPath:(NSString *)slugPath withSlug:(id)slug {
  if ([slug isKindOfClass:[Comment class]]) {
    Comment *comment = (Comment *)slug;
    return comment.post.identifier;
  } else {
    return [super valueForSlugPath:slugPath withSlug:slug];
  }
}
@end
```

By overriding as demonstrated above, we can pass our endpoint a `Dictionary`, a `Post` object, or a `Comment` object and when we fetch from our Posts endpoint, we'll interact with the appropriate endpoint.
a

######Slug Mapping Nil Check

By default, a value is checked if it is `nil` or `NSNull`.  If either of these is true, the path is not mapped.  In rare cases, you may need to specify what constitutes as `nil`.  For example, sometimes when using an NSInteger, it is 0 but needs to be nil.

```ObjC
@implementation PostsEndpoint
/*
...
*/
- (BOOL)valueIsValid:(id)value forSlugPath:(NSString *)slugPath {
  if ([slugPath isEqualToString:@"identifier"]) {
    return [value intValue] > 0;
  } else {
    return YES;
  }
}
@end
```

#####Response Key Path

If you wish to use a portion of the response located at a specified keypath, you can declare it here.  This is only necessary for specific situations.  For example, if our response looked like this:

```
[
  "results" : [
    // ... results
  ]
]
```

We could specify to map only the array located at `results` by declaring like so:

######ObjC

```ObjC
- (NSString *)responseKeyPath {
  return @"results";
}
```

######Swift

```Swift
override var responseKeyPath: String {
  return "results"
}
```

####Serializers

In rare situations, you may need to provide a request or response serializer yourself.  In those situations use the following:


#####Response Serializer

```ObjC
- (AFHTTPResponseSerializer<AFURLResponseSerialization> *)responseSerializer {
  return ...;
}
```

#####Request Serializer

```ObjC
- (AFHTTPRequestSerializer<AFURLRequestSerialization> *)requestSerializer {
  return ...;
}
```

####Append Header

In some situations, the header contains valueable data we want to include in mapping.  A common example of this is when next / last urls are included for paging in the header.

If the response is a dictionary, an additional field will be added called 'Header', and values can be accessed via keypath syntax, ie: `Header.etag`.

```
[
  "Header" : [
    "headerKey" : "headerVal",
    // ...
  ]
  "responseKey" : "response Val"
  "responseKey2": "response val"
]
```

If the response is an array, it will be appended to the key `"response"` for mapping.

```
[
  "Header" : [
    "headerKey" : "headerVal"
  ]
  "response" : [
    // ... array response
  ]
```

######ObjC

```ObjC
- (BOOL)shouldAppendHeaderToResponse {
  return YES;
}
```

######Swift

```Swift
override var shouldAppendHeaderToResponse: Bool {
  return true
}
```

####Transform Response

For some apis, the data we receive isn't able to be parsed a valid json representation for mapping.  This is most common with XML webservices.  In those situations, you can override `transformResponseDataToMappableRawType:`.  This can also be overridden for customize behavior of specialized circumstances.

######ObjC

```ObjC
- (id<GenomeMappableRawType>)transformResponseToMappableRawType:(id)response {
  if ([response isKindOfClass:[NSData class]]) {
        NSData *responseData = response;
        NSDictionary *responseDictionary = ... convert response data;
        return responseDictionary;
  } else {
    return response;
  }
}
```

######Swit

```Swift
override func transformResponseToMappableRawType(response: AnyObject) -> GenomeMappableRawType? {
  if let data = response as? NSData {
    return ... converted data
  } else {
    return response as? GenomeMappableRawType
  }
}
```

####Networking Examples

Once you've modeled your endpoint, the majority of the work is done!  You simply intialize your endpoint with a slug and parameters as necessary and you're on your way!

#####Get

######Get specific post

```ObjC
PostsEndpoint *ep = [PostsEndpoint endpointWithSlug:@{@"identifier" : @"3"}];
[ep getWithCompletion:^(Post *post, NSError *error){
  // ...
}];
```

######Get a user's posts

```ObjC
PostsEndpoint *ep = [PostsEndpoint endpointWithParameters:@{@"user_id" : currentUser.identifier}];
[ep getWithCompletion:^(NSArray *posts, NSError *error){
  // ... array of Post objects
}];
```

#####Post

```ObjC
NSDictionary *newPost = @{
  @"title" : @"New Post",
  @"body" : @"This is a cool new post"
};
PostsEndpoint *ep = [PostsEndpoint endpointWithParameters:newPost];
[ep postWithCompletion:^(Post *post, NSError *error){
  // ... created new post, or error
}];
```

#####Put

```ObjC
NSArray *tags = [
  @"red",
  @"fun",
  @"summer"
]

PostTagEndpoint *ep = [PostTagEndpoint endpointWithSlug:post
                                          andParameters:tags];
[ep putWithCompletion:^(NSArray *tags, NSError *error){
  // ... created or updated tags for post.
}];
```

#####Patch

```ObjC
NSDictionary *updatedParams = @{
  @"title" : @"New Title",
  @"body" : @"Updated body"
};

PostsEndpoint *ep = [PostsEndpoint endpointWithSlug:post
                                      andParameters:updatedParams];
[ep patchWithCompletion:^(Post *post, NSError *error){
  // ... created new post, or error
}];
```

#####Delete

```ObjC
PostEndpoint *ep = [PostEndpoint endpointWithSlug:post];
[ep deleteWithCompletion:^(Post *deletedPost, NSError *error) {
    // .. deleted object or error
}]
```

####Mapping

For more information, see <a href="https://github.com/loganwright/genome">Genome</a>