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:
- Setting up the environment
- SDK generation instructions
- SDK installation instructions via CocoaPods
- SDK installation instructions via static framework
- 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.
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.
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.
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.
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.
This will update your project with the new SDK as shown in Figure 5.
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.
- Open terminal and go to the unarchived directory.
- Run command "pod install" (without the quotes), as shown in Figure 6.
- A new file named "APIMATICCalculator.xcworkspace" will be created as a result.
- Open the "APIMATICCalculator.xcworkspace" in XCode.
- Change the build target: Product -> Schema and select "Framework"
- 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.
- Open "Calculator.xcodeproj". This will open your project in Xcode.
- 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.
- Ensure that the framework is linked to your app, as shown in Figure 8.
- Add the linker flag for static frameworks : 'all_load', as shown in Figure 9.
- Build the project to confirm correct referencing of the framework.
Figure 7: copying SDK to our project
Figure 8: linking the project
Figure 9: adding linker flags
You are now ready to use the library in your code.
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:
- 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.
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 = .....
Figure 12: result