Creating applications that use REST services
Your application programs can use REST services either synchronously or asynchronously.
Synchronous execution
When a service is used synchronously, the request is processed immediately, and the response
contains the result. This is appropriate for short-running operations that return a relatively small
amount of data. For example, the following call requests the list of employees
immediately.
def run_sync():
url = "https://%s:50050/v1/services/listemployees/1.0" % (restHostname)
headers = {
"content-type": "application/json",
"authorization": token
}
json = {
"sync": True
}
response = requests.post(url, verify = False, headers = headers, proxies = None, json = json)
if response.status_code == 200:
pprint(response.json())
The content of each row of the
resultSet
section of the output is determined by
the service
description.{
'jobStatus': 4,
'jobStatusDescription': 'Job is complete'"
'resultSet': [
{'EMPID': '10001', 'FIRSTNAME': 'John', 'LASTNAME': 'Doe'},"
{'EMPID': '10002', 'FIRSTNAME': 'Mary', 'LASTNAME': 'Jones'}
],
'rowCount': 2
}
A job can have one of the following statuses:
- 0
- The attempt to run the job failed.
- 1
- The job is queued.
- 2
- The job is running.
- 4
- The job completed.
- 5
- The job was canceled and is stopping.
Asynchronous execution
When a service is used asynchronously, the request is processed as a batch job, and the
response contains a job ID. The job ID can be used to query the job status and, after the job
completes, to obtain the result. This is appropriate for long-running operations, or when coding a
progress indicator for a user
interface.
def run_async():
url = "https://%s:50050/v1/services/listemployees/1.0" % (restHostname)
headers = {
"content-type": "application/json",
"authorization": token
}
json = {
"sync": False
}
response = requests.post(url, verify = False, headers = headers, proxies = None, json = json)
if response.status_code == 202:
job_id = response.json()["id"]
print("Job started asynchronously with id:", job_id)
You can use the returned job ID to retrieve the results.
def run_fetch_async(id):
url = "https://%s:50050/v1/services/%s" % (restHostname, job_id)
headers = {
"content-type": "application/json",
"authorization": token
}
json = {
"limit": 1000,
}
response = requests.get(url, verify = False, headers = headers, proxies = None, json = json)
pprint(response.json())
Each call to run_fetch_async
returns status information and, if output data is
available, that output data. Each successive call returns the next batch of records until the output
data is fully retrieved.
When data is available, the response looks like
this:
{'MonitorServices': [{'jobID': '3b125fed-de4d-4789-b9f2-7d6d8eaec817',
'jobStatus': 3,
'jobStatusDescription': 'Job has data available',
'serviceExecuter': 'bluadmin',
'serviceName': 'DEMO1',
'startTime': '2020-02-20T08:34:47.073092-05:00',
'version': '1.0'}]}
The output of the call includes the job ID. To retrieve the output, call
run_fetch_async_all(job_id)
with that job ID, for
exampledef run_fetch_async('3b125fed-de4d-4789-b9f2-7d6d8eaec817')
{
'jobStatus': 4,
'jobStatusDescription': 'Job is complete'"
'resultSet': [
{'EMPID': '10001', 'FIRSTNAME': 'John', 'LASTNAME': 'Doe'},"
{'EMPID': '10002', 'FIRSTNAME': 'Mary', 'LASTNAME': 'Jones'}
],
'rowCount': 2
}
A job can have one of the following statuses:
- 0
- The attempt to run the job failed.
- 1
- The job is queued.
- 2
- The job is running.
- 3
- Data is available. For example, if an asynchronous request returns 2500 records, but a request limits each response to at most 1000 records, the request status changes to 3 when the first response, containing the first 1000 records, is received. The request remains in status 3 until the final response, containing the final 500 records, is received, at which time the request status changes from 3 to 4.
- 4
- The job completed.
- 5
- The job was canceled and is stopping.
The following function uses the
jobStatus
states to determine whether the
specified job is queued, is running, or has
completed.def run_fetch_async_all(job_id):
url = "https://%s:50050/v1/services/%s" % (restHostname, job_id)
headers = {
"content-type": "application/json",
"authorization": token
}
json = {
"limit": 1000,
}
response = requests.get(url, verify = False, headers = headers, proxies = None, json = json)
if response.status_code == 200:
result = response.json()
jobStatus = result["jobStatus"]
if jobStatus == 1:
print("Job is queued")
elif jobStatus == 2:
print("Job is running")
elif jobStatus == 3 or jobStatus == 4:
print("Fetched", result["rowCount"], "rows")
pprint(result["resultSet"])
# We're still waiting or there's still more data to fetch.
if jobStatus < 4:
response = requests.get(url, verify = False, headers = headers, proxies = None, json = json)
else:
pprint(response.json())