Platformsios 7.0, osx 10.9, watchos 2.0, tvos 9.0, requires ARC
DependenciesRestGoatee-Core, AFNetworking

Build Status
Coverage Status
Carthage Compatible
Pod Version
Pod Platform
Pod License
Readme Score

RestGoatee is an add-on framework to AFNetworking; taking the raw NSDictionary and NSXMLParser responses and convienently converts them to your own objects. If you have AFNetworking >= 3.0 this library will use that version, otherwise it will be included as part of the CocoaPods pod install process.

This library deals solely with networking, and uses the underlying pod, RestGoatee-Core for deserializing JSON and XML.

Supports: iOS 7.0+ and AFNetworking 3.x, below version 2.6 supports AFNetworking 2.x, branch v1.5.4 supports down to AFNetworking 1.3.3 (does not have XML support).

This library’s aim is one of simplicity in the common case and extensibility in the general case:
1) The "API reponse to working objects" operation is not the place for business logic or key translation.
2) The API layer should be able to handle new objects and object properties seemlessly without requiring new deserialization logic. For example, this commit added an entirely new response object to the example project without fanfare.
3) Due to JSON and XML having limited types, the deserializer needs to be able to intelligently map to a larger standard family of types.
4) CoreData support is usually not done at the outset of a project; this library makes it easier to turn it on with minimal refactoring. CoreData support is implicit, but inactive in projects without it.
5) The default mapping behavior should be both generally intuitive (correct 99% of the time) and extensible.
6) The default should be the least verbose in terms of complexity and lines of code. You don’t specify mappings for objects that are obviously one-to-one and well-named.

Why Use RestGoatee?

Consider your favorite or most popular model framework:

  • Does it require mappings to build simple objects? RestGoatee
  • Does it support NSManagedObject subclasses? RestGoatee
  • Does it understand the keys foo-bar foo_bar and fooBar are likely the same key? RestGoatee
  • JSON or XML? RestGoatee


Using cocoapods add pod 'RestGoatee' to your Podfile and run pod install. People without cocoapods can include the top level folder "RestGoatee" in their repository. Include #import <RestGoatee/RestGoatee.h> to include all public headers and start using the library.

If you implement -keyForReconciliationOfType:, the key ought to be something generally available on all objects (a unique identifer key for example). Objects without this key will not be unique checked, additionally it does not affect non-NSManagedObject subclasses.


You can clone this repository and run pod install in your installation directory.

We will use this example to turn a request to iTunes Search API into objects.


@interface RGBook : NSObject

@property (nonatomic, strong) NSString* artistName;
@property (nonatomic, strong) NSString* description;
@property (nonatomic, strong) NSArray* genres;
@property (nonatomic, strong) NSDate* releaseDate;
@property (nonatomic, strong) NSNumber* trackId;
@property (nonatomic, strong) NSString* trackName;


*** A note on usage: the semantics of the property are fully respected. A property could be declared (copy, readonly) and would be treated correctly. readonly properties are constructed through their backing instance variables and copy are sent -copy, etc.

@implementation RGBook @end //nothing!

In your API…

- (void) getResults:(NSString*)searchTerm completion:(RGResponseBlock)completion {
  /* your invocation of the API */  [self GET:@"/search" parameters:@{ @"term" : searchTerm } keyPath:@"results" class:[RGBook class] completion:completion];

Another option is to retrieve the raw objects:

- (void) getResults:(NSString*)searchTerm completion:(RGResponseBlock)completion {
  [self GET:@"/search" parameters:@{ @"term" : searchTerm } keyPath:@"results" class:Nil completion:^(RGResponseObject* response) {
      NSLog(@"%@", response.responseBody);

This API Client can handle XML, this would return the raw RGXMLNode document node:

- (void) getBartStations {
    [self GET:@"" parameters:nil keyPath:@"root.stations.station" class:Nil completion:^(RGResponseObject* response) {
        NSLog(@"%@", response.responseBody);

This call would return an array of RDDBartStation:

- (void) getBartStations {
    [self GET:@"" parameters:nil keyPath:@"root.stations.station" class:[RDDBartStation self] completion:^(RGResponseObject* response) {
        NSLog(@"%@", response.responseBody);

Image Downloading is optimized and cached; the use cases can be per UIImageView or directly invoked like so:

UIImageView* imageView = [UIImageView new];
[imageView rg_setImageWithURL:@""];

- OR -

NSURL* url = [NSURL URLWithString:@""];
NSMutableURLRequest* request = [NSMutableURLRequest requestWithURL:url];
rg_setImageWithURL(nil, request, nil, ^(NSHTTPURLResponse* response, UIImage* image) {
    NSLog(@"%@", image);
    /* Do something with your image */}, nil);


BSD Simplified (2-clause)

Latest podspec

    "name": "RestGoatee",
    "version": "2.8.0",
    "summary": "An intuitive JSON & XML deserialization library for ReST based clients",
    "homepage": "",
    "license": "BSD",
    "authors": {
        "Ryan Dignard": "[email protected]"
    "source": {
        "git": "",
        "tag": "2.8.0"
    "requires_arc": true,
    "platforms": {
        "ios": "7.0",
        "osx": "10.9",
        "watchos": "2.0",
        "tvos": "9.0"
    "source_files": "RestGoatee",
    "dependencies": {
        "RestGoatee-Core": [
            "~> 2.5.5"
        "AFNetworking": [
            "~> 3.0"

Pin It on Pinterest

Share This