iOS - Cloudant NoSQL DB API
This tutorial shows how to apply technology available in IBM MobileFirst Platform Foundation to store data for iOS mobile applications. By using Cloudant NoSQL DB APIs, you can complete specific database operations, such as creating, reading, updating, deleting, and synchronizing data between local and remote databases. This tutorial provides a basic overview of these APIs and explains how to configure and run the sample, in the following topics:
- Using the IMFData SDK
- Creating local data stores
- Creating remote data stores
- Setting user permissions for remote stores
- Modeling data for iOS applications
- Creating and updating data
- Supporting synchronization and offline storage
- Running the iOS sample
- Obtaining and configuring the required SDKs
- BlueList application flow
Using the IMFData SDK
After the IMFData SDK is installed, you can begin to initialize and use the SDK in your native iOS application.
The value for
cloudantProxyUrl is the URL of the MobileFirst Data Proxy as it was configured during installation. The URL includes the IP address, host, and context root that you defined.
In the native iOS sample that comes with this tutorial, the value for the
cloudantProxyUrl is set in the
Creating local data stores
You can create a Store object to allow your application to access a local database, which can be used even when the application is offline.
Creating remote data stores
You can also create a Store object to allow your application to access a remote database.
Setting user permissions for remote stores
You can set specific permissions for users to access remote stores.
Note: In the sample, the user is authenticated via OAuth. OAuth has been configured through adapter-based authentication. You can find further instructions on setting up access with OAuth capabilities and the MobileFirst Data Proxy in configuring OAuth security documentation.
Modeling data for iOS applications
In iOS applications, you can use the
CDTDataObjectMapper class to map native objects to the JSON document format. When you create a data store with the
IMFDataManager API, a
CDTDataObjectMapper is created automatically and is set on the
CDTStore object. In the sample, a custom
TodoItem class enables you to store custom data as objects in the application. When you create a custom
CDTDataObjectMapper class, make sure that it meets the following requirements:
- Conform to the
- Have the
IMFDataObjectprotocol metadata property set on the class interface.
TodoItem implementation (
You must then register the class and data type with the
CDTDataObjectMapper. In the sample, the
TableViewController does that after the store is created.
Creating and updating data
Using the same operation, you can save new objects and save changes to existing objects in a data store.
Creating Todo Items
Updating Todo Items
To delete an object in a data store, pass the object to the
delete: completionHandler method:
You can query for objects that have an object mapper. The Cloudant query API provides convenient methods for querying with
NSPredicate and for querying by data type. For more information about these functions, see Querying data in the user documentation.
Supporting synchronization and offline storage
By using the data manager API, you can synchronize data between local storage on the device and remote stored instances.
When pull replication runs, the local database within the mobile device is updated with what exists in the remote database.
When push replication runs, the data from the local database within the mobile device is sent to the remote database.
Note: The code snippets above might be different from the code that you can see in the sample. These snippets have been created to give the clearest and most understandable outline of the APIs and how they are used. For the sample to be easier to use, all the implementation for the above operations can be found in the
Running the iOS sample
Make sure that you have properly configured and started the following instances:
- MobileFirst Server with
iOSBlueListNative API deployed
- Cloudant Data Local Layer Edition
- MobileFirst Data Proxy Server configured against MobileFirst Server and the Cloudant Data Layer Local Edition
If you have not completed some of these tasks, review the proper setup section of the Working with Cloudant NoSQL DB API tutorial.
Obtaining and configuring the required SDKs
- Make sure that you have correctly installed and set up CocoaPods. If you have not done so, complete the following:
- Install CocoaPods by entering the following terminal command:
- Set up CocoaPods by entering the following terminal command:
The next step is to download and install the required dependencies for this project by using the provided
Podfile. If you want to create or have your own
podfile, include the following content:
- Install CocoaPods by entering the following terminal command:
podfile, navigate to the Xcode project directory in terminal (in the sample:
/mfp-bluelist-on-premises/iOS/objective-c/) and run the following command:
$ pod install
Note: For the
pod install command to work correctly, your
podfile must be named
bluelist-objective-c.xcworkspacefile. When using CocoaPods, you must use the
.xcworkspacefile instead of the
.xcodeprojectfile because of how the dependencies are configured.
- In the
bluelist.plistfile, set the
cloudantProxyUrlto your MobileFirst Data Proxy Server location.
- In the
worklight.plistfile, make sure to check all the values and update them to match the MobileFirst Server instance that you have deployed.
Now you can run the sample on the simulators that are provided by Xcode or on a supported iOS device.
BlueList application flow
When the application starts, the
AppDelegate instance initializes the connection to MobileFirst Server. After initialization, the application creates and registers the
The sample silently authenticates a user by calling
CloudantAutheticationAdapter with the correct username and password parameters. This is completed in the
After authentication, the database is configured in the
setupIMFDatabase method in the
TableViewController. This database configuration consists of the following steps:
- Initializing the SDK
- Creating the local and remote databases.
- Setting permissions for the user that was created.
- Setting the
- Registering the
TodoItemclass and data type with the
Note: For simplicity, the name of the database that gets created is currently set to the variable
IBM_DB_NAME in the
TableViewController. By design, the
setupIMFDatabase method allows you to pass any database name as a parameter.
TableViewController class provides functions for creating, updating, deleting, and listing items, and functions for push and pull replication.
After completing initialization, the application does an initial pull from the remote database. The user can now add, delete, and modify list items in the application, and update the corresponding priority (red = high, yellow = medium, white = low). By design, the application starts synchronization only when the user manually pulls down the list. On pull down, the application first completes a pull replication from the remote database to the local. After this operation has completed, push replication occurs, which sends any updated local data to the remote database. The local and remote databases are then synchronized.