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:

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. 

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.

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.

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'
end

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

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.

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

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.

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.

Figure 10: method definition

The method getCalculateAsyncWithGetCalculateInput() takes two arguments:

GetCalculateInput

A wrapper class that contains an operation enum, and two double vatiables

CompletedGetCalculate

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.

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 = ..... 

Go to top

Download here: Sample app setup with CocoaPods