Consume an API in Objective-C

Getting started

Every API can be consumed with an Objective-C client library, that is a wrapper around the JSON API .
The Objective-C client library is always made of two parts:

  • A Mashape folder, that contains the core functionalities of every Objective-C client library and that is immutable for every API.
  • Two auto-generated *.h and *.m files targeted for the specific API, that has "nearly" the same name of the API.

The client library automatically constructs the "X-Mashape-Authorization" header for every request, and deserializes the response into ready to use Objective-C objects.

Adding libicucore into your project

To use the Objective-C client library, you must link the libicucore library into your project.
To do that, double-click on the project icon in Groups & Files pane in Xcode and go to the Build tab of the Project Info window, go to the Linking sub-section of the tab, double click on the "Other Linker Flags" field and add -licucore to the flags using the popup window.

Initialize the library

To use the client library, include the auto-generated *.h file (located in the Classes directory) in your code. Then, initialize a new client object, whose class is defined in the auto-generated *.h file and has the same name of the *.h file. The constructor accepts two arguments, that are your Public and Private keys.

For example, if you download the Bitly API's Objective-C client library, you will get the following files:

|- Classes
   |- Mashape - The base Objective-C client folder.
   |- Bitly.h - The auto-generated header file for the API, that declares a Bitly class.
   |- Bitly.m - The auto-generated implementation for the API, that implements the Bitly class.
|- LICENSE
|- README

To initialize the client library instantiate a new Bitly object by executing initWithDeveloperKey method and setting your Public and Private keys in the constructor. For example:

Call a method

The client object exposes all the methods available for the API, that you can easily call. The methods may require some arguments (some of them may be optional), according to the API's documentation.

The execution of a method may throw a MashapeClientException when a fatal error occurs and the request failed (for example when the keys are not valid). A fatal error is different from a generic error, it means that the HTTP request wasn't successful for the following reasons:

  • You have provided invalid credential keys.
  • No or invalid response by the API.

You can handle the exception with its code and message value. The code is represented by a NSString object in the exception's name . Go to the errors section for more info.

For example, a sample client implementation for the Bitly component could be:

Read the response

Every method returns an object that wraps the JSON response that has the same structure like described in the API's documentation.

Handle the response according to the component's documentation. Remember that the response is an object.

Navigate through the response object

The Objective-C client library internally uses the json-framework library to deserialize a JSON response into ready to use objects.

Basically what you should know is how the JSON data is mapped in Objective-C:

  • Null -> NSNull
  • String -> NSMutableString
  • Array -> NSMutableArray
  • Object -> NSMutableDictionary
  • Boolean -> NSNumber (initialised with -initWithBool:)
  • Number -> NSDecimalNumber

As stated in the json-framework documentation, since Objective-C doesn't have a dedicated class for boolean values, these turns into NSNumber instances. These are initialised with the -initWithBool: method, and round-trip back to JSON properly. (They won't silently suddenly become 0 or 1; they'll be represented as 'true' and 'false' again.)

Asynchronous requests

The library natively supports asynchronous requests to the API. This is extremely useful when you don't want to wait for a response and continue the execution of your program without interfering.
To call an API's method asynchronously just pass an optional callback parameter object that implements the MashapeDelegate protocol. The method, instead of returning the API response returns a NSOperationQueue object. For example:

Sample.h Sample.m

The MashapeDelegate interface has two methods:

  • requestCompleted - Executed when the request is completed. It has an id response argument, that is the response of the API call. It may be a NSMutableArray or NSMutableDictionary object (depending if the method returns an array or not) according to the documentation.
  • errorOccurred - Executed when an error occurred. It has a MashapeClientException argument, that is the exception raised.

Errors

Like the JSON API, there may be API's custom errors or Mashape errors. See the errors section for more info.

Update the client library

It may happen we release a new version of the client library. It's a good practice to update your API's client library installations when a new version is available.

To update the library, delete the MashapeClient folder and replace it with the new one. Your implementation should keep working as usual.

If you are consuming more than one API with the client library, a tip could be to keep just one installation of the library (one MashapeClient folder) and move only the auto-generated *.h and *.m files for the new components you want to consume into the existing installation. In this way when you will have to update the client library to a newer version, replacing just one folder is all that's required.