Data services

Version 1.0 - March 2017

Changelog

  • Fixed outdated api to retrieve service

Introduction

One of the core steps of building a mobile application is sourcing data from different external sources. In practice, there are different options

  • REST endpoints (JSON over HTTP(S) )
  • MQTT endpoints (Use of MQTT messaging technology)
  • SOAP endpoints
  • proprietary endpoints

We describe some of the options in the following chapter

REST endpoint consumption

Consuming a REST http(s) endpoint is one of the most common scenarios. In this chapter, using the REST Service consumption wizard, we will show how to

  • Consume a REST HTTPS endpoint
  • Automatically parse JSON and generate Swift classes from it
  • Automatically generate client Swift code to call the endpoint
  • Call the REST Service and handle any kind of exception

In this example, we use a sample REST service that returns a list of dummy banking accounts. You can use it too, it's a simple REST endpoint on AWS:

https://aq5dv0hhp7.execute-api.us-west-2.amazonaws.com/prod/accounts

Executing this with username=demo and password=demo returns a JSON document

{
  "username": "flangel",
  "password": "12345",
  "timestamp": 8923487299,
  "accounts": [
    {
      "name": "Euro Checking",
      "id": 2389233812093238,
      "lastTransaction": 1417453332,
      "balance": 540,
      "currency": "EUR"
    },
    {
      "name": "Rent Saving",
      "id": 9032443412107340,
      "lastTransaction": 1420130032,
      "balance": 800,
      "currency": "USD"
    },
    {
      "name": "Frank's Checking",
      "id": 9032876412119872,
      "lastTransaction": 1425571626,
      "balance": 1200,
      "currency": "USD"
    }
  ]
}

So lets consume the same service in our mobile app:

Step 1 - Create the data service

One data service consists of many HTTP methods, i.e. different REST endpoints that you can call. We add one GET methods first:

  1. Select New | Service
  1. Give it a name of banking. This is name for all banking related REST endpoints
  2. As Request URL, specify the first REST endpoint that you want to consume
    • by convention, we combine the HTTP verb with the last part of the URL
    • so here, the Swift method that is generated becomes getAccounts
  1. Now click on "Invoke Remote Request" to execute the request
  1. Now click on Invoke Remote Request to execute the request
    The username/password is demo/demo.
  1. Click on Next as we will not configure request parameter
  1. Review the raw contents
  1. Review the model that has been generated
  • Use the type column to redefine types
  • Sometimes, for instance, you want to use a String type
    There is no need to do anything here, just click Finish
  1. Finally, press finish to create the structures
    This will take 5-10 seconds. After that the Swift structures have been created that reflect this JSON structure we retrieved from the REST endpoint:

Step 2 - Invoke the REST service

Now, all we need to do is to invoke the data service. Here a short snippet of code to invoke it.

import ScadeKit

class MainPageAdapter: SCDLatticePageAdapter {

	// page adapter initialization
	override func load(_ path: String) {		
		super.load(path)	
		
		// print name of all accounts
		let accounts = getAccounts()
		accounts.forEach {print($0.name)}
	}
	
	func getAccounts() ->  [Accounts] {
		
		// Get REST service reference
		let bankingService: banking! = SCDRuntime.loadService("banking.service")
		
		// Invoke service and get response
		let result : AccountsResponse = bankingService.getAccounts()
		
		// get accounts array
		return result.accounts
	}
}

When running it in the simulator, the accounts name are printed in the console

Current limitations

  1. We don't support JSON arrays, i.e. JSON documents beginning with [ at the moment. As a workaround, parse the JSON document manually or change the JSON data structure you retrieve.