Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 129 lines (88 sloc) 10.189 kb
6ec59255 »
2010-02-17 Added styling and links to Google Group
1 Introduction
2 =========================
bd3f5591 »
2009-08-08 First cut at a README.
3
5e8b7e85 »
2011-07-01 Updating README
4 RestKit is a Cocoa framework for interacting with RESTful web services in Objective C on iOS and Mac OS X. It provides a set of primitives for interacting with web services wrapping GET, POST, PUT and DELETE HTTP verbs behind a clean, simple interface. RestKit also provides a system for modeling remote resources by mapping them from JSON (or XML) payloads back into local domain objects. Object mapping functions with normal NSObject derived classes with properties. There is also an object mapping implementation included that provides a Core Data backed store for persisting objects loaded from the web.
3178b15f »
2010-04-06 Removed references to ElementParser (XML support has been removed) an…
5
2d9c774e »
2011-06-20 Removed dead link to blog post.
6 RestKit was first publicly introduced in April of 2010.
6ec59255 »
2010-02-17 Added styling and links to Google Group
7
f3f09ab3 »
2010-10-01 Rewrote the README to reflect the new realities.
8 To get started with installation, skip down the document below the Design & Dependencies section.
9
10 Design
11 -------------------------
12
5e8b7e85 »
2011-07-01 Updating README
13 RestKit is composed of three main components: **Network**, **Object Mapping**, and **Core Data**. Each layer provides a higher level of abstraction around the problem of accessing web services and representing the data returned as an object. The primary goal of RestKit is to allow the application programmer to think more in terms of their application's data model and less about the details of fetching, parsing, and representing resources. Functionally, each piece provides...
f3f09ab3 »
2010-10-01 Rewrote the README to reflect the new realities.
14
15 1. **Network** - The network layer provides a request/response abstraction on top of NSURLConnection. The main interface for the end developer is the *RKClient*, which provides an interface for sending GET, POST, PUT, and DELETE requests asynchronously. This wraps the construction and dispatch of *RKRequest* and *RKResponse* objects, that provide a nice interface for working with HTTP requests. Sending parameters with your request is as easy as providing an NSDictionary of key/value pairs. File uploading support from NSData and files is supported through the use of an *RKParams* object, which serializes into a multipart form representation suitable for submission to a remote web server for processing. SSL & HTTP AUTH is fully supported for requests. *RKResponse* objects provide access to the string of JSON parsed versions of the response body in one line of code. There are also a number of helpful method for inspecting the request and response such as isXHTML, isJSON, isRedirect, isOK, etc.
5e8b7e85 »
2011-07-01 Updating README
16 1. **Object Mapping** - The object mapping layer provides a simple API for turning remote JSON/XML responses into local domain objects declaratively. Rather than working directly with *RKClient*, the developer works with *RKObjectManager*. *RKObjectManager* provides support for loading a remote resource path (see below for discussion) and calling back a delegate with object representations of the data loaded. Remote payloads are parsed to an NSDictionary representation and are then mapped to local objects using Key-Value Coding. Any KVC compliant class can be targeted for object mapping. RestKit also provides support for serializing local objects back into a wire format for submission back to your remote backend system. Local domain objects can be serialized to JSON or URL Form Encoded string representations for transport. To simplify the generation of URL's that identify remote resources, RestKit ships with an object routing implementation that can
17 generate an appropriate URL based on the object and HTTP verb being utilized. Object mapping is a deep topic and is explored thoroughly in the [Object Mapping Design Document].
18 1. **Core Data** - The Core Data layer provides additional support on top of the object mapper for mapping from remote resources to persist local objects. This is useful for providing offline support, holding on to transient data, and speeding up user interfaces by avoiding expensive trips to the web server. The Core Data support requires that you initialize an instance of *RKManagedObjectStore* and assign it to the *RKObjectManager*. RestKit includes a library of extensions to NSManagedObject that provide an Active Record pattern on top of the Core Data primitives. See the Examples/ subdirectory for examples of how to get this running. The Core Data support also provides *RKManagedObjectSeeder*, a tool for creating a local "seed database" to bootstrap an object model from local JSON files. This allows you to ship an app to the store that already has data pre-loaded and then synchronize with the cloud to keep your clients up to date.
f3f09ab3 »
2010-10-01 Rewrote the README to reflect the new realities.
19
20 ### Base URL and Resource Paths
21
22 RestKit utilizes the concepts of the Base URL and resource paths throughout the library. Basically the base URL is a prefix URL that all requests will be sent to. This prevents you from spreading server name details across the code base and repeatedly constructing URL fragments. The *RKClient* and *RKObjectManager* are both initialized with a base URL initially. All other operations dispatched through these objects work of a resource path, which is basically just a URL path fragment that is appended to the base URL before constructing the request. This allows you to switch between development, staging, and production servers very easily and reduces redundancy.
23
43227e3f »
2010-10-01 Cleanups for github flavored markdown
24 Note that you can send *RKRequest* objects to arbitrary URL's by constructing them yourself.
f3f09ab3 »
2010-10-01 Rewrote the README to reflect the new realities.
25
15d291bc »
2011-12-09 Moved OS X headers to Public/ and updated README.md
26 Parsers
6ec59255 »
2010-02-17 Added styling and links to Google Group
27 -------------------------
bd3f5591 »
2009-08-08 First cut at a README.
28
15d291bc »
2011-12-09 Moved OS X headers to Public/ and updated README.md
29 RestKit provides a pluggable parser interface configurable by MIME Type. The standard RestKit distribution includes two parsers:
f3f09ab3 »
2010-10-01 Rewrote the README to reflect the new realities.
30
15d291bc »
2011-12-09 Moved OS X headers to Public/ and updated README.md
31 1. **RKJSONParserJSONKit** - A very fast JSON parser leveraging [JSONKit](http://github.com/johnezang/JSONKit)
32 1. **RKXMLParserLibXML** - A custom LibXML2 based parser. Only provides parsing, not serialization.
10146563 »
2011-07-03 modified README.md to allow the #import lines to be recognized as a c…
33
15d291bc »
2011-12-09 Moved OS X headers to Public/ and updated README.md
34 The JSONKit headers can be imported for direct use:
f3f09ab3 »
2010-10-01 Rewrote the README to reflect the new realities.
35
15d291bc »
2011-12-09 Moved OS X headers to Public/ and updated README.md
36 ```objc
37 #import <RestKit/JSONKit.h>
38 ```
4bf924cc »
2010-10-01 Slight tweak for YAJL/SBJSON list
39
15d291bc »
2011-12-09 Moved OS X headers to Public/ and updated README.md
40 Additional parsers can be added to your RestKit application by linking the parsers into your application and configuring it to handle the appropriate
41 MIME Type:
e5100bd7 »
2010-10-19 Removed dependency on regexkitlite
42
15d291bc »
2011-12-09 Moved OS X headers to Public/ and updated README.md
43 ```objc
44 [[RKParserRegistry sharedRegistry] setParserClass:[SomeOtherParser class] forMIMEType:@"application/json"]];
45 ```
f3f09ab3 »
2010-10-01 Rewrote the README to reflect the new realities.
46
15d291bc »
2011-12-09 Moved OS X headers to Public/ and updated README.md
47 The RestKit project also provides optional additional parsers that can be installed separately from the main library:
bd3f5591 »
2009-08-08 First cut at a README.
48
15d291bc »
2011-12-09 Moved OS X headers to Public/ and updated README.md
49 1. [**RKJSONParserSBJSON**](https://github.com/RestKit/RKJSONParserSBJSON) - A JSON parser built on top of SBJSON
50 1. [**RKJSONParserYAJL**](https://github.com/RestKit/RKJSONParserYAJL) - A JSON parser built on top of YAJL)
51 1. [**RKJSONParserNXJSON**](https://github.com/RestKit/RKJSONParserNXJSON) - A JSON parser built on top of the Nextive JSON parser
bd3f5591 »
2009-08-08 First cut at a README.
52
f3f09ab3 »
2010-10-01 Rewrote the README to reflect the new realities.
53 Documentation & Example Code
54 -------------------------
55
56 Documentation and example code is being added as quickly as possible. Please check the Docs/ and Examples/ subdirectories to see what's available. The [RestKit Google Group](http://groups.google.com/group/restkit) is an invaluable resource for getting help working with the library.
57
462cf35b »
2011-04-14 Implemented Rake tasks for generating documentation via Appledoc very…
58 RestKit has API documentation available on the web. You can access the documentation in several ways:
59
60 1. Online in your web browser. Visit http://restkit.org/api/
43fd38ee »
2011-04-15 Changed URL to feed:// to work with Xcode 3.x. refs #48
61 1. Directly within Xcode. Visit your Xcode Preferences and view the Documentation tab. Click + and add the RestKit feed: feed://restkit.org/api/org.restkit.RestKit.atom
462cf35b »
2011-04-14 Implemented Rake tasks for generating documentation via Appledoc very…
62 1. Generate the documentation directly from the project source code. Run `rake docs` to generate and `rake docs:install` to install into Xcode
63
6ec59255 »
2010-02-17 Added styling and links to Google Group
64 Installation
f3f09ab3 »
2010-10-01 Rewrote the README to reflect the new realities.
65 =========================
66
8bc44444 »
2011-02-16 Xcode 4 specific install instructions
67 Quick Start (aka TL;DR)
68 -----------
69
a11c9999 »
2011-11-23 Added CoreData.h import to main RestKit header. Updated quick start i…
70 RestKit assumes that you are using a modern Xcode project building to the DerivedData directory. Confirm your settings
71 via the "File" menu > "Project Settings...". On the "Build" tab within the sheet that opens, click the "Advanced..."
72 button and confirm that your "Build Location" is the "Derived Data Location".
73
bc33f3ff »
2011-07-18 README links for submodules updated.
74 1. Add Git submodule to your project: `git submodule add git://github.com/RestKit/RestKit.git RestKit`
976942d0 »
2011-02-16 Updates to quick start section
75 1. Add cross-project reference by dragging **RestKit.xcodeproj** to your project
8bc44444 »
2011-02-16 Xcode 4 specific install instructions
76 1. Open build settings editor for your project
c2e8932c »
2012-02-13 Simplified to a single header search path
77 1. Add the following **Header Search Paths** (including the quotes): `"$(BUILT_PRODUCTS_DIR)/../../Headers"`
563f5e90 »
2011-11-23 Updated all example projects to build against the new project. Cleane…
78 1. Add **Other Linker Flags** for `-ObjC -all_load`
976942d0 »
2011-02-16 Updates to quick start section
79 1. Open target settings editor for the target you want to link RestKit into
80 1. Add direct dependency on the **RestKit** aggregate target
8bc44444 »
2011-02-16 Xcode 4 specific install instructions
81 1. Link against required frameworks:
0e498ad3 »
2012-03-30 Added note that CFNetwork is only required on iOS. fixes #615
82 1. **CFNetwork.framework** on iOS
7496355b »
2011-02-16 Trying to get formatting right for Github flavored markdown
83 1. **CoreData.framework**
563f5e90 »
2011-11-23 Updated all example projects to build against the new project. Cleane…
84 1. **Security.framework**
a29182a2 »
2011-10-17 Added note about CoreServices.framework on OS X
85 1. **MobileCoreServices.framework** on iOS or **CoreServices.framework** on OS X
976942d0 »
2011-02-16 Updates to quick start section
86 1. **SystemConfiguration.framework**
07cdf1f0 »
2011-03-01 update projects to link libxml2 (verified working). Update readme to …
87 1. **libxml2.dylib**
e775fcda »
2012-03-20 Add QuartzCore to the Quick Start section. fixes #607
88 1. **QuartzCore.framework** on iOS
563f5e90 »
2011-11-23 Updated all example projects to build against the new project. Cleane…
89 1. Link against RestKit:
90 1. **libRestKit.a** on iOS
91 1. **RestKit.framework** on OS X
976942d0 »
2011-02-16 Updates to quick start section
92 1. Import the RestKit headers via `#import <RestKit/RestKit.h>`
93 1. Build the project to verify installation is successful.
8497da78 »
2010-02-17 README Update
94
d2aab62c »
2011-09-03 Removed existing install guide and replaced with link to the wiki ins…
95 Visual Install Guide
8bc44444 »
2011-02-16 Xcode 4 specific install instructions
96 -------------------------
97
d2aab62c »
2011-09-03 Removed existing install guide and replaced with link to the wiki ins…
98 An step-by-step visual install guide for Xcode 4.x is available on the RestKit Wiki: https://github.com/RestKit/RestKit/wiki/Installing-RestKit-in-Xcode-4.x
8497da78 »
2010-02-17 README Update
99
663a7d47 »
2011-11-10 Added announcements mailing list to README
100 Community Resources
6ec59255 »
2010-02-17 Added styling and links to Google Group
101 -------------------------
102
663a7d47 »
2011-11-10 Added announcements mailing list to README
103 A Google Group (high traffic) for development discussions and user support is available at: [http://groups.google.com/group/restkit](http://groups.google.com/group/restkit)
47d7c905 »
2010-02-17 Fixed linking
104
13810798 »
2012-03-20 Added note about filing bug reports and feature requests on Github
105 The preferred venue for discussing bugs and feature requests is on Github Issues. The mailing list support traffic can be overwhelming
106 for our small development team. Please file all bug reports and feature requests at: <https://github.com/RestKit/RestKit/issues>
107
663a7d47 »
2011-11-10 Added announcements mailing list to README
108 For users interested in low traffic updates about the library, an announcements list is also available:
109 [http://groups.google.com/group/restkit-announce](http://groups.google.com/group/restkit-announce)
6ec59255 »
2010-02-17 Added styling and links to Google Group
110
8dbd8c5d »
2010-10-27 remove www
111 Follow RestKit on Twitter:[http://twitter.com/restkit](http://twitter.com/restkit)
61e1d1f1 »
2010-10-27 Added Twitter link
112
663a7d47 »
2011-11-10 Added announcements mailing list to README
113 Contributing
114 -------------------------
115
116 Forks, patches and other feedback are always welcome.
117
95c6cdda »
2011-10-14 Add line break below credits
118 Credits
119 -------------------------
120
663a7d47 »
2011-11-10 Added announcements mailing list to README
121 RestKit is brought to you by [Blake Watters](http://twitter.com/blakewatters) and the RestKit team.
27afe218 »
2011-10-14 Updating credits to show GateGuru some love
122
123 Support is provided by the following organizations:
124
125 * [GateGuru](http://www.gateguruapp.com/)
126 * [Two Toasters](http://www.twotoasters.com/)
5e8b7e85 »
2011-07-01 Updating README
127
570b13ca »
2011-07-23 Updated Object Mapping documentation, added support for inferring obj…
128 [Object Mapping Design Document]: https://github.com/RestKit/RestKit/blob/master/Docs/Object%20Mapping.md
Something went wrong with that request. Please try again.