README.md in afmotion-0.9.0 vs README.md in afmotion-2.0.0.rc1

- old
+ new

@@ -16,30 +16,55 @@ end ``` ### Web Services -If you're interacting with a web service, you can use `AFHTTPClient` with this nice wrapper: - ```ruby -# DSL Mapping to properties of AFHTTPClient -AFMotion::Client.build_shared("https://alpha-api.app.net/") do - header "Accept", "application/json" +@client = AFMotion::... # create your client - operation :json -end - -AFMotion::Client.shared.get("stream/0/posts/stream/global") do |result| +@client.get("stream/0/posts/stream/global") do |result| if result.success? - p result.object + p (result.operation || result.task) # depending on your client elsif result.failure? p result.error.localizedDescription end end ``` +You can either use `AFMotion::Client` or `AFMotion::SessionClient` to group similar requests. They have identical APIs, except for their creation and that their request `result` objects contain either `result.operation` (for `::Client`) or `result.task` (for `::SessionClient`). + +#### AFMotion::Client + +If you're interacting with a web service, you can use [`AFHTTPRequestOperationManager`](http://cocoadocs.org/docsets/AFNetworking/2.0.0/Classes/AFHTTPRequestOperationManager.html) with this nice wrapper: + +```ruby +# DSL Mapping to properties of AFHTTPRequestOperationManager + +@client = AFMotion::Client.build("https://alpha-api.app.net/") do + header "Accept", "application/json" + + response_serializer :json +end +``` + +#### AFMotion::SessionClient + +If you're using iOS7, you can use [`AFHTTPSessionManager`](http://cocoadocs.org/docsets/AFNetworking/2.0.0/Classes/AFHTTPSessionManager.html): + +```ruby +# DSL Mapping to properties of AFHTTPSessionManager + +@client = AFMotion::SessionClient.build("https://alpha-api.app.net/") do + session_configuration :default + + header "Accept", "application/json" + + response_serializer :json +end +``` + ### Images Loading images from the internet is pretty common. AFNetworking's existing methods aren't bad at all, but just incase you want extra Ruby: ```ruby @@ -64,22 +89,10 @@ 1. `gem install afmotion` 2. `require 'afmotion'` or add to your `Gemfile` -3. In your `Rakefile`, add: - -```ruby -Motion::Project::App.setup do |app| - ... - - app.pods do - pod 'AFNetworking' - end -end -``` - ## Overview ### Results Each AFMotion wrapper callback yields an `AFMotion::HTTPResult` object. This object has properties like so: @@ -102,26 +115,10 @@ p result.error.localizedDescription end end ``` -### Operations - -There are wrappers for each `AFURLConnectionOperation` subclass, each of the form: - -```ruby -AFMotion::Operation::[Operation Type].for_request(ns_url_request) do |result| - ... -end -``` - -- `AFMotion::Operation::HTTP.for_request...` -- `AFMotion::Operation::JSON.for_request...` -- `AFMotion::Operation::XML.for_request...` -- `AFMotion::Operation::PLIST.for_request...` -- `AFMotion::Operation::Image.for_request...` - ### One-off Requests There are wrappers which automatically run a URL request for a given URL and HTTP method, of the form: ```ruby @@ -144,27 +141,47 @@ - `AFMotion::PLIST.get/post/put/patch/delete(url)...` - `AFMotion::Image.get/post/put/patch/delete(url)...` ### HTTP Client -If you're constantly accesing a web service, it's a good idea to use an `AFHTTPClient`. Things lets you add a common base URL and request headers to all the requests issued through it, like so: +If you're constantly accesing a web service, it's a good idea to use an `AFHTTPRequestOperationManager`. Things lets you add a common base URL and request headers to all the requests issued through it, like so: ```ruby client = AFMotion::Client.build("https://alpha-api.app.net/") do header "Accept", "application/json" - operation :json + response_serializer :json end client.get("stream/0/posts/stream/global") do |result| + # result.operation exists ... end ``` +If you're using iOS7, you can use [`AFHTTPSessionManager`](http://cocoadocs.org/docsets/AFNetworking/2.0.0/Classes/AFHTTPSessionManager.html): + +```ruby +# DSL Mapping to properties of AFHTTPSessionManager + +client = AFMotion::SessionClient.build("https://alpha-api.app.net/") do + session_configuration :default + + header "Accept", "application/json" + + response_serializer :json +end + +client.get("stream/0/posts/stream/global") do |result| + # result.task exists + ... +end +``` + If you're constantly used one web service, you can use the `AFMotion::Client.shared` variable have a common reference. It can be set like a normal variable or created with `AFMotion::Client.build_shared`. -`AFHTTPClient` supports methods of the form `AFHTTPClient#get/post/put/patch/delete(url, request_parameters)`. The `request_parameters` is a hash containing your parameters to attach as the request body or URL parameters, depending on request type. For example: +`AFHTTPRequestOperationManager` & `AFHTTPSessionManager` support methods of the form `Client#get/post/put/patch/delete(url, request_parameters)`. The `request_parameters` is a hash containing your parameters to attach as the request body or URL parameters, depending on request type. For example: ```ruby client.get("users", id: 1) do |result| ... end @@ -174,18 +191,18 @@ end ``` #### Multipart Requests -`AFHTTPClient` supports multipart form requests (i.e. for image uploading). Simply prepend `multipart!` to any other request method and it'll convert your parameters into properly encoded multipart data: +`AFHTTPRequestOperationManager` & `AFHTTPSessionManager` support multipart form requests (i.e. for image uploading) - simply use `multipart_post` and it'll convert your parameters into properly encoded multipart data. For all other types of request data, use the `form_data` object passed to your callback: ```ruby # an instance of UIImage image = my_function.get_image data = UIImagePNGRepresentation(image) -client.multipart!.post("avatars") do |result, form_data| +client.multipart_post("avatars") do |result, form_data| if form_data # Called before request runs # see: https://github.com/AFNetworking/AFNetworking/wiki/AFNetworking-FAQ form_data.appendPartWithFileData(data, name: "avatar", fileName:"avatar.png", mimeType: "image/png") elsif result.success? @@ -194,21 +211,24 @@ ... end end ``` +This is an instance of [`AFMultipartFormData`](http://cocoadocs.org/docsets/AFNetworking/2.0.0/Protocols/AFMultipartFormData.html). + If you want to track upload progress, you can add a third callback argument which returns the upload percentage between 0.0 and 1.0: ```ruby -client.multipart!.post("avatars") do |result, form_data, progress| +client.multipart_post("avatars") do |result, form_data, progress| if form_data # Called before request runs # see: https://github.com/AFNetworking/AFNetworking/wiki/AFNetworking-FAQ form_data.appendPartWithFileData(data, name: "avatar", fileName:"avatar.png", mimeType: "image/png") elsif progress - # 0.0 <= progress <= 1.0 + # 0.0 < progress < 1.0 my_widget.update_progress(progress) + else ... end ``` #### Headers @@ -224,28 +244,17 @@ client.headers.delete "Accept" #=> "application/something_else" ``` -#### Client Operations - -If you want to grab an `AFURLConnectionOperation` from your client instance, use `create_operation` or `create_multipart_operation`: - -```ruby -operation = client.create_operation(:get, "http://google.com", {q: "hello"}) do |result| -end - -multipart_operation = client.create_multipart_operation(:get, "http://google.com", {q: "hello"}) do |result, form_data, progress| -end - -# elsewhere -client.enqueueHTTPRequestOperation(operation) -``` - #### Client Building DSL -The `AFMotion::Client` DSL allows the following properties: +The `AFMotion::Client` & `AFMotion::SessionClient` DSLs allows the following properties: - `header(header, value)` - `authorization(username: ___, password: ____)` for HTTP Basic auth, or `authorization(token: ____)` for Token based auth. -- `operation(operation_type)`. Allows you to set a common operation class for all your client's requests. So if your API is always going to be JSON, you should set `operation(:json)`. Accepts `:json`, `:plist`, `:xml`, or `:http` -- `parameter_encoding(encoding)`. Allows you to set a body format for requests parameters. For example, when you send a POST request you might want the parameters to be encoding as a JSON object instead of the traditional `key=val` format. Accepts `:json`, `:plist`, and `:form` (normal encoding). +- `request_serializer(serializer)`. Allows you to set an [`AFURLRequestSerialization`](http://cocoadocs.org/docsets/AFNetworking/2.0.0/Protocols/AFURLRequestSerialization.html) for all your client's requests, which determines how data is encoded on the way to the server. So if your API is always going to be JSON, you should set `operation(:json)`. Accepts `:json` and `:plist`, or any instance of `AFURLRequestSerialization`. +- `response_serializer(serializer)`. Allows you to set an [`AFURLResponseSerialization`](http://cocoadocs.org/docsets/AFNetworking/2.0.0/Protocols/AFURLResponseSerialization.html), which determines how data is decoded once the server respnds. Accepts `:json`, `:xml`, `:plist`, `:image`, `:http`, or any instance of `AFURLResponseSerialization`. + +For `AFMotion::SessionClient` only: + +- `session_configuration(session_configuration, identifier = nil)`. Allows you to set the [`NSURLSessionConfiguration`](https://developer.apple.com/library/ios/documentation/Foundation/Reference/NSURLSessionConfiguration_class/Reference/Reference.html#//apple_ref/occ/cl/NSURLSessionConfiguration). Accepts `:default`, `:ephemeral`, `:background` (with the `identifier` as a String), or an instance of `NSURLSessionConfiguration`. \ No newline at end of file