Using your generated iOS SDK

This article is now deprecated. SDK usage instructions are now contained in the generated SDK.

See the new APIMATIC docs.

In this article, we will walk you through the generation of the SDK and how to use it.

The following covers the following aspects:

  1. Setting up the environment
  2. SDK generation instructions
  3. SDK installation instructions via CocoaPods
  4. SDK installation instructions via static framework
  5. Using the SDK on our app

1. Setting up the environment:

Following this tutorial here, a library is already generated, downloaded, and ready for use.

We will be using Xcode IDE. You should have the following tools installed:

  • Xcode v7.0 (7A220) or greater
  • Cocoapods : 0.38.2 or greater

2. SDK generation instructions:

After choosing iOS platform, as shown in Figure 1, a zipped file will be downloaded. This file contains the code for the APIMATICCalculator library we will be using in our project. 

Image not found
Figure 1: Choosing iOS platform.


3. SDK installation instructions via CocoaPods:

CocoaPods is a popular dependency manager for Swift and Objective-C Cocoa projects. The following steps help you integrate with an existing project setup with CocoaPods. You can download a sample app setup with CocoaPods here.


Image not found
Figure 2: CocoaPods sample project directory.


As shown in Figure 2, the project directory has a "Podfile" where the dependency of our project are defined and a "Vendor" folder where we should copy our SDK to.


3.1 Copying the SDK into the project

Create a new folder named "APIMATICCalculator" inside your "Vendor" folder. 

Copy the contents of your SDK into Vendor/APIMATICCalculator, as shown in Figure 3.

Image not found
Figure 3: Copying SDK to Vendor folder.


3.2 Define the SDK as a dependency

In order to use our SDK, we need to add its dependency to our "Podfile". Edit the "Podfile" in the root of our project as follows:

target 'Calculator' do
    pod 'APIMATICCalculator', :path => 'Vendor/APIMATICCalculator'


Figure 4 shows how your "Podfile" should look like after adding the code.

Image not found
Figure 4: Podfile.


3.3 Build the app with the new dependency

Open a terminal at the root of the project and execute the following command.

pod install

This will update your project with the new SDK as shown in Figure 5.

Image not found
Figure 5: pod install.


You are now ready to use the library in your code. Proceed to step 5


4. SDK installation instructions via static framework:

The SDK can also be used in your project by building a static library. This is done in a two step process: Building the framework, and then referencing the generated static library.

4.1 Building the framework

The following set of instructions will briefly walk you through the steps.

  1. Open terminal and go to the unarchived directory.
  2. Run command "pod install" (without the quotes), as shown in Figure 6.
  3. A new file named "APIMATICCalculator.xcworkspace" will be created as a result.
  4. Open the "APIMATICCalculator.xcworkspace" in XCode.
  5. Change the build target: Product -> Schema and select "Framework"
  6. Invoke build command (command + B). By default the generated framework is copied to your desktop and is named: APIMATICCalculator.framework

Image not found
Figure 6: pod install

4.2 Referencing the library in your project

You can download a sample app to go along with the instructions below.

  1. Open "Calculator.xcodeproj". This will open your project in Xcode.
  2. Simply drag & drop the "APIMATICCalculator.framework" from your desktop to your project directory. Ensure 'copy items if needed' is checked, as shown in Figure 7.
  3. Ensure that the framework is linked to your app,  as shown in Figure 8. 
  4. Add the linker flag for static frameworks : 'all_load', as shown in Figure 9.
  5. Build the project to confirm correct referencing of the framework.
Image not found
Figure 7: copying SDK to our project


Image not found
Figure 8: linking the project 


Image not found
Figure 9: adding linker flags


You are now ready to use the library in your code.

5. Using the SDK in our app:

In steps 3 and 4, we displayed two different ways to reference the SDK in our app.

The following steps illustrate how to invoke the code embedded in our SDK. In order to use your library,we need to instantiate a controller, and invoke a method on it.

Figure 10 shows the method we want to invoke. Lets quickly examine the method signature.


Image not found
Figure 10: method definition

The method getCalculateAsyncWithGetCalculateInput() takes two arguments:

A wrapper class that contains an operation enum, and two double vatiables
A block definition that will be executed once the call has been made

Note: You might wonder why the arguments are contained in a wrapper object? This is because "Collect parameters" is enabled in our code generation settings. This will dynamically create a new class to represent the parameters required by the endpoint. This is really nifty when you have a large number of arguments and want to keep the method signature simple.

Now go to your "ViewController.m"
Figure 11 shows how your "ViewController.m" should look like after adding the necessary code.

Image not found
Figure 11: invocation

Lets take a quick look at each of the arguments of the completion block:

BOOL - Success
This is "True" if the call was successful, and "False" otherwise
HTTPContext - Context
This represents the raw request and responses. It is useful when you want to examine response headers
NSNumber - response
The parsed response from the server. This can be nil if success is false
NSError - error
This contains information about the failure of the request. Can be nil

Lets run the app!
1+2 = ..... 

Image not found
Figure 12: result


Go to top

Download here: Sample app setup with CocoaPods

Have more questions? Submit a request