<commit_before># Getting Acquainted with RestKit
> _This guide is current as of RestKit **v0.20.0**._

This guide provides an introduction to the RestKit framework for iOS and Mac OS X. After reading it, you should have an understanding of the following topics:

1. What RestKit is and the benefits of adopting it for your next iOS or Mac OS X project.
2. How RestKit is designed and the philosophy of the library.
3. How to install RestKit into an application and begin interacting with a web service.
4. How RestKit interfaces with Core Data.
5. How RestKit provides abstractions for interacting with web service API's

## Guide Assumptions

This guide is designed for beginners who want to get started with a RestKit application from scratch. It does not assume that you have any prior experience with RestKit. It does, however, assume that the you have a basic understanding of Cocoa development and have some pre-requisites installed:

* [Xcode](https://itunes.apple.com/us/app/xcode/id497799835?mt=12) version >= 4.6
* [CocoaPods](http://cocoapods.org/) version >= 1.6.2

RestKit is a framework for implementing web service API client applications on iOS and Mac OS X in the Objective-C programming language. If you have no prior experience with Cocoa and Objective-C, then you will face a very steep learning curve if you attempt to dive straight into RestKit. It is recommended that you not attempt to drink the ocean by tackling Objective-C, Cocoa, and RestKit all at once. There are numerous resources available online for getting started with Cocoa development and this guide will be here once you have established a firm grounding in the basics of Cocoa development.

If you already have a handle on the basics of Cocoa development, then there are a few specific technologies and patterns that you will need to be familiar with in order to get the most out of this guide:

* [REST](http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm) - REST is an acronym for Representational State Transfer and describes an architectural pattern for implementing interapplication communication in distributed systems such as the World Wide Web. RestKit provides a set of tools for implementing RESTful client applications in Cocoa/Objective-C.
* [Key-Value Coding](http://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/KeyValueCoding/Articles/KeyValueCoding.html) - Key-Value coding is a mechanism for expressing indirect read/write access to properties by name. It is implemented as an informal protocol that is adopted by `NSObject` and underpins many Cocoa technologies such as key-value observation, Core Data, and bindings. KVC is the enabling technology for the object mapping system in RestKt.
* [NSOperation](http://developer.apple.com/library/mac/#documentation/Cocoa/Reference/NSOperation_class/Reference/Reference.html) - The `NSOperation` class is a Cocoa Foundation abstract class that encapsulates the code and data associated with a single task. Much of RestKit is implemented as `NSOperation` subclasses.
* [Core Data](http://developer.apple.com/library/mac/#documentation/cocoa/Conceptual/CoreData/cdProgrammingGuide.html) - Core Data is an object graph management and persistence framework provided by Apple with the Mac OS X and iOS SDKs. RestKit provides strong support for integrating a RESTful web service API with client-side persistence backed by Core Data.
* [Objective-C Runtime](https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/ObjCRuntimeGuide/Introduction/Introduction.html) - Objective-C is a highly dynamic language implemented on top of the C programming language. The runtime provides much of the dynamic functionality of the language. RestKit leverages many features of the runtime in the implementation of the object mapping engine. For the purposes of this guide, it is sufficient for the reader to simply be aware that Objective-C provides dynamic functionality such as runtime type inspection, declared property introspection, and message forwarding.
* [AFNetworking](http://afnetworking.org/) - AFNetworking is a "delightful networking library for iOS and Mac OS X". RestKit is implemented on top of the networking primitives provided by AFNetworking.

## What is RestKit?

> This section provides background and philosophy of RestKit in details. You can safely skip this section and come back to it at a later time. The next section begins the hand's on exploration of working with RestKit.

RestKit is a modern Objective-C framework for implementing RESTful web service client applications on iOS and Mac OS X. It is designed to make the development of your application easier by providing a system for binding your application's data model with the JSON or XML documents emitted by the web service you are communicating with. It enables you to write less code by shifting many application concerns into the library. It also speeds development by providing out-of-the-box solutions and patterns for tackling many common problems you will face when implementing your application -- particularly when integrating with Core Data. Experienced developers also find that RestKit enables a more satisfying and more maintainable code base because it encourages cleanliness and testability as core values.

RestKit is opinionated software. It makes a number of assumptions about your backend API and encourages the adoption of several design patterns in your Cocoa application code. Not every API is suitable for integration with RestKit -- particularly those that follow remote procedure call (RPC) semantics. When evaluating RestKit for use in your project, you should consider how closely your API and application design conform to the following assumptions:

* Your backend API is RESTful or at least "REST-ish". Interactions with your web application can be described in terms of resources and operations performed on those resources.
* Your backend API and your application's data model should be designed independently around what makes the most sense for each application. RestKit provides the tools for expressing the connection between these designs cleanly and simply.
* You think of your API in terms of objects that are accessed and manipulated, rather than requests made and responses processed. HTTP is a transfer medium and an implementation detail rather than a primary concern.
* Testability is a primary concern in your project. You believe in executable tests that verify behavior as a design and development tool. RestKit encourages the use of unit and functional testing for your application and provides tools for adopting a test-driven development style.

### RestKit Components

RestKit is shipped as a single library that is composed of several individual components collaborating to form a cohesive framework. Each component is designed with minimal dependencies and is usable as a standalone library. Each of these components is explained briefly below. Don't worry about attempting to understand the low-level details of each component now -- we'll explore each in detail later. For now, try to focus on the functionality provided by each component and grasp the layering of each component within the overall architecture.

#### Object Mapping

The Object Mapping component provides the lion's share of the functionality within RestKit. The Object Mapping system provides a mechanism for expressing the transformation of objects between representations using key-value coding and the dynamic features of the Objective-C runtime.

#### Networking

The Networking component provides integration between the Object Mapping component and HTTP networking primitives provided by AFNetworking. Services provided by the Networking component include the serialization and deserialization wire formats (such as JSON/XML), the binding of Object Mapping descriptions with HTTP requests and responses, the generation of URL's via routing, and the parameterization of local objects into HTTP parameters. This component includes many of the most used classes, such as the object manager and object request operation.

#### Core Data

The Core Data component provides integration between the RestKit Object Mapping and Networking components and Apple's Core Data modeling and persistence framework. This component mostly includes specialized implementations of classes provided by the Object Mapping and Networking layers, but also includes additional functionality specific to Core Data such as relationship connection descriptions.

##### Search

A subset of the Core Data component -- the Search component provides support for the indexing and searching of managed objects. The component includes a tokenizer, indexer, and convenience API's for generating search predicates that can be used to query indexed objects.

#### Testing

The Testing component includes several classes to make unit testing object mapping straightforward. Also included is a lightweight object factory implementation, which makes it easy to build reusable test fixtures. The testing classes are agnostic about the testing library you use and work easily with SenTest, Kiwi, Specta, Cedar, etc.

## Getting Up and Running

RestKit is distributed as a single library containing several sub-components. There are two supported installation methods:

1. [Automatic configuration via CocoaPods](https://github.com/RestKit/RestKit/wiki/Installing-RestKit-v0.20.x-via-CocoaPods) - This is the recommended approach as CocoaPods handles the linker flags, header paths, and download of source code dependencies on your behalf.
2. [Manual configuration as a submodule](https://github.com/RestKit/RestKit/wiki/Installing-RestKit-v0.20.x-as-a-Git-Submodule) - This method involves adding a submodule to your project and building RestKit as a dependency. You are responsible for configuring the project appropriately.

Before proceding with the tutorial, you should familiarize yourself with the installation method of your choosing.

## Creating the RKGist Application

The remainder of this guide is organized as a step-by-step tutorial designed to walk you through the basics of working with RestKit to implement access to an API. Each sections builds on its predecessors, so the best approach is to work through each section one at a time in the order presented. You can obtain a complete copy of the completed tutorial application [on Github](http://github.com/RestKit/RKGist).

By following this guide, you'll be creating an iOS application with RestKit called `RKGist`, a very simple client for [Github's Gist application](https://gist.github.com/). We've selected Gist for this tutorial because it is very well known, has a relatively simple API, and is very [well documented](http://developer.github.com/v3/gists/). We'll explore a large subset of the RestKit API's in a task based fashion, introducing new functionality and concepts as they enter the purview of the application being developed. 

### Creating the iOS Application

To begin creating the application, Open Xcode and select the "File" menu, then "New Project…". You will be presented with a new Xcode window displaying the template selection sheet. Select the "Master-Detail Application" template under the "iOS" and hit the "Next" button.

![Choose Project Template](Images/Xcode-Choose_Project_Template.png)

On the next screen, configure the options for your project by setting the *Product Name* to "RKGist", specifying a *Class Prefix* of "RKG" and then enabling the following options:

* Use Storyboard
* Use Core Data
* Use Automatic Reference Counting
* Include Unit Tests

Hit the "Next" button and save your new project to an appropriate place on disk.

![Configure Project Options](Images/Xcode-Configure_Project_Options.png)

### Installing RestKit via CocoaPods

Once your project has been created, you'll need to add RestKit to it using [CocoaPods](http://cocoapods.org/). To do so, open up your Terminal application and navigate to the location on disk where you saved the RKGist application. From there, install CocoaPods by executing the following commands on your Terminal:

```sh
$ [sudo] gem install cocoapods
$ pod setup
```
You can now add RestKit to your project by creating a new Podfile:

```sh
$ edit Podfile
```

Your favorite editor will open and allow you to configure your dependencies. Input the following into your Podfile:

```ruby
platform :ios, 6.0
pod 'RestKit', '~> 0.20.0rc'

# Include optional Testing and Search components
pod 'RestKit/Testing', '~> 0.20.0rc'
pod 'RestKit/Search', '~> 0.20.0rc'

# Import Expecta for Testing
target :test do
  link_with :RKGistTests
  pod 'Expecta', '0.2.1'
end
```

Invoke CocoaPods to install the dependencies:

```sh
$ pod install
```

CocoaPods will configure your project for use and create a new Workspace file. Open up `RKGist.xcworkspace` and then open the `RKGist-Prefix.pch` file from within the **RKGist** > **Supporting Files** group in the workspace. Set the files content to:

```objc
//
// Prefix header for all source files of the 'RKGist' target in the 'RKGist' project
//

#import <Availability.h>

#ifndef __IPHONE_5_0
#warning "This project uses features only available in iOS SDK 5.0 and later."
#endif

#ifdef __OBJC__
    #import <UIKit/UIKit.h>
    #import <Foundation/Foundation.h>
    #import <CoreData/CoreData.h>
#endif

#if __IPHONE_OS_VERSION_MIN_REQUIRED
    #import <SystemConfiguration/SystemConfiguration.h><commit_msg>Update TUTORIAL.md<commit_after># Getting Acquainted with RestKit
> _This guide is current as of RestKit **v0.20.0**._

This guide provides an introduction to the RestKit framework for iOS and Mac OS X. After reading it, you should have an understanding of the following topics:

1. What RestKit is and the benefits of adopting it for your next iOS or Mac OS X project.
2. How RestKit is designed and the philosophy of the library.
3. How to install RestKit into an application and begin interacting with a web service.
4. How RestKit interfaces with Core Data.
5. How RestKit provides abstractions for interacting with web service API's

## Guide Assumptions

This guide is designed for beginners who want to get started with a RestKit application from scratch. It does not assume that you have any prior experience with RestKit. It does, however, assume that the you have a basic understanding of Cocoa development and have some pre-requisites installed:

* [Xcode](https://itunes.apple.com/us/app/xcode/id497799835?mt=12) version >= 4.6
* [CocoaPods](http://cocoapods.org/) version >= 1.6.2

RestKit is a framework for implementing web service API client applications on iOS and Mac OS X in the Objective-C programming language. If you have no prior experience with Cocoa and Objective-C, then you will face a very steep learning curve if you attempt to dive straight into RestKit. It is recommended that you not attempt to drink the ocean by tackling Objective-C, Cocoa, and RestKit all at once. There are numerous resources available online for getting started with Cocoa development and this guide will be here once you have established a firm grounding in the basics of Cocoa development.

If you already have a handle on the basics of Cocoa development, then there are a few specific technologies and patterns that you will need to be familiar with in order to get the most out of this guide:

* [REST](http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm) - REST is an acronym for Representational State Transfer and describes an architectural pattern for implementing interapplication communication in distributed systems such as the World Wide Web. RestKit provides a set of tools for implementing RESTful client applications in Cocoa/Objective-C.
* [Key-Value Coding](http://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/KeyValueCoding/Articles/KeyValueCoding.html) - Key-Value coding is a mechanism for expressing indirect read/write access to properties by name. It is implemented as an informal protocol that is adopted by `NSObject` and underpins many Cocoa technologies such as key-value observation, Core Data, and bindings. KVC is the enabling technology for the object mapping system in RestKt.
* [NSOperation](http://developer.apple.com/library/mac/#documentation/Cocoa/Reference/NSOperation_class/Reference/Reference.html) - The `NSOperation` class is a Cocoa Foundation abstract class that encapsulates the code and data associated with a single task. Much of RestKit is implemented as `NSOperation` subclasses.
* [Core Data](http://developer.apple.com/library/mac/#documentation/cocoa/Conceptual/CoreData/cdProgrammingGuide.html) - Core Data is an object graph management and persistence framework provided by Apple with the Mac OS X and iOS SDKs. RestKit provides strong support for integrating a RESTful web service API with client-side persistence backed by Core Data.
* [Objective-C Runtime](https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/ObjCRuntimeGuide/Introduction/Introduction.html) - Objective-C is a highly dynamic language implemented on top of the C programming language. The runtime provides much of the dynamic functionality of the language. RestKit leverages many features of the runtime in the implementation of the object mapping engine. For the purposes of this guide, it is sufficient for the reader to simply be aware that Objective-C provides dynamic functionality such as runtime type inspection, declared property introspection, and message forwarding.
* [AFNetworking](http://afnetworking.org/) - AFNetworking is a "delightful networking library for iOS and Mac OS X". RestKit is implemented on top of the networking primitives provided by AFNetworking.

## What is RestKit?

> This section provides background and philosophy of RestKit in details. You can safely skip this section and come back to it at a later time. The next section begins the hand's on exploration of working with RestKit.

RestKit is a modern Objective-C framework for implementing RESTful web service client applications on iOS and Mac OS X. It is designed to make the development of your application easier by providing a system for binding your application's data model with the JSON or XML documents emitted by the web service you are communicating with. It enables you to write less code by shifting many application concerns into the library. It also speeds development by providing out-of-the-box solutions and patterns for tackling many common problems you will face when implementing your application -- particularly when integrating with Core Data. Experienced developers also find that RestKit enables a more satisfying and more maintainable code base because it encourages cleanliness and testability as core values.

RestKit is opinionated software. It makes a number of assumptions about your backend API and encourages the adoption of several design patterns in your Cocoa application code. Not every API is suitable for integration with RestKit -- particularly those that follow remote procedure call (RPC) semantics. When evaluating RestKit for use in your project, you should consider how closely your API and application design conform to the following assumptions:

* Your backend API is RESTful or at least "REST-ish". Interactions with your web application can be described in terms of resources and operations performed on those resources.
* Your backend API and your application's data model should be designed independently around what makes the most sense for each application. RestKit provides the tools for expressing the connection between these designs cleanly and simply.
* You think of your API in terms of objects that are accessed and manipulated, rather than requests made and responses processed. HTTP is a transfer medium and an implementation detail rather than a primary concern.
* Testability is a primary concern in your project. You believe in executable tests that verify behavior as a design and development tool. RestKit encourages the use of unit and functional testing for your application and provides tools for adopting a test-driven development style.

### RestKit Components

RestKit is shipped as a single library that is composed of several individual components collaborating to form a cohesive framework. Each component is designed with minimal dependencies and is usable as a standalone library. Each of these components is explained briefly below. Don't worry about attempting to understand the low-level details of each component now -- we'll explore each in detail later. For now, try to focus on the functionality provided by each component and grasp the layering of each component within the overall architecture.

#### Object Mapping

The Object Mapping component provides the lion's share of the functionality within RestKit. The Object Mapping system provides a mechanism for expressing the transformation of objects between representations using key-value coding and the dynamic features of the Objective-C runtime.

#### Networking

The Networking component provides integration between the Object Mapping component and HTTP networking primitives provided by AFNetworking. Services provided by the Networking component include the serialization and deserialization wire formats (such as JSON/XML), the binding of Object Mapping descriptions with HTTP requests and responses, the generation of URL's via routing, and the parameterization of local objects into HTTP parameters. This component includes many of the most used classes, such as the object manager and object request operation.

#### Core Data

The Core Data component provides integration between the RestKit Object Mapping and Networking components and Apple's Core Data modeling and persistence framework. This component mostly includes specialized implementations of classes provided by the Object Mapping and Networking layers, but also includes additional functionality specific to Core Data such as relationship connection descriptions.

##### Search

A subset of the Core Data component -- the Search component provides support for the indexing and searching of managed objects. The component includes a tokenizer, indexer, and convenience API's for generating search predicates that can be used to query indexed objects.

#### Testing

The Testing component includes several classes to make unit testing object mapping straightforward. Also included is a lightweight object factory implementation, which makes it easy to build reusable test fixtures. The testing classes are agnostic about the testing library you use and work easily with SenTest, Kiwi, Specta, Cedar, etc.

## Getting Up and Running

RestKit is distributed as a single library containing several sub-components. There are two supported installation methods:

1. [Automatic configuration via CocoaPods](https://github.com/RestKit/RestKit/wiki/Installing-RestKit-v0.20.x-via-CocoaPods) - This is the recommended approach as CocoaPods handles the linker flags, header paths, and download of source code dependencies on your behalf.
2. [Manual configuration as a submodule](https://github.com/RestKit/RestKit/wiki/Installing-RestKit-v0.20.x-as-a-Git-Submodule) - This method involves adding a submodule to your project and building RestKit as a dependency. You are responsible for configuring the project appropriately.

Before proceding with the tutorial, you should familiarize yourself with the installation method of your choosing.

## Creating the RKGist Application

The remainder of this guide is organized as a step-by-step tutorial designed to walk you through the basics of working with RestKit to implement access to an API. Each sections builds on its predecessors, so the best approach is to work through each section one at a time in the order presented. You can obtain a complete copy of the completed tutorial application [on Github](http://github.com/RestKit/RKGist).

By following this guide, you'll be creating an iOS application with RestKit called `RKGist`, a very simple client for [Github's Gist application](https://gist.github.com/). We've selected Gist for this tutorial because it is very well known, has a relatively simple API, and is very [well documented](http://developer.github.com/v3/gists/). We'll explore a large subset of the RestKit API's in a task based fashion, introducing new functionality and concepts as they enter the purview of the application being developed. 

### Creating the iOS Application

To begin creating the application, Open Xcode and select the "File" menu, then "New Project…". You will be presented with a new Xcode window displaying the template selection sheet. Select the "Master-Detail Application" template under the "iOS" and hit the "Next" button.

![Choose Project Template](Images/Xcode-Choose_Project_Template.png)

On the next screen, configure the options for your project by setting the *Product Name* to "RKGist", specifying a *Class Prefix* of "RKG" and then enabling the following options:

* Use Storyboard
* Use Core Data
* Use Automatic Reference Counting
* Include Unit Tests

Hit the "Next" button and save your new project to an appropriate place on disk.

![Configure Project Options](Images/Xcode-Configure_Project_Options.png)

### Installing RestKit via CocoaPods

Once your project has been created, you'll need to add RestKit to it using [CocoaPods](http://cocoapods.org/). To do so, open up your Terminal application and navigate to the location on disk where you saved the RKGist application. From there, install CocoaPods by executing the following commands on your Terminal:

```sh
$ [sudo] gem install cocoapods
$ pod setup
```
You can now add RestKit to your project by creating a new Podfile:

```sh
$ edit Podfile
```

Your favorite editor will open and allow you to configure your dependencies. Input the following into your Podfile:

```ruby
platform :ios, 6.0
target "RKGist" do
    pod 'RestKit', '~> 0.20.0rc'
# Include optional Testing and Search components
    pod 'RestKit/Testing', '~> 0.20.0rc'
    pod 'RestKit/Search', '~> 0.20.0rc'
end

# Import Expecta for Testing
target "RKGistTests" do
    pod 'Expecta', '0.2.1'
end
```

Invoke CocoaPods to install the dependencies:

```sh
$ pod install
```

CocoaPods will configure your project for use and create a new Workspace file. Open up `RKGist.xcworkspace` and then open the `RKGist-Prefix.pch` file from within the **RKGist** > **Supporting Files** group in the workspace. Set the files content to:

```objc
//
// Prefix header for all source files of the 'RKGist' target in the 'RKGist' project
//

#import <Availability.h>

#ifndef __IPHONE_5_0
#warning "This project uses features only available in iOS SDK 5.0 and later."
#endif

#ifdef __OBJC__
    #import <UIKit/UIKit.h>
    #import <Foundation/Foundation.h>
    #import <CoreData/CoreData.h>
#endif

#if __IPHONE_OS_VERSION_MIN_REQUIRED
    #import <SystemConfiguration/SystemConfiguration.h>
{'fraction_non_alphanumeric': 0.04993688275042697, 'fraction_numerical': 0.00408405732531373, 'mean_word_length': 4.886145104895105, 'pattern_counts': {'":': 0, '<': 13, '<?xml version=': 0, '>': 29, 'https://': 10, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4169839', 'n_tokens_mistral': 6531, 'n_tokens_neox': 6153, 'n_words': 3684}