Rocking With Kii!

Hello World,

For the past couple of weeks I’ve been having a lot of fun playing around in Kii. No, I’m not talking about the former province in Japan nor am I refering to the Hawaiian deity (actually spelled Ki’i). The Kii that I speak of is a Backend as a Service (known as BaaS) by a company of the same name. What exactly is Kii?

The Kii Cloud enables developers to focus on application development and leave the User and Data Management, Analytics, Monetization, and Push Notification services to the Kii Cloud though the use of APIs and SDKs. Kii already provides APIs, Guides, and Sample Code for IOS, Android, and Javascript-based platforms as well as a REST implementation. The Javascript implementation was easy to learn and implement but my desire was to see if I could use the Kii Cloud from within a Corona SDK app. And By Golly … Yes I Can!

In this post I will show you how to sign up for an account on Kii and then show you some sample code you can use in your Corona app.

SignUp

Signing up for a Kii Cloud account easy and you can get started for free! If you haven’t already sign up for an account by going to their site: http://www.kii.com

Create Your First App

After you have successfully signed up for an account you are now ready create your first Kii Cloud app! once you sign into Kii and you will be taken to the Developer Portal in your account. Click on the Create App button to begin the process of creating your first app.

Specify App Properties

A new dialog will appear enabling you to specify your new app properties. You will enter the Kii app name, select United States (unless you live in Japan or China), and select the radio button next to the HTML5 icon.

App Dashboard

Your new Kii app will now appear in your App Dashboard. From here you will be able to see statistics and other related information about your app.

App ID and KEYS

Your new Kii Cloud app will will be assigned several alphanumeric ids and keys. To view those keys click on your new Kii Cloud app from your App Dashboard. Once you have entered your Kii Cloud app screen find and click on the Access Keys button on the top right section of the screen.

Doing this will display a popup showing your App ID, App Key, Client ID, and Client Secret. The only two you need to be concerned with are the App ID and App Key.

Copy and paste those two values into a text editor. You will need them later.

Your Corona SDK App

Now we’re ready to take a look at some of the sample code that will enable you to communicate with your Kii Cloud app.

I found that the easiest and most direct way to interact with the Kii Cloud from a Corona SDK app was to use the RESTful API. The network.request method enabled us to just that.

Here is some Corona (Lua) code used to SignUp a user using the Kii RESTful API

local function userSignUp( obj )
	if (not obj.loginName or not obj.password or not obj.email) then
print("Missing login data")
	else
		local baseURL = "https://api.kii.com/api/apps/"
		local appId = "????????" -- Your AppId
		local appKey = "????????????????????????????????" -- Your AppKey

		local headers = {}
		headers["content-type"]		= "application/vnd.kii.RegistrationRequest+json"
		headers["x-kii-appid"]		= appId
		headers["x-kii-appkey"]		= appKey

		local params = {}
		params.headers = headers
		params.body = value.encode ( obj )

		network.request( _BASEURL .. appId .. "/users", "POST", networkListener,  params)
	end
end

The method above expects one parameter: a Lua table containing keys and values. The key/values that it expects are: loginName, password, and email. Although this Kii API method does not require all three of these values I am validating their existence just for this example.

The base URL used for all your calls to the Kii Cloud (unless you live in Japan or China) is assigned to the baseURL variable.

Remember the App ID and App Key you copied earlier? Now you can copy and pasted those values into your code and assign them to the appId and appKey variables.

If you take a look at the Kii Cloud documentation (http://documentation.kii.com/en/guides/rest/) you will see examples calls to each of their API methods. The REST API documentation shows examples using CURL. CURL is a command line tool used to transfer data to a or from a networked server. You can get more information about CURL here – http://curl.haxx.se/docs/manpage.html.

curl -v -X POST \
-H "content-type:application/vnd.kii.RegistrationRequest+json" \
-H "x-kii-appid:{APP_ID}" \
-H "x-kii-appkey:{APP_KEY}" \
"https://api.kii.com/api/apps/{APP_ID}/users" \
-d '{"loginName":"user_123456", "email":"user@123456.com"}'

We are then able to translate this command line call into a Lua code by assigning the three Headers (the three -H values) to the three Lua variables. Then we assign the headers to a params table variable. The obj parameter (passed into the function) is then stored in the params table variable.

Finally the network.request method is called, passing in the entire URL (a concatenation of the _BASEURL, appId, and the remaining portion of the URL). The network.request method is an asynchronous method. This means that your Corona code will continue to execute until it is notified of the Kii Cloud method completion. This is the purpose of the next argument, networkListener. This is the callback method that is used to handle the response. You can get more information about the network.request method here: http://docs.coronalabs.com/api/library/network/request.html

function networkListener( response )
	if not response.errorCode then
		print("response.access_token: " .. response.access_token)
	else
		print("response.errorCode: " .. response.error_description)
	end
end

Once the Kii Cloud REST API method is completed it will call the networkListener method shown above. An object containing information about the call will be passed into your callback method. In this sample code we are only interested in either the access_token (which is used in many of the subsequent calls) or the errorCode.

Here is a sample call to userSignUp method described above.

userSignUp( {loginName=obj.testUser, password=obj.testPassword, email=obj.testEmail} )

As you see we are able to create a new user in our Kii Cloud app using the simple and straightforward code shown above. In fact I had so much fun working with the Kii Cloud API that I decided to write an entire library containing all the calls to the REST API. Once completed I will release the library into the “developer wild” for anyone to use. Keep your eye on this blog as I will post a link to the library source very soon.

CIAO