Skip to content

Commit

Permalink
Updated README, it was too long. (still kinda is)
Browse files Browse the repository at this point in the history
  • Loading branch information
Steven Degutis committed Jun 26, 2009
1 parent e567b79 commit 4e40dc6
Showing 1 changed file with 31 additions and 98 deletions.
129 changes: 31 additions & 98 deletions README.md
View file
Expand Up @@ -2,52 +2,31 @@ CocoaREST - Cocoa Library
=========================

* Created by [Steven Degutis](http://degutis.org)
* Recently renamed yet again (this time for the final time, thank goodness!) to CocoaREST



What is CocoaREST?
==================

CocoaREST is a family of classes for the Cocoa (and Cocoa Touch) platforms, which allows developers to interact with RESTful APIs on the internet. There are two abstract superclasses:

* SDNetTaskManager

* Handles user-specified information (username, password, rate-limiting information, etc.) about the social network, and is necessary for running tasks
* The lifespan of this object is generally as long as your controller object

* SDNetTask

* Handles task-specific arguments and data (such as `statusID`, `page`, `text`, `count`, etc.)
* returns information from the service in the form of Cocoa classes (`NSDictionary`, `NSArray`, `NSNumber`, `NSString`, etc.)
* The lifespan of this object is generally very short, and it should rarely, if ever, be retained
* Runs in a separate thread when `-run` is called, and calls its delegate methods on the main thread when completed

There are several concrete subclasses of these two, which allow developers to interact with specific web APIs:

* `SDTwitterManager`/`SDTwitterTask`, interacts with Twitter.com (view [<http://apiwiki.twitter.com/REST+API+Documentation>](API))
* `SDIdenticaManager`/`SDIdenticaTask`, interacts with identi.ca (in progress!)
* `SDFriendfeedManager`/`SDFriendfeedTask`, interacts with Friendfeed.com (in progress!)

These classes have been designed specifically for developers to *easily* be able to extend the functionality of existing services by making minor adjustments inside these APi-specific class files, which is becoming a necessity these days with the way these APIs are rapidly changing.

CocoaREST is a family of classes for the Cocoa and Cocoa Touch platforms, which allows developers to interact with RESTful APIs on the internet.

Why use it?
===========

The CocoaREST family of Cocoa Classes are designed to be flexible, powerful, and incredibly simple and transparent to use. Here are just some advantages:
The basic workflow is something like this:

* Uses modern, up-to-date APIs. For example, SDTwitterTask uses "statuses/mentions" versus the archaic "statuses/replies"
* Instantiate a long-living object of a SDNetTaskManager subclass representing the service you want to use (ie SDTwitterTaskManager)
* Set its delegate, success and fail selectors, and any other properties the subclass may specify
* Instantiate a short-lived object of its counterpart SDNetTask subclass (ie SDTwitterTask)
* Set properties on this task object (which correspond to query arguments in the chosen RESTful service)
* Run the task and catch its results (or errors) in the 2 delegate methods

* Designed from the ground up to be easily maintainable and extendable by any developer, for extending current and implementing future RESTful APIs
It's really that simple. The key thing to remember are that @properties in both subclasses are usually representative of query arguments.

* Is built to support multiple services, including (but not limited to) Twitter, Identi.ca, and Friendfeed
Some features:

* Has large, automatic performance boosts, due to taking advantage of the modern technologies available in Mac OS X 10.5 Leopard, such as multi-threading (via NSOperation/Queue) and synthesized, atomic, thread-safe @properties
* `SDNetTasks` runs smoothly in background threads, and can even run simultaneously with other `SDNetTasks`
* Uses an optimized JSON parser to handle returned values stunningly quickly
* User experience is greatly improved, since the user will never see a spinning wheel due to a running Task
* Lightweight and easy to get started with
* Tasks are run asynchronously in background threads
* Easily extensible to support more services in the future (many are planned)
* Easily maintainable to support changes in currently supported services' APIs

* Requested returned values are returned in the format available for that specific API (either XML or JSON), and parsed with either `LibXML` or `YAJL`, which maximizes the number of supported services and API calls


Sample Code
Expand All @@ -71,7 +50,7 @@ Sample Code
// 3 tasks can be run simultaneously
manager.maxConcurrentTasks = 3;
// create a basic task
// create and run a basic task
SDTwitterTask *mentionsTask = [SDTwitterTask taskWithManager:manager];
mentionsTask.type = SDTwitterTaskGetPersonalTimeline;
mentionsTask.count = 3;
Expand All @@ -88,100 +67,54 @@ Sample Code
}


How to use CocoaREST
====================

Using `CocoaREST` is easy. The basic steps are:

Integrating CocoaREST into your app
===================================

1. Copy all the files from the Source directory, into your own project. For now, developers will need to link against the dynamic library libcrypto.dylib (which comes standard on all modern versions of Mac OS X and is available on the iPhone SDK as well).


2. Pick your a service-specific pair of subclasses, such as SDTwitterManager and SDTwitterTask, and #import their header files into whatever class you plan to use them in. The `AppDelegate.h` header file in the demo project is an example you can use.

2. Just follow the above example, peeking at the header files when necessary. Make sure to include the header for the specific Manager subclass you're using.

3. Implement the delegate methods you have chosen, just as the AppDelegate in the demo project does. Inside your delegate methods, you can access the Manager and Task objects to fully see the context surrounding `task.results`. For example, if you were implementing `SDTwitterTaskDelegate`, these are the methods you'd need to implement:

- (void) twitterManager:(SDTwitterManager*)manager resultsReadyForTask:(SDTwitterTask*)task;
- (void) twitterManager:(SDTwitterManager*)manager failedForTask:(SDTwitterTask*)task;

4. Create and `-run` some tasks! The Header files are very self-explanatory and well-documented. However, it is recommended that you take a look at the section below as well.



More in-depth explanation of usage
==================================

The bare basics that are required to request data from or send data to a social network, are as follows:

* Instantiate an object of a concrete `SDNetTaskManager` subclass (usually using `+manager`)

* Set its `delegate`, along with the `successSelector` and `failSelector`
* Read SDNetManager.h for information on what the signature of these selectors should look like
* Set its `username` and `password`, if any of your tasks will require authentication
* Optionally, you can set the specific Manager's settings. For instance, SDTwitterManager declares `appName`, `appVersion`, and `appWebsite`
* For more control, you can set the maximum tasks that can be run simultaneously, via the `maxConcurrentTasks` @property
* Be sure to look inside `SDNetTaskManager.h` as well as the header for your specific Manager subclass

* Instantiate an object of a concrete `SDNetTask` subclass (usually using `+taskWithManager:`)

* Set the task's `type` @property it should use (values are located in the Task subclass's header files)
* Set any required properties for the specified task (ie. `screenName`, `text`, or `statusID`)
* Check the Task subclass's header file for a list of writable properties, and types of services/tasks

* Run the task via `[task run]`, which runs asynchronously
CocoaREST and the iPhone
========================

* Implement the Task's specific delegate methods to handle any returned data
* After every SDTwitterTasks, its `SDTwitterManager` object will have new rate-limiting information set on it. You can reliably et this data from the `SDTwitterManager` @properties `limitMaxAmount`, `limitRemainingAmount`, and `limitResetEpochDate`, whenever necessary. They will always reflect the real-time limiting information inside the delegate methods
* The `results` @property of the task object will contain returned information from the social networking service.
* Once a task has completed, it will deallocate on its own. It should not be retained, and cannot be run a second time (as it is an NSOperation subclass).
This project doesn't use any classes which are unavailable on the iPhone SDK, excepting NSColor (a UIColor counterpart coming soon!). The `YAJL` C library's source code (under the Source dir) works just fine when compiled against the iPhone SDK. Thus, `CocoaREST` is perfectly suitable for use on the iPhone SDK.



A note on threads and performance
=================================

`SDNetTask` objects are run in separate threads in the background, to both increase performance and improve the user's experience. However, despite any worries this may invoke, the vast majority of use-cases should not worry about thread-safety, since all delegate methods are called on the main thread, and the task waits until the delegate is finished before continuing execution in the background thread. Thus, it is perfectly safe to access any @properties on the task from the main thread, after the task has completed. This allows you to implement such functionality as iterating through the returned values and storing them in a Core Data context, without worrying about data corruption at all.


`SDNetTask` objects are run in separate threads in the background, to both increase performance and improve the user's experience. However, despite any worries this may invoke, the vast majority of use-cases should not worry about thread-safety, since the delegate methods are always called on the main thread, and the task waits until the delegate is finished before continuing execution in the background thread. Thus, it is perfectly safe to access any @properties on the task from the main thread, after the task has completed. This allows developers to implement such functionality as iterating through the returned values and storing them in a Core Data context, without worrying about data corruption at all.

A note about the format of returned values
==========================================

You may get any kind of ObjC type in the `results` property, anything from `NSArray` to `NSDictionary`, `NSString` to `NSNumber`, etc. Because of the JSON parser, these results (or the objects in a collection) may not always be of the classes you might expect. So be sure to ask for a value's `-class` when testing the services.

UUIDs: For backwards-compatibility with `MGTwitterEngine`, each Task object creates its very own a unique string identifier (or UUID) inside `-init`. These unique string identifiers are compatible with `MGTwitterEngine`'s and may be used as keys in dictionaries if you so desire. However, they are deprecated, to be removed in the (hopefully near) future. If anything, the task itself should be stored in a collection, but usually this is not necessary, as each task encapsulates sufficient information inside it for determining any contextual information needed to understand the returned data.


Compatibility with MGTwitterEngine
==================================

Creating a subclass-pair of SDNetTaskManager/Task
=======================================================
Most (if not all) MGTwitterEngine code should work just fine with CocoaREST.

Coming soon!
**UUIDs:** For compatibility with MGTwitterEngine, each Task object creates its very own a unique string identifier (or UUID) inside `-init`. These unique string identifiers are compatible with MGTwitterEngine's and may be used as keys in dictionaries if you so desire. However, they are deprecated, to be removed in the (hopefully near) future. If anything, the task itself should be stored in a collection, but usually this is not necessary, as each task encapsulates sufficient information inside it for determining any contextual information needed to understand the returned data.



Other people's Source Code used in this project
===============================================

This code requires the aforementioned `NSString` and `NSData` files, which are borrowed directly from `MGTwitterEngine`. Similarly, this README file and the Source Code license borrowed heavily from their `MGTwitterEngine` counterparts.

The class `SDNetTask` uses JSON parsing (and will support XML in the near future). The JSON library used is `yajl` (written in C), and was written by Lloyd Hilaiel. For more information about `yajl`, visit <http://lloyd.github.com/yajl/>
This code requires the aforementioned `NSString` and `NSData` files, which are borrowed directly from MGTwitterEngine. Similarly, this README file and the Source Code license borrowed heavily from their MGTwitterEngine counterparts.

The class `SDNetTask` uses JSON parsing (and will support XML in the near future). The JSON library used is [`yajl`](http://lloyd.github.com/yajl/) (written in C), and was written by Lloyd Hilaiel.


CocoaREST and the iPhone
===========================

This project doesn't use any classes which (as far as I know) are unavailable on the iPhone SDK, excepting NSColor (a UIColor counterpart coming soon!). Similarly, the `YAJL` C static library works just fine when compiled against the iPhone SDK. Thus, `CocoaREST` is perfectly suitable for use on the iPhone SDK.


Standard ending of a README
===========================
Heartfelt Goodbyes
==================

That's about it. If you have trouble with the code, or want to make a feature request or report a bug (or even contribute some improvements), you can get in touch with me using the info below. I hope you enjoy using CocoaREST!

`Steven Degutis`
Sincerely, `Steven Degutis`

* Web: <http://degutis.org>
* AIM: `stevendegutis`
Expand Down

0 comments on commit 4e40dc6

Please sign in to comment.