Overview

LUAPIClient is used to perform requests to the LevelUp API.

Setup

Before using LUAPIClient, it must be set up with a valid API key. This is done with setupWithAppID:APIKey:.

Issuing Requests

The method performRequest:success:failure: is used to issue requests to the LevelUp’s REST API. It performs these requests in the background, and then handles the responses. If the request is successful, the success block is called, passing in the result of the API call. If an error occurs, the failure block is called with an appropriate NSError.

A API request is an instance of LUAPIRequest which has been generated using a request builder class. See the documentation for the request builder for information on specific API calls.

Authentication

When a user logs in, an access token is provided along with the user’s ID. LUAPIClient needs to be given these values so that they can be included in API calls which require an authenticated user. Once stored, these values will be securely stored so that they will persist between application launches.

Development Mode

You can configure the SDK to run in “Development Mode” by configuring the SDK using setupWithAppID:APIKey:developmentMode: or by setting developmentMode to YES. When in Development Mode, all API requests will go to the LevelUp Sandbox server rather than the production API server. The Sandbox server allows you to test the API without charging any money. When in Development Mode, make sure your App ID and API Key are associated with a Sandbox App, configured at https://www.thelevelup.com/developer/sandbox/apps.

Errors

When an API call fails, the failure block passed to performRequest:success:failure: will be called with an NSError object containing additional information about the error. This error will have the domain LUAPIErrorDomain.

Codes

See LUAPIErrorCode in LUConstants.h for a list of possible error codes.

User Info

The userInfo dictionary for this NSError has keys for several pieces of information:

• LUAPIErrorKeyAPIErrors: An optional array of LUAPIError objects returned by the server.
• LUAPIErrorKeyErrorMessage: An optional error message from the server. If multiple errors were returned, this will only contain the first message. LUAPIErrorKeyAPIErrors can be used to see all errors.
• LUAPIErrorKeyJSONResponse: An optional JSON response from the server.
• LUAPIErrorKeyOriginalError: If this error was generated from another NSError, it is included under this key.
• LUAPIErrorKeyURLResponse: An NSURLResponse containing the response.

Example

LUAPIRequest *request = [LUUserRequestFactory requestForCurrentUser];
[[LUAPIClient sharedClient] performRequest:request
                                   success:^(LUUser *user) {
                                     NSLog(@"The current user is %@", user);
                                   }
                                   failure:^(NSError *error) {
                                     NSLog(@"Got an error: %@", error);
                                   }];