Getting Started with the REST API Using iOS

Thu 19 December 2013 By Arnaud Kervern

As you may know, we just freed our first release of the iOS SDK to access our REST API. Before we blog about how to start a whole application with things like UIListView, we discuss the basics to get you started on something if you already are a UIKit compliant person.

Adding SDK to Any XCode Project

We recommend you use CocoaPods as your dependency management system to include our library. Do not hesitate to look at it deeper, it's good, you can eat it. To sum it up, after installing CocoaPods:

  • Add Nuxeo pods specs repository:

$ pod repo add nuxeo

  • Create a text file named Podfile with this content:

platform :ios, '7.0'
pod 'NuxeoSDK', :head

  • Execute pod to build the workspace, then open it:

$ pod
$ open MyProject.xcworkspace

Requesting a document

Instead of talking a lot before coding, let's start with something concrete:
NSURL url = [[NSURL alloc] initWithString:@"http://localhost:8080/nuxeo"];
// [1]
session = [[NUXSession alloc] initWithServerURL:url username:@"Administrator" password:@"Administrator"];
[session addDefaultSchemas:@[@"dublincore"]];

// [2]
NUXRequest request = [[NUXRequest alloc] initWithSession:session];
[[request addURLSegment:@"path"] addURLSegment:@"default-domain"];
// [3]
[request setCompletionBlock:^(NUXRequest
request) {
NSError error;
// [5]
doc = [request responseEntityWithError:&error];

[self doSomethingGreatWith:doc];
// [4]
[request start];

[1] Session initialisation

You can initialize a session from the init method, or by using the shared one filled with NUXSession-info.plist content. Session can also set default behaviors for further requests, such as if you want to get the dublincore schema for all requests; add it with addDefaultSchemas method.
-> NUXSession documentation

In this sample, we initialize a session binded to a server hosted on "http://localhost:8080/nuxeo", authenticated with default credentials and expecting to have the dublincore schema for all requests.

[2] Request

Requests are attached to a session, and let you access the REST API. You have access to some methods that hide URL construction, such as if you want to use an adaptor, to set a category. It also lets you set HTTP stuff like request headers, parameters, method, etc...
-> NUXRequest documentation

In this sample, we manually instantiate a request and add some URL segments to access the fetch document endpoint (/path/default-domain).

[3] Result blocks

We need to use blocks patterns, so we define two blocks: one when the request is successful, and the other if something goes wrong.

[4] Requests execution

You can start the request synchronously, or asynchronously, depending on what you need. Keep in mind to not block the UI thread.
-> NUXRequest documentation

In this sample, we forget to handle a failure case (I'm confident.) but the request is started asynchronously.

[5] Do something with the response

As soon as the remote server gives an answer, your block is called with the executed request filled with response data: responseStatusCode, responseMessage, response. You can access the response as bytes (if you love fighting with bytes), as an UTF8 encoded string, as a JSON dictionnary or as a NUXEntity.
-> Response handling documentation
-> NUXEntity mapping documentation

In this sample, we get the response as a NUXDocument which is a NUXEntity implementation for "document" entity-type response, and do "somethingGreatWith". We skip over error result ...

To Go Further

This is all for today. If you want to go further, you should take a look at the following links:

Category: Product & Development
Tagged: How to, REST API