23 Calling APIs from Custom Code
As a service developer, you might want to access platform APIs, connector APIs, and other custom APIs from your custom code. The custom code SDK provides methods that simplify making requests to these APIs.
Note that the purpose of the examples in this chapter is to illustrate how to interface with the custom code service. The examples are not intended to teach best practices for writing Node.js REST API implementations.
Send Requests to Platform, Connector, and Custom APIs
You use custom code SDK methods to send requests to platform, custom, and connector APIs. When you call one of these methods, that method makes a RESTful HTTP call to the API. This SDK makes the HTTP calls mostly transparent to you, but you’ll see that a method's arguments and its return value are similar to what you would see with a RESTful HTTP request and response.
The SDK methods follow a common request pattern. There are two response patterns – stream and promise.
API Request Pattern
The custom code SDK methods that make requests to custom, platform, and connector APIs follow this pattern:
req.oracleMobile.<service>.<method>(required arguments, options, httpOptions)
The <service>
identifies the API that you want to call.
-
For platform APIs, this is the name of the platform, such as
storage
,ums
, ornotification
. -
For connector APIs, this can be either
connectors
orconnectors.<api>
. Later, we discuss how to choose which one to use. -
For custom APIs, this can be either
custom
orcustom.<api>
. Later, we discuss how to choose which one to use.
You use options
to specify optional API-specific properties. The next section discusses the options
properties that are shared by many of these methods. Each method description in the subsequent sections discusses additional options
properties that apply to that method, if any.
The httpOptions
argument is like the Node.js http.request(options)
argument. You use this argument to pass properties not covered by required arguments and options
. For example, if you need to pass the timeout
property to specify the number of milliseconds to wait for a request to respond before terminating the request, then you would pass it in httpOptions
. Another example of when you use httpOptions
is to pass query parameters to a connector. To learn more about http.request(options)
, go to the API documentation at https://github.com/request/request
and scroll down to the section entitled "request(options, callback)".
Tip:
When you usehttpOptions.qs
to pass the query string, you can use encodeURIComponent(<string>)
for the qs
value to ensure that your code handles multibyte characters.
You can omit the options
and httpOptions
arguments. When you do so, they are treated as null values. Any value that you provide in options
that affects a parameter in httpOptions
overrides the httpOptions
parameter. The methods ignore any property in the options
and httpOptions
arguments that they do not support.
You might notice that you don’t need to worry about authentication when you send requests to custom, platform, and custom APIs from custom code. The service re-uses the access token that’s passed into the custom code and takes care of authentication for you. With connectors, if you need to use different credentials for the external service, you can use options.externalAuthorization
to pass the value to be used in the Authorization
header for the external service.
If you need to send direct requests to third-party web services without going through a connector, use a Node API such as the HTTP API.
API Response Patterns
The return value for a custom code SDK call to an API depends on the value of the options.outType
property.
-
If the
outType
isstream
, then, if there’s no error, the return value is a stream that you can pipe. -
If the
outType
is undefined or any value other thanstream
, then the return value is a promise object.
Handle a Stream
When the response is a stream
, then, if there’s no error, the return value is a stream that you can pipe. Otherwise, you can process the error as shown in this example:
req.oracleMobile.storage.store('attachments', req, {
mobileName: 'Technician Notes',
contentType: req.header('content-type'),
inType: 'stream',
outType: 'stream'
})
.on('error', function (error) {
res.status(error.status).send(error.message);
})
.on('response', function (response) {
console.info('HEADERS received from response:', response.headers);
})
.pipe(res);
For more information about streaming, see https://github.com/request/request
.
Handle a Promise
A promise provides access to the result of an asynchronous request. At the time a promise is returned, the request may or may not have completed. Most custom code SDK methods return promises. In the following examples, <promiseFunction>
represents a custom code SDK method that returns a promise, such as req.oracleMobile.storage.getCollections
.
When you call a promise function, you typically use the then
function to handle the success or failure as shown here:
<promiseFunction>.then(successFunction, errorFunction)
-
<promiseFunction>
is the call that returns a promise, such asreq.oracleMobile.storage.getCollections
in the next code example. -
successFunction
is a user-defined function that is called if the prior promise function resolves successfully. This occurs when the request completes with a response status code less than400
. ThesuccessFunction
takes a single argument, which is what the prior<promiseFunction>
returned on success. With custom code SDK methods, this is a JSON object with the following properties:-
result
: The body of the result. -
statusCode
: The HTTP status code. -
headers
: A JSON object that contains all the HTTP response headers, such as{accept-charset:'UTF-8',content-type:'application/json'}
. -
contentType
: The value of theContent-Type
header if that header was included in the response. -
contentLength
: The value of theContent-Length
header if that header was included in the response.
-
-
errorFunction
is a user-defined function that is called if and when promise function doesn’t resolve successfully. This is when the response status is equal to or greater than400
, or if there is a severe error. TheerrorFunction
takes a single argument, which is what the<promiseFunction>
returned on error. With custom code SDK methods, this is a JSON object with the following properties:-
statusCode
: The HTTP status code. -
error
: The body of the error or the error message. -
headers
: All the response HTTP headers.
-
The then
function takes an optional progressFunction
argument. However, the custom code SDK doesn’t use this argument, and you can omit it from the call.
Here’s an example of how to call a custom code SDK method to access a custom, platform, or connector API and use then
to handle the promise that it returns. In this example:
-
In this example, the
<promiseFunction>
isreq.oracleMobile.storage.getCollections
. This is a function from the storage component of the custom code SDK, which either resolves with a successful promise or rejects with an error promise. -
If
getCollections
completes successfully, then it passes the successful promise to the first argument forthen
, which isfunction(result)
. -
If
getCollections
results in an error, then it passes the error promise to the second argument, which isfunction(error)
.
// Get metadata about the backend's collections.
service.get('/mobile/custom/incidentreport/collections',
function (req, res) {
req.oracleMobile.storage.getCollections({sync: true}).then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
});
A promise and its result can be assigned to a variable. This means that the result can live longer than the function call alone, allowing you to chain multiple success and failure functions calls against the result. For example, you can write code like this:
var collections = req.oracleMobile.storage.getCollections({sync: true});
collections.then(successFunction1, errorFunction1);
...
collections.then(successFunction2, errorFunction2);
Because the custom code SDK uses the Bluebird promises library, we recommend that you use this library to process these promises. If you only use the then()
function from the promises library, you don’t need to include Bluebird in your package.
There are several promise libraries that you can choose from for your custom code implementation, but the extent to which they will work with the custom code SDK promises is not known. To learn more about Bluebird promises, go to https://github.com/petkaantonov/bluebird
.
Invoke Calls Synchronously
When you need to invoke a series of calls in a synchronous manner, waiting for one operation to complete before starting the next one, then you can take advantage of the fact that most custom code SDK methods return a promise. A promise handles some of the complexity of making synchronous calls in an asynchronous environment like Node, and provides a simple way to handle both success and failure cases through callback methods.
The simplest way to extract the result of a promise is to use the then
function. In your custom code, you can provide two arguments to the then
function.
-
A function to invoke on success, which takes a single argument – the success promise.
-
A function to invoke on error, which takes a single argument – the error promise.
Here’s an example of using the then
function to handle the result of a promise function. As you can see, it has two arguments:
-
function(result)
, which sends thegetById
result. -
function(error)
, which sends the error message.
service.get('/mobile/custom/incidentreport/attachments/:id',
function (req, res) {
req.oracleMobile.storage.getById('attachments', req.params.id, {sync: true}).then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
});
When you need to call more than one API operation from a route definition, you can use then
to chain the calls, so that one call completes successfully before the next one is called. In this example, the route definition:
-
Posts an incident to the database and returns the result.
-
If the post completes successfully, gets the user info.
-
If the user info is retrieved successfully, posts an analytics event.
Notice that none of the then
functions take a second argument (the error function). If an error (rejected) promise is passed to a then
function that doesn’t have a second argument, then the code skips to the first then
function with a second argument. In this example, because there aren’t any, all errors trickle to the catch
function.
service.post('/mobile/custom/incidentreport/incidents',
function (req, res) {
/* Post the incident and send the response.
* Then, if the post was successful,
* get the username,
* then use the username to post an event.
*
**/
postIncident()
.then(getUser)
.then(postEvent)
.catch(function (errorResult) {
console.warn(errorResult);
});
function postIncident() {
return req.oracleMobile.database.insert('FIF_Incidents', req.body)
.then(
function (successResult) {
res.status(successResult.statusCode).send(successResult.result);
// By default, Bluebird wraps this with a
// resolved promise
return {status: "resolved"};
},
function (errorResult) {
res.status(errorResult.statusCode).send(errorResult.error);
throw errorResult;
}
);
};
function getUser() {
return req.oracleMobile.ums.getUser({fields: 'username'});
};
function postEvent(successResult) {
var userName = successResult.result.username;
/*
* Record the NewIncident event
*/
var timestamp = (new Date()).toISOString();
// Events are posted as an array
var events = [];
// Put events in context
events.push(
{name: 'context',
type: 'system',
timestamp: timestamp,
properties: {userName: userName}
});
// Start the session
events.push(
{name: 'sessionStart',
type: 'system',
timestamp: timestamp
});
// Add the custom event:
events.push(
{name: 'NewIncident',
type: 'custom',
component: 'Incidents',
timestamp: timestamp,
properties: {customer: req.body.customer}
});
// End the session:
events.push(
{name: 'sessionEnd',
type: 'system',
timestamp: timestamp
});
// Post the batch of events. Apply the passed-in session ID to all.
// The postEvent result is returned by this function
return req.oracleMobile.analytics.postEvent(
events,
{sessionId: req.header('oracle-mobile-analytics-session-id')});
};
});
Invoke Calls Asynchronously
Promise.join
lets you make several asynchronous calls and then use the results after all calls are complete. The promise that the join returns is an array of the results.
For example, the following code makes three calls to the incidentreport
custom API to get information for the result body. After all calls complete successfully, the then
function’s success handler extracts the necessary information to compile the result, and then sends it.
Note that the join
functions aren’t necessarily called in the order in which they occur in the code. The only guarantee is that all the join
functions successfully complete before a success promise is returned.
/* Promise.join example
*
* Promise.join takes multiple promises as arguments.
* If all promises succeed, then it returns a promise
* that holds an array of the results of the promises.
*/
var Promise = require("bluebird");
module.exports = function(service) {
...
service.get('/mobile/custom/incidentreport/join/:custId/:incidentId/:techId', function (req, res) {
// Three functions that return promises.
var customer = req.oracleMobile.custom.incidentreport.get(
"customers/" + req.params.custId, {outType: 'json'});
var incident = req.oracleMobile.custom.incidentreport.get(
"incidents/" + req.params.incidentId, {outType: 'json'});
var technician = req.oracleMobile.custom.incidentreport.get(
"technicians/" + req.params.techId, {outType: 'json'});
Promise.join(customer, incident, technician).then(
function (joinResult) {
// Anonymous handler that's called if all 3 promises succeeded.
// Harvest a piece of data from each promise result.
var report = {
customerContact: joinResult[0].result.email,
description: joinResult[1].result.title,
technicianContact: joinResult[2].result.email};
res.type('application/json');
res.status(200).send(report);
},
function (error) {
// Anonymous handler to handle errors
console.info(error);
res.status(error.statusCode).send(error.error);
}
);
})
...
}
Invoke a Dynamic Set of Calls
Use Promise.all
when you have a dynamic set of calls and you must wait until all calls complete before you take some action. If any of the promises in the array don’t succeed, then the returned promise is rejected with the reason for rejection.
/* Promise.all example
*
* Promise.all takes an array of promises as an argument (promiseArray).
* If all promises succeed, then it returns a promise that holds
* an array of the results from the promiseArray's promises.
*/
var Promise = require("bluebird");
module.exports = function(service) {
...
service.get('/mobile/custom/incidentreport/all/:custId/:incidentId/:techId', function (req, res) {
// Put the functions that return promises in the array
promiseArray = [];
promiseArray.push(req.oracleMobile.custom.incidentreport.get(
"customers/" + req.params.custId, {outType: 'json'}));
promiseArray.push(req.oracleMobile.custom.incidentreport.get(
"incidents/" + req.params.incidentId, {outType: 'json'}));
promiseArray.push(req.oracleMobile.custom.incidentreport.get(
"technicians/" + req.params.techId, {outType: 'json'}));
// Call Promise.all with the array
Promise.all(promiseArray).then(
function (allResult) {
var report = {
customerContact: allResult[0].result.email,
description: allResult[1].result.title,
technicianContact: allResult[2].result.email};
res.type('application/json');
res.status(200).send(report);
},
function (error) {
console.dir(error);
res.status(error.statusCode).send(error.error);
}
);
})
...
}
Create a Function that Returns a Promise
Here are some examples of creating and using functions that return a promise. The first example shows how to return a resolved promise and a rejected promise.
// Simple function that returns a resolved promise.
// Note the object passed to Promise.resolve is the
// object the promise is resolved with.
function resolve() {
return Promise.resolve({status: "resolved"});
}
// Simple function that returns a rejected promise.
// The object passed to Promise.reject describes the error.
function reject() {
return Promise.reject({error: "rejected"});
}
In this example, the compareEtags
function takes a successful (resolved) promise as its argument. It rejects the promise if the request had an ETag header and the ETag for the result doesn’t match the ETag passed in the header.
var Promise = require("bluebird");
var etag = require('etag');
module.exports = function(service) {
...
service.get('/mobile/custom/incidentreport/incidents/:id/ifmatch', function (req, res) {
function compareEtags(result) {
thisEtag = result.headers.etag;
if (req.header('if-match') &&
thisEtag != req.header('if-match')) {
return Promise.reject({
statusCode: 412,
error: "Precondition Failed" +". If-Match ETag: " + req.header('if-match') + ", this Etag: " + thisEtag
})
} else {
// result is already a resolved promise
return result;
}
}
// The custom code SDK get method returns a promise,
// which is then passed to the custom function compareEtags.
// On success, compareEtags passes the result from the get.
// If there's an ETag header, then the function rejects the
// promise if the result's ETag doesn't match.
//
// All rejections are caught by the last then.
req.oracleMobile.custom.incidentreport.get(
"incidents/" + req.params.id, {outType: 'json'})
.then(compareEtags)
.then(
function (result) {
// res.setHeader('Etag', etag(JSON.stringify(result.result)));
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
});
...
}
Common options Properties
Several custom code SDK methods that access APIs accept an optional options
argument, which is a JSON object. Here are the options
properties:
Property | Description | Type | Default Value |
---|---|---|---|
accept |
The value for the Accept header. Use this property to list the media types that you prefer for the response body. Note that for most methods, the media type for a response body is application/json .
|
String | Empty, which indicates no preference for response type. |
contentType |
The value for the Content-Type header. This property specifies the content type of the request body. For most methods, this is application/json .
|
String | Empty. Note that if the inType is json , then the service sets the Content-Type header to application/json .
|
inType |
For Storage, connector API, and custom API SDK functions that take a request body, use this option to specify whether the request body is json or stream .
If You typically set this property when the custom code builds the request body that you are sending to the API. |
String | Undefined. If this property isn’t set, then the method passes the request body as is. The request is serviced by the Node Request module, which accepts a string or a buffer. |
outType |
The response body type. The value can be one of the following:
This property is supported only by the Storage API and the connector and custom APIs. All other APIs use the default response behavior. |
String | Undefined. The response body is converted to a string using the UTF8 encoding. |
encodeURI |
When true, encodes the URI and the following arguments and properties:
This option is useful for multibyte characters. |
Boolean | false |
Access Mobile Backend Information from Custom Code
Use the req.oracleMobile.mbe.getMbe()
method to inquire about the backend that the request is coming from. Note that this method is synchronous and doesn't return a promise.
Arguments
This method doesn’t have any required arguments and doesn’t take the options
and httpOptions
arguments.
Response
The response body is a JSON object that contains the name
, version
, and id
properties.
Examples
{
name: 'myMBE',
version: '1.0',
id: 'ab72abb7-b337-4673-8584-ca5163df5d24'
}
Platform APIs
You can use the req.oracleMobile.<service>
methods described in the following topics to call the platform APIs, where <service>
identifies the platform that you want to call.
Further details, such as the HTTP response status codes and the schema for the request and response bodies, can be found in REST API Reference for Oracle Mobile Hub - Platform APIs.
Analytics Collector API
The Analytics API lets you log runtime events, such as a user submitting an inquiry or placing an item into a shopping cart, so that you can observe performance and usage patterns.
This API has one method.
analytics.postEvent(events, options, httpOptions)
This method accepts a batch of events and validates them. If they are valid, they are sent to the Analytics database. If one or more events in a batch are not valid, then no events are sent to the Analytics database.
When adding events to the batch, keep the following in mind:
-
There are two types of events —
custom
andsystem
. Use the custom events to record the events that you want to analyze. Use the system events to group your custom events. Note that if you don't specify the event type, then the event defaults tocustom
. -
Events are JSON objects. All events must have a
name
and atimestamp
. Thecomponent
andproperties
are optional. -
With custom events, you can add your own custom properties to
properties
. For example:{ name: 'NewIncident', type: 'custom', component: 'Incidents', timestamp: timestamp, properties: {customer: 'Lynn White'} }
-
You can group events by session. For example, a session can mark the beginning and ending of a function within a mobile app or when an app starts and stops. You start a session by adding a system event with the name
You use a user-defined session ID to associate events with a session. You have two ways to specify a session ID for an event. You can add asessionStart
. You use asessionEnd
event to end the session.sessionId
property to an event, and you can set theoptions.sessionId
property. Here’s examples of starting and stopping a session. In these examples, the session ID is set explicitly, but you can also set it usingoptions.sessionId
.{ name: 'sessionStart', type: 'system', sessionId: '2d64d3ff-25c7-4b92-8e49-21884b3495ce', timestamp: timestamp } { name: 'sessionEnd', type: 'system', sessionId: '2d64d3ff-25c7-4b92-8e49-21884b3495ce', timestamp: timestamp }
-
If you want to provide context to a session, then precede the
sessionStart
event with a system event namedcontext
. You can also intersperse context events with custom events to indicate changes in context, such as a location change. Here’s an example of a context event:{ name: 'context', type: 'system', timestamp: timestamp, properties: { userName: 'joe', model: 'iPhone5,1', longitude: '-122.11663', latitude: '37.35687', manufacturer: 'Apple', osName: 'iPhone OS', osVersion: '7.1', osBuild: '13E28', carrier: 'ATT' }
Arguments
events
: Required. This is an array of event
objects. To learn about the event
properties, see the POST /mobile/platform/analytics/events
operation in REST API Reference for Oracle Mobile Hub -
Platform APIs.
options
: Optional. JSON object. This object can have these properties in addition to those listed in Common options Properties:
Property | Description | Type | Default |
---|---|---|---|
applicationKey |
Deprecated. | String | None |
deviceId |
Identifies the device. This is the ID that is returned when you register the device with the Mobile Devices API. | String | None |
sessionId |
Specifies a default session ID. Use a session ID to group all events by a user-defined session. When present, the sessionID value in the event object overrides this value.
|
String | None |
Response
The response body is a JSON object with a message
attribute. For example, {"message":"1 events accepted for processing."}
Example
Here’s an example that records events when incidents are created. After it successfully saves an incident in the database, it gets the user name for the context event, and then it records the event. This example uses the promises then()
function to insure that each API call completes successfully before invoking the next, as described in Invoke Calls Synchronously.
In this example, the request body looks like this:
{
title:'Water heater is leaking',
technician:'jwhite',
customer:'Lynn Smith'
}
This code expects the request to include the session ID in the Oracle-Mobile-Analytics-Session-ID
header. It sets the options.sessionId
property to this value.
service.post('/mobile/custom/incidentreport/incidents/log',
function (req, res) {
/* Post the incident and send the response.
* Then, if the post was successful,
* get the username,
* then use the username to post an event.
*
**/
postIncident()
.then(getUser)
.then(postEvent)
.catch(function (errorResult) {
console.warn(errorResult);
});
function postIncident() {
return req.oracleMobile.database.insert('FIF_Incidents', req.body)
.then(
function (successResult) {
res.status(successResult.statusCode).send(successResult.result);
// By default, Bluebird wraps this with a
// resolved promise
return {status: "resolved"};
},
function (errorResult) {
res.status(errorResult.statusCode).send(errorResult.error);
throw errorResult;
}
);
};
function getUser() {
return req.oracleMobile.ums.getUser({fields: 'username'});
};
function postEvent(successResult) {
var userName = successResult.result.username;
/*
* Record the NewIncident event
*/
var timestamp = (new Date()).toISOString();
// Events are posted as an array
var events = [];
// Put events in context
events.push(
{name: 'context',
type: 'system',
timestamp: timestamp,
properties: {userName: userName}
});
// Start the session
events.push(
{name: 'sessionStart',
type: 'system',
timestamp: timestamp
});
// Add the custom event:
events.push(
{name: 'NewIncident',
type: 'custom',
component: 'Incidents',
timestamp: timestamp,
properties: {customer: req.body.customer}
});
// End the session:
events.push(
{name: 'sessionEnd',
type: 'system',
timestamp: timestamp
});
// Post the batch of events. Apply the passed-in session ID to all.
// The postEvent result is returned by this function
return req.oracleMobile.analytics.postEvent(
events,
{sessionId: req.header('oracle-mobile-analytics-session-id')});
};
});
App Policies API
The App Policies API lets you retrieve the app policies that have been set for the current backend. For example, a backend might have app policies for the string that appears in an app’s welcome message, the background color, and a timeout value.
This API has one method.
appConfig.getProperties(httpOptions)
This method retrieves the app policies that have been set for a backend. These are the policies that you create from the backend’s App Policies page.
Arguments
This method doesn’t have any required arguments and doesn’t take the options
argument.
Response
The response body is a JSON object where the name/value pairs represent the app policies.
Examples
service.get(
'/mobile/custom/incidentreport/appPolicies',
function (req, res) {
req.oracleMobile.appConfig.getProperties().then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
});
{
"fifBgColor": "blue",
"fifWelcomeMessage": "Hello",
"fifShowArg": true
}
Database Access API
You can use the Database Access API to retrieve, add, update, and delete rows in a database table, as well as execute SQL statements.
This API has the following methods:
-
database.delete(table, keys, options, httpOptions): Deletes a row.
-
database.get(table, keys, options, httpOptions): Retrieves a row from a table.
-
database.getAll(table, options, httpOptions): Retrieves specified fields from all rows in a table.
-
database.insert(table, object, options, httpOptions): Adds rows to a table.
-
database.merge(table, object, options, httpOptions): Adds or updates rows in a table.
-
database.sql(sql, args, options, httpOptions): Executes an SQL statement.
database.delete(table, keys, options, httpOptions)
This method lets you delete a row from the table.
Arguments
table
: Required. String. The name of the database table to delete the row from.
keys
: Required. String. If the table’s row key is id
, then provide the id
value. Otherwise, provide the primary key values in the order in which the primary keys were specified when the first row was added to the table (which resulted in the creation of the table). Use an array for a composite key. For example, if the options.primaryKeys
property was set to incidentReport,technician
when the table was created, then the values must be listed in that order, such as ['5690','jwhite']
.
options
: Optional. JSON object. This object can have the following property in addition to those listed in Common options Properties:
Property | Description | Type | Default |
---|---|---|---|
encodeURI |
Set to true to URI-encode the table and keys values. This option can be useful for multibyte values.
|
Boolean | false |
Response
The response body is a JSON object. If the table’s row key is id
, then the response is an array that contains the deleted row’s id
value. Otherwise, the response is the rowCount
indicating if 0 or 1 row was deleted.
Examples
Here’s an example of calling the method to delete a record with the id
specified in the request URI:
service.delete('/mobile/custom/incidentreport/incidents/:id',
function (req, res) {
req.oracleMobile.database.delete(
'FIF_Incidents', req.params.id).then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
});
Here’s an example of the response for this request.
{"items":[{"id":42}]}
Note that if you have defined primary keys for the table (instead of using the system-defined id
column for the row key), then the response shows the rowCount
of the deleted rows. For example:
{
"rowCount": 1
}
database.get(table, keys, options, httpOptions)
This method lets you retrieve a row from a table.
Arguments
table
: Required. String. The name of the database table to retrieve the row from.
keys
: Required. String. If the table’s row key is id
, then provide the id
value. Otherwise, provide the primary key values in the order in which the primary keys were specified when the first row was added to the table (which resulted in the creation of the table). Use an array for a composite key. For example, if the options.primaryKeys
property was set to incidentReport,technician
when the table was created, then the values must be listed in that order, such as ['5690','jwhite']
.
options
: Optional. JSON object. This object can have the following property in addition to those listed in Common options Properties:
Property | Description | Type | Default |
---|---|---|---|
encodeURI |
Set to true to URI-encode the table and keys values. This option can be useful for multibyte values.
|
Boolean | false |
expectSingleResult |
Set to true to return an object instead of an array and to return 404 (not found) if the row for the specified keys doesn’t exist.
|
Boolean | false |
Response
By default, the response body is a JSON object containing an items
array with just one item, which contains the column names and corresponding values. To return a single object, include options.expectSingleResult
in the request and set it to true
.
Examples
Here’s an example of calling the method to retrieve the row with the id
specified in the request URI. Because the expectSingleResult
option is omitted, the response body will contain an array, and the response status will always be 200
.
service.get('/mobile/custom/incidentreport/incidents/:id',
function (req, res) {
req.oracleMobile.database.get(
'FIF_Incidents', req.params.id).then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
});
Here’s an example of the response for this request.
{
"items":[
{
"id":2,
"createdBy":"jdoe",
"createdOn":"2018-01-31T20:14:24.4948+00:00",
"modifiedBy":"jdoe",
"modifiedOn":"2018-01-31T20:14:24.4948+00:00",
"title":"Water heater is leaking",
"technician":"jwhite",
"status":"Open",
"customer":"Lynn Smith",
"incidentReport":"7890"
}
]
}
Here’s an example of including the expectSingleResult
option with a value of true
. The response body will contain an object, and the response status will be 404
if the row doesn’t exist.
service.get('/mobile/custom/incidentreport/incidents/:id',
function (req, res) {
req.oracleMobile.database.get(
'FIF_Incidents', req.params.id, {expectSingleResult: true}).then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
});
Here’s an example of the response for this request.
{
"id": 2,
"createdBy": "jdoe",
"createdOn": "2018-01-31T20:14:24.4948+00:00",
"modifiedBy": "jdoe",
"modifiedOn": "2018-01-31T20:14:24.4948+00:00",
"title": "Water heater is leaking",
"technician": "jwhite",
"status": "Open",
"customer": "Lynn Smith",
"incidentReport": "7890"
}
database.getAll(table, options, httpOptions)
This method lets you retrieve the specified fields from all the rows in a table.
Note that the Database_MaxRows
environment policy restricts the number of rows that the service returns for this call. The default value is 1000
. Ensure that this value is sufficient for your needs. If your request doesn’t return all the rows that you expected, ask your mobile cloud administrator to increase the Database_MaxRows
value.
Arguments
table
: Required. String. The name of the tables to retrieve the rows from.
options
: Optional. JSON object. This object can have the following properties in addition to those listed in Common options Properties:
Property | Description | Type | Default |
---|---|---|---|
encodeURI |
Set to true to URI-encode the table and fields values. This option can be useful for multibyte values.
|
Boolean | false |
fields |
A comma separated list of the fields to return. For example, customer, status .
|
String | If you omit this argument, then the method returns all fields. |
Response
The response body is a JSON object containing an items
array, where each item represents a row, and contains the column names and corresponding values.
Examples
Here’s an example of calling the method to retrieve the customer
and status
fields from the FIF_Incidents table:
service.get('/mobile/custom/incidentreport/incidents',
function (req, res) {
req.oracleMobile.database.getAll(
'FIF_Incidents', {fields: 'customer,status'}).then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
});
Here’s an example of the response for this request.
{
"items":[
{
"status":"Open",
"customer":"Lynn Smith"
},
{
"status":"Completed",
"customer":"John Doe"
}
]
}
The /database/objects/{table}
resource supports a query parameter to filter by column values which rows to retrieve. This example uses the httpOptions
argument to pass a request query string that filters the results for a matching technician.
service.get('/mobile/custom/incidentreport/incidents',
function (req, res) {
httpOptions={};
httpOptions.qs = {technician : 'jwhite'};
req.oracleMobile.database.getAll(
'FIF_Incidents', {}, httpOptions).then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
});
database.insert(table, object, options, httpOptions)
This method lets you add one or more rows to a table.
When the Database_CreateTablesPolicy
environment policy is allow
, then the following actions can occur:
-
If the table doesn't exist, then it is created.
-
If a column doesn’t exist, then the table is altered to include it.
-
If the value is larger than the column size, then the column is resized.
Ask your mobile cloud administrator about the Database_CreateTablesPolicy
environment policy setting.
Arguments
table
: Required. String. The name of the database table to add the row to.
object
: Required. JSON object containing the table data. If you’re adding one row, then you can use this format:
{
status : 'Open',
code : '3'
}
If you’re adding multiple rows, then use this format:
[
{
status:'Open',
code:3},
{
status:'Completed',
code:9}
]
options
: Optional. JSON object. This object can have the following properties in addition to those listed in Common options Properties:
Property | Description | Type | Default |
---|---|---|---|
encodeURI |
Set to true to URI-encode the table , extraFields , and primaryKeys values. This option can be useful for multibyte values.
|
Boolean | false |
extraFields |
For an implicit table creation, optionally provide a comma-separated list that specifies which predefined columns to include in the table from amongst id , createdBy , createdOn , modifiedBy , and modifiedOn . For example, createdOn,createdBy .
To not include any predefined columns, specify |
String | To include all the predefined columns, do not include this property. Note that the id column is added to the table automatically if both the primaryKeys and extraFields properties are absent.
|
primaryKeys |
For an implicit table creation, provide a URL-encoded, comma-separated list specifying which attributes of the JSON object in the request body constitute the table's primary key. For example, lastName,firstName .
Note: Because you can’t retrieve the primary key order from the table metadata, make sure that you document the order of the primary fields. |
String | If you do not specify a primary key, then the service adds an id column to the table, and generates the column's values automatically, as long as you don’t also include extraFields without id in the list.
|
Response
The response body is a JSON object. If the table is indexed on id
, then the response is an array of the new rows’ id
values. Otherwise, the response is the rowCount
of the records added.
Examples
Here’s an example of calling the method to add two rows. If the table doesn’t exist, then the service creates it. This table doesn’t have extra fields, and its primary key is code
:
service.post('/mobile/custom/incidentreport/initStatus', function (req, res) {
req.oracleMobile.database.insert(
'FIF_Status',
[
{
status: 'Closed',
code: '0'},
{
status: 'Completed',
code: '9'}
],
{extraFields: 'none', primaryKeys: 'code'}).then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
});
Here’s an example of the response for this request.
{
"rowCount": 2
}
Note that if a table’s row key is the system-defined id
column (instead of user-defined primary keys), then the response shows the id
values for the new rows. For example:
{"items":[{"id":42},{"id":43}]}
database.merge(table, object, options, httpOptions)
This method lets you add or update rows in a table. Whether the operation performs an add or update depends on whether the table uses id
or primary key fields to uniquely identify rows.
-
id
field: If you include anid
property in the table data in theobject
argument, then the operation performs an update. Otherwise it adds the row. -
Primary key fields: If the table uses primary key fields, then the operation performs an update if a row exists with matching primary key values. Otherwise, it adds the row.
Note that if you submit a batch of rows, all the rows must have the same set of columns.
When the Database_CreateTablesPolicy
environment policy is allow
, then the following actions can occur:
-
If the table doesn't exist, then it is created.
-
If a column doesn’t exist, then the table is altered to include it.
-
If the value is larger than the column size, then the column is resized.
Ask your mobile cloud administrator about the Database_CreateTablesPolicy
environment policy setting.
Arguments
table
: Required. String. The name of the database table to add the row to.
object
: Required. JSON object containing the table data. If you’re adding one row, then you can use this format:
{
status : 'Open',
code : '3'
}
If you’re adding multiple rows, then use this format:
[
{
status:'Open',
code:'3'},
{
status:'Completed',
code:'9'}
]
options
: Optional. JSON object. This object can have the following properties in addition to those listed in Common options Properties:
Property | Description | Type | Default |
---|---|---|---|
encodeURI |
Set to true to URI-encode the table , extraFields , and primaryKeys values. This option can be useful for multibyte values.
|
Boolean | false |
extraFields |
For an implicit table creation, optionally provide a comma-separated list that specifies which predefined columns to include in the table from amongst id , createdBy , createdOn , modifiedBy , and modifiedOn . For example, createdOn,createdBy .
To not include any predefined columns, specify |
String | To include all the predefined columns, do not include this property. Note that the id column is added to the table automatically if both the primaryKeys and extraFields properties are absent.
|
primaryKeys |
For an implicit table creation, provide a URL-encoded, comma-separated list specifying which attributes of the JSON object in the request body constitute the table's primary key. For example, lastName,firstName .
Because you can’t retrieve the primary key order from the table metadata, make sure that you document the order of the primary fields. |
String | If you do not specify a primary key, then the operation adds an id column to the table, and generates the column's values automatically, as long as you don’t also include extraFields without id in the list.
|
Response
The response body is a JSON object. If the table is indexed on id
, then the response is an array of the new rows’ id
values. Otherwise, the response is the rowCount
.
Examples
Here’s an example of calling the method to add or update two rows. If the table doesn’t exist, then the operation creates it. This table doesn’t have extra fields, and its primary key is code
:
service.post('/mobile/custom/incidentreport/initStatus', function (req, res) {
req.oracleMobile.database.merge(
'FIF_Status',
[
{
status: 'Closed',
code: '0'},
{
status: 'Completed',
code: '9'}
],
{extraFields: 'none', primaryKeys: 'code'}).then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
});
Here’s an example of the response for this request.
{
"rowCount": 2
}
Note that if a table’s row key is the system-defined id
column (instead of user-defined primary keys), then the response shows the id
values for the new rows. For example:
{"items":[{"id":42},{"id":43}]}
database.sql(sql, args, options, httpOptions)
This method lets you execute an SQL statement, such as INSERT, UPDATE, MERGE, DELETE, or SELECT. You can use this method for complex actions, such as when you need to join tables, use aggregate functions like COUNT() and SUM(), or use a WHERE clause to delete a set of rows.
Unlike the other database
methods, this operation doesn’t alter your schema automatically. For example:
-
If the table doesn't exist, then it isn’t created.
-
If a column doesn’t exist, then the table isn’t altered to include it.
-
If the value is larger than the column size, then the column isn’t resized.
The Database_MaxRows
environment policy restricts the number of rows that the service returns for this call. The default value is 1000
. Ensure that this value is sufficient for your needs. If your request doesn’t return all the rows that you expected, ask your mobile cloud administrator to increase the Database_MaxRows
value.
Arguments
sql
: Required. String. The SQL statement to execute. Examples:
INSERT into Statuses (status, code) values (:status, :code)
SELECT SUM("totalGross") "salesByGenre", "genre" FROM "Movies" GROUP BY "genre"
SELECT COUNT("incidentReport") "reportCount" FROM "FIF_Incidents" WHERE "status" = :status
args
: Optional. If your SQL statement takes parameters, then pass them in this JSON object.
To execute the SQL statement once with a single set of parameters, use this format for the args
argument:
{
status : 'Open',
code : '3'
}
To execute the SQL statement multiple times, use this format for the args
argument:
[
{
status:'Open',
code:3},
{
status:'Completed',
code:9
}
]
options
: Optional. JSON object. This object can have the following properties in addition to those listed in Common options Properties:
Property | Description | Type | Default |
---|---|---|---|
encodeURI |
Set to true to URI-encode the SQL statement. This option can be useful for multibyte values.
|
Boolean | false |
Response
The response body is a JSON object. The structure of the JSON object depends on the SQL verb and whether the table has a primary key. For example, here’s a response body for a SELECT statement:
{"items":[{ "code" : 3}] }
Here’s an example of a response body for an INSERT, DELETE, UPDATE, OR MERGE where the table has a primary key:
{ "rowCount" : 2 }
Here’s an example of a response body for an INSERT, DELETE, UPDATE, OR MERGE where the row key is the id
column:
{"items":[{"id":42},{"id":43}]}
Examples
Here’s an example of calling the method to insert rows:
service.post('/mobile/custom/incidentreport/status', function (req, res) {
req.oracleMobile.database.sql(
'insert into Statuses (status, code) values (:status, :code)',
[
{
status: 'Closed',
code: '0'},
{
status: 'Completed',
code: '9'}
]).then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
});
Here’s an example of the response for this request.
{
"rowCount": 2
}
Note that if a table’s row key is the system-defined id
column (instead of user-defined primary keys), then the response shows the id
values for the new rows. For example:
{"items":[{"id":42},{"id":43}]}
Location API
The Location API lets you query about location devices, their assets, and the places where they’re located.
This API has the following methods:
-
location.assets.getAsset(id, httpOptions): Retrieves the asset that matches the ID or name.
-
location.assets.query(queryObject, httpOptions): Retrieves the assets that match the query parameters that you specify in the request body.
-
location.devices.getDevice(id, httpOptions): Retrieves the device that matches the ID or name.
-
location.devices.query(queryObject, httpOptions): Retrieves the devices that match the query parameters that you specify in the request body.
-
location.places.getPlace(id, httpOptions): Retrieves the place that matches the ID or name.
-
location.places.query(queryObject, httpOptions): Retrieves the places that match the query parameters that you specify in the request body.
location.assets.getAsset(id, httpOptions)
Call this method to retrieve the asset that matches the specified ID or name.
Arguments
id
: Required. Must be one of the following:
-
String that contains the ID of the asset to retrieve.
-
JSON object that contains either the
id
property or thename
property, where the property value indicates the search value. If the object contains both properties, then the SDK retrieves the asset with the matching name.
Response
The response body is a JSON object that follows the Asset
schema that is shown for the GET /mobile/platform/location/assets
and GET /mobile/platform/location/assets/{id}
operations in REST API Reference for Oracle Mobile Hub -
Platform APIs
Examples
Here’s an example of calling this method to retrieve an asset by ID.
service.get(
'/mobile/custom/incidentreport/assets/:id',
function (req, res) {
req.oracleMobile.location.assets.getAsset(req.params.id).then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
});
Here’s an example of calling this method to retrieve an asset by name.
service.get(
'/mobile/custom/incidentreport/assets/:name',
function (req, res) {
req.oracleMobile.location.assets.getAsset({name:req.params.name}).then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
});
Here’s an example of the response body:
{
"id":111,
"createdOn":"2015-08-06T18:37:59.424Z",
"createdBy":"jdoe",
"modifiedOn":"2015-08-06T18:37:59.424Z",
"modifiedBy":"jdoe",
"name":"RC_WH_01_F01_B023",
"label":"forklift",
"description":"Forklift in the FixItFast Warehouse in Redwood City",
"lastKnownLocation":{
"gpsPoint":{
"latitude":37.5548,
"longitude":-121.1566
}
},
"devices":[
{
"id":345,
"createdOn":"2015-08-06T18:37:59.424Z",
"createdBy":"jdoe",
"modifiedOn":"2015-08-08T07:22:44.654Z",
"modifiedBy":"tsmith",
"name":"RC_WH_01_F01_B001",
"description":"Beacon in FixitFast Warehouse in Redwood City",
"beacon":{
"iBeacon":{
"uuid":"B9407F30-F5F8-466E-AFF9-25556B57FE6D",
"major":"1.0",
"minor":"1.1"
}
},
"attributes":{
"manufacturer":"Abc Company",
"manufacturerId":"10D39AE7-020E-4467-9CB2-DD36366F899D",
"status":"Active",
"visibility":"Public"
},
"links":[
{
"rel":"canonical",
"href":"/mobile/platform/location/devices/345"
},
{
"rel":"self",
"href":"/mobile/platform/location/devices/345"
}
]
}
],
"attributes":{
"EquipmentManufacturer":"Abc Company",
"beaconID":"AE2924505-66045"
},
"links":[
{
"rel":"canonical",
"href":"/mobile/platform/location/assets/111"
},
{
"rel":"self",
"href":"/mobile/platform/location/assets/111"
}
]
}
location.assets.query(queryObject, httpOptions)
Call this method to retrieve the assets that match the query parameters that you specify in queryObject
.
Arguments
queryObject
: Required. String. The parameters that describe the desired results. For details, see the body parameter for the POST /mobile/platform/location/assets/query
operation in REST API Reference for Oracle Mobile Hub -
Platform APIs. If you don’t have any query parameters, then use an empty body ({}
).
Response
The response body is a JSON object that contains an array of items that follow the Asset
schema that is shown for the POST /mobile/platform/location/assets/query
operation in REST API Reference for Oracle Mobile Hub -
Platform APIs. The result also contains paging information. For example:
"totalResults":2,
"offset":0,
"limit":40,
"count":2,
"hasMore":false
Examples
1225
in the name or description (case-insensitive).service.get(
'/mobile/custom/incidentreport/assets,
function (req, res) {
req.oracleMobile.location.assets.query({"search":"1225"}).then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
});
{
"items":[
{
"devices":[
{
"id":3401,
"createdBy":"jdoe",
"name":"RC_WH_01_F01_B001",
"createdOn":"2015-08-06T18:37:59.424Z",
"modifiedOn":"2015-08-08T07:22:44.654Z",
"beacon":{
"iBeacon":{
"uuid":"B9407F30-F5F8-466E-AFF9-25556B57FE6D",
"major":"1.0",
"minor":"1.1"}},
"modifiedBy":"tsmith",
"links":[
{
"rel":"canonical",
"href":"/mobile/platform/location/devices/3401"},
{
"rel":"self",
"href":"/mobile/platform/location/devices/3401"}
],
"attributes":{
"manufacturer":"Example Company",
"manufacturerId":"10D39AE7-020E-4467-9CB2-DD36366F899D",
"status":"Active",
"visibility":"Public"},
"description":"Beacon on 1st Floor in FixitFast Warehouse in Redwood City"}
],
"label":"hospital bed",
"lastKnownLocation":{
"placeId":244},
"id":333,
"createdBy":"jdoe",
"name":"hospital bed #233",
"createdOn":"2015-08-06T18:37:59.424Z",
"modifiedOn":"2015-08-06T18:37:59.424Z",
"modifiedBy":"jdoe",
"links":[
{
"rel":"canonical",
"href":"/mobile/platform/location/assets/333"},
{
"rel":"self",
"href":"/mobile/platform/location/assets/333"}
],
"attributes":{
"EquipmentManufacturer":"Example Company",
"SJId":"6754843090"},
"description":"model 1225 hospital bed"},
{
"devices":[
{
"id":648,
"createdBy":"jdoe",
"name":"RC_WH_01_F01_B001",
"createdOn":"2015-08-06T18:37:59.424Z",
"modifiedOn":"2015-08-08T07:22:44.654Z",
"beacon":{
"iBeacon":{
"uuid":"B9407F30-F5F8-466E-AFF9-25556B57FE6D",
"major":"1.0",
"minor":"1.1"}},
"modifiedBy":"tsmith",
"links":[
{
"rel":"canonical",
"href":"/mobile/platform/location/devices/648"},
{
"rel":"self",
"href":"/mobile/platform/location/devices/648"}
],
"attributes":{
"manufacturer":"Example Company",
"manufacturerId":"10D39AE7-020E-4467-9CB2-DD36366F899D",
"status":"Active",
"visibility":"Public"},
"description":"Beacon on 1st Floor in FixitFast Warehouse in Redwood City"}
],
"label":"hospital bed",
"lastKnownLocation":{
"placeId":360},
"id":888,
"createdBy":"jdoe",
"name":"hospital bed #233",
"createdOn":"2015-10-16T09:24:41.354Z",
"modifiedOn":"2015-10-16T09:24:41.354Z",
"modifiedBy":"jdoe",
"links":[
{
"rel":"canonical",
"href":"/mobile/platform/location/assets/888"},
{
"rel":"self",
"href":"/mobile/platform/location/assets/888"}
],
"attributes":{
"EquipmentManufacturer":"Example Company",
"SJId":"6754843090"},
"description":"model 1225 hospital bed"}
],
"totalResults":2,
"offset":0,
"count":2,
"hasMore":false
}
location.devices.getDevice(id, httpOptions)
Call this method to retrieve the device that matches the specified ID or name.
Arguments
id
: Required. Must be one of the following:
-
String that contains the ID of the device to retrieve.
-
JSON object that contains either the
id
property or thename
property, where the property value indicates the search value. If the object contains both properties, then the SDK retrieves the device with the matching name.
Response
The response body is a JSON object that follows the Location device
schema that is shown for the GET /mobile/platform/location/devices
and GET /mobile/platform/location/devices/{id}
operations in REST API Reference for Oracle Mobile Hub -
Platform APIs.
Examples
Here’s an example of calling this method to retrieve a device by ID.
service.get(
'/mobile/custom/incidentreport/devices/:id',
function (req, res) {
req.oracleMobile.location.devices.getDevice(req.params.id).then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
});
Here’s an example of calling this method to retrieve a device by name.
service.get(
'/mobile/custom/incidentreport/devices/:name',
function (req, res) {
req.oracleMobile.location.devices.getDevice({name:req.params.name}).then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
});
Here’s an example of the response body:
{
"id": 12345,
"createdOn": "2015-08-06T18:37:59.424Z",
"createdBy": "jdoe",
"modifiedOn": "2015-08-08T07:22:44.654Z",
"modifiedBy": "tsmith",
"name": "RC_WH_01_F01_B001",
"description": "Beacon on 1st Floor in FixitFast Warehouse in Redwood City",
"place":
{
"id": 111,
"createdOn": "2015-08-06T18:37:59.424Z",
"createdBy": "jdoe",
"modifiedOn": "2015-08-06T18:37:59.424Z",
"modifiedBy": "jdoe",
"name": "FixitFast Redwood City Warehouse",
"label": "FixitFast Warehouse",
"parentPlace": 42,
"description": "FixitFast Warehouse in Redwood City",
"address" : {
"gpsPoint" : {
"latitude": 37.5548,
"longitude": -121.1566
}
},
"attributes" : {
"equipmentManufacturer": "Abc Corp"
},
"links": [
{
"rel": "canonical",
"href": "/mobile/platform/location/places/111"
},
{
"rel": "self",
"href": "/mobile/platform/location/places/111"
}
]
},
"beacon": {
"iBeacon" : {
"uuid": "B9407F30-F5F8-466E-AFF9-25556B57FE6D",
"major": "1.0",
"minor": "1.1"
}
},
"attributes" : {
"manufacturer": "Abc Company",
"manufacturerId": "10D39AE7-020E-4467-9CB2-DD36366F899D"
"status": "Active",
"visibility": "Public"
},
"links": [
{
"rel": "canonical",
"href": "/mobile/platform/location/devices/12345"
},
{
"rel": "self",
"href": "/mobile/platform/location/devices/12345"
}
]
}
location.devices.query(queryObject, httpOptions)
Call this method to retrieve the devices that match the query parameters that you specify in queryObject
.
Arguments
queryObject
: Required. String. The parameters that describe the desired results. For details, see the body parameter for the POST /mobile/platform/location/devices/query
operation in REST API Reference for Oracle Mobile Hub -
Platform APIs. If you don’t have any query parameters, then use an empty body ({}
).
Response
The response body is a JSON object that contains an array of items that follow the Location device
schema that is shown for the POST /mobile/platform/location/devices/query
operation in REST API Reference for Oracle Mobile Hub -
Platform APIs The result also contains paging information. For example:
"totalResults":2,
"offset":0,
"limit":40,
"count":2,
"hasMore":false
Examples
warehouse
in either the name or description (case-insensitive).service.get(
'/mobile/custom/incidentreport/devices,
function (req, res) {
req.oracleMobile.location.devices.query({{ "search": "Warehouse"}}).then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
});
{
"items":[
{
"id":33,
"name":"RC_WH_01_B09_C004",
"description":"Beacon on 2nd Floor NW in FixItFast Warehouse in Redwood City",
"protocol":"altBeacon"},
{
"id":12,
"name":"RC_WH_01_F01_B001",
"description":"Beacon on 1st Floor SE in FixItFast Warehouse in Redwood City",
"protocol":"altBeacon"},
{
"id":61,
"name":"RC_WH_01_F01_B008",
"description":"Beacon on 2nd Floor SW in FixItFast Warehouse in Redwood City",
"protocol":"altBeacon"},
{
"id":58,
"name":"RC_WH_02_F01_B011",
"description":"Beacon on 1st Floor NW in FixitFast Warehouse in Redwood City",
"protocol":"altBeacon"},
{
"id":114,
"name":"RC_WH_01_K22_A999",
"description":"Beacon on 3rd Floor NW in FixitFast Warehouse in Redwood City",
"protocol":"altBeacon"}
],
"totalResults":5,
"offset":0,
"count":5,
"hasMore":false
}
location.places.getPlace(id, httpOptions)
Call this method to retrieve the place that matches the specified ID or name.
Arguments
id
: Required. Must be one of the following:
-
String that contains the ID of the place to retrieve.
-
JSON object that contains either the
id
property or thename
property, where the property value indicates the search value. If the object contains both properties, then the SDK retrieves the place with the matching name.
Response
The response body is a JSON object that follows the Place
schema that is shown for the GET /mobile/platform/location/places
and GET /mobile/platform/location/places/{id}
operations in REST API Reference for Oracle Mobile Hub -
Platform APIs.
Examples
Here’s an example of calling this method to retrieve a place by ID.
service.get(
'/mobile/custom/incidentreport/places/:id',
function (req, res) {
req.oracleMobile.location.places.getPlace(req.params.id).then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
});
Here’s an example of calling this method to retrieve a place by name.
service.get(
'/mobile/custom/incidentreport/places/:name',
function (req, res) {
req.oracleMobile.location.places.getPlace({name:req.params.name}).then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
});
Here’s an example of the response body:
{
"id": 111,
"createdOn": "2015-08-06T18:37:59.424Z",
"createdBy": "jdoe",
"modifiedOn": "2015-08-06T18:37:59.424Z",
"modifiedBy": "jdoe",
"name": "FixitFast Redwood City Warehouse",
"label": "FixitFast Warehouse",
"parentPlace": 42,
"description": "FixitFast Warehouse in Redwood City",
"address" : {
"gpsPoint" : {
"latitude": 37.5548,
"longitude": -121.1566
}
},
"attributes" : {
"equipmentManufacturer": "Abc Corp"
},
"links": [
{
"rel": "canonical",
"href": "/mobile/platform/location/places/111"
},
{
"rel": "self",
"href": "/mobile/platform/location/places/111"
}
]
}
location.places.query(queryObject, httpOptions)
Call this method to retrieve the places and, optionally, the associated devices that match the query properties that you specify in the queryObject
.
Arguments
queryObject
: Required. String. The parameters that describe the desired results. For details, see the body parameter for the POST /mobile/platform/location/places/query
operation in REST API Reference for Oracle Mobile Hub -
Platform APIs. If you don’t have any query parameters, then use an empty body ({}
).
Response
Place
schema that is shown for the POST /mobile/platform/location/places/query
operation in REST API Reference for Oracle Mobile Hub -
Platform APIs. The result also contains paging information. For example: "totalResults":2,
"offset":0,
"limit":40,
"count":2,
"hasMore":false
Examples
warehouse
in the name or description (case-insensitive). By default, the response includes the children
array, which contains information about descendent places. In this request, the includeDescendantsInResult
property is set to none
. Therefore the request doesn't include that array.service.get(
'/mobile/custom/incidentreport/places',
function (req, res) {
req.oracleMobile.location.places.query({"search":"warehouse","includeDescendantsInResult":"none" }).then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
});
Here’s an example of the response body:
{
"items":[
{
"devices":[
{
"id":12345,
"createdBy":"jdoe",
"name":"RC_WH_01_F01_B001",
"createdOn":"2015-08-06T18:37:59.424Z",
"modifiedOn":"2015-08-08T07:22:44.654Z",
"beacon":{
"iBeacon":{
"uuid":"B9407F30-F5F8-466E-AFF9-25556B57FE6D",
"major":"1.0",
"minor":"1.1"}},
"modifiedBy":"tsmith",
"links":[
{
"rel":"canonical",
"href":"/mobile/platform/location/devices/12345"},
{
"rel":"self",
"href":"/mobile/platform/location/devices/12345"}
],
"attributes":{
"manufacturer":"Abc Company",
"manufacturerId":"10D39AE7-020E-4467-9CB2-DD36366F899D",
"status":"Active",
"visibility":"Public"},
"description":"Beacon on 1st Floor in FixitFast Warehouse in Redwood City"}
],
"label":"FixItFast Warehouse",
"id":112,
"createdBy":"jdoe",
"name":"FixItFast Redwood City Warehouse",
"createdOn":"2015-08-06T18:37:59.424Z",
"modifiedOn":"2015-08-06T18:37:59.424Z",
"address":{
"gpsPoint":{
"latitude":122,
"longitude":37}},
"modifiedBy":"jdoe",
"links":[
{
"rel":"canonical",
"href":"/mobile/platform/location/places/112"},
{
"rel":"self",
"href":"/mobile/platform/location/places/112"}
],
"attributes":{
"hours":"9am-6pm"},
"hasChildren":false,
"parentPlace":42,
"description":"FixItFast Warehouse in Redwood City"},
{
"devices":[
{
"id":111,
"createdBy":"jdoe",
"name":"RC_WH_01_F01_B001",
"createdOn":"2015-08-06T18:37:59.424Z",
"modifiedOn":"2015-08-08T07:22:44.654Z",
"beacon":{
"iBeacon":{
"uuid":"B9407F30-F5F8-466E-AFF9-25556B57FE6D",
"major":"1.0",
"minor":"1.1"}},
"modifiedBy":"tsmith",
"links":[
{
"rel":"canonical",
"href":"/mobile/platform/location/devices/111"},
{
"rel":"self",
"href":"/mobile/platform/location/devices/111"}
],
"attributes":{
"manufacturer":"Abc Company",
"manufacturerId":"10D39AE7-020E-4467-9CB2-DD36366F899D",
"status":"Active",
"visibility":"Public"},
"description":"Beacon on 1st Floor in FixitFast Warehouse in Redwood City"},
{
"id":222,
"createdBy":"jdoe",
"name":"RC_WH_01_F01_B996",
"createdOn":"2015-08-08T18:37:59.424Z",
"modifiedOn":"2015-08-12T07:22:44.654Z",
"beacon":{
"iBeacon":{
"uuid":"B9407F30-F5F8-466E-AFF9-25552345908234DD0",
"major":"1.0",
"minor":"1.1"}},
"modifiedBy":"tsmith",
"links":[
{
"rel":"canonical",
"href":"/mobile/platform/location/devices/222"},
{
"rel":"self",
"href":"/mobile/platform/location/devices/222"}
],
"attributes":{
"manufacturer":"Abc Company",
"manufacturerId":"10D39AE7-020E-4467-9CB2-DD36366F899D",
"status":"Active",
"visibility":"Public"},
"description":"Beacon on 2nd Floor in FixitFast Warehouse in Redwood City"}
],
"label":"FixItFast Warehouse",
"id":325,
"createdBy":"jdoe",
"name":"FixItFast Palo Alto Warehouse",
"createdOn":"2015-08-06T19:27:59.424Z",
"modifiedOn":"2015-08-06T19:27:59.424Z",
"address":{
"gpsCircle":{
"latitude":123,
"longitude":37,
"radius":300}},
"modifiedBy":"jdoe",
"links":[
{
"rel":"canonical",
"href":"/mobile/platform/location/places/325"},
{
"rel":"self",
"href":"/mobile/platform/location/places/325"}
],
"attributes":{
"hours":"9am-6pm"},
"hasChildren":false,
"parentPlace":42,
"description":"FixItFast Warehouse in Palo Alto"}
],
"totalResults":2,
"offset":0,
"count":2,
"hasMore":false
}
Location Management API
The Location Management API lets you create, update, and delete location devices, places, and assets.
This API has the following methods:
-
location.assets.register(assets, context, httpOptions): Creates one or more assets.
-
location.assets.remove(id, context, httpOptions): Deletes assets.
-
location.assets.update(id, asset, context, httpOptions): Updates a single asset.
-
location.devices.register(devices, context, httpOptions): Creates one or more location devices.
-
location.devices.remove(id, context, httpOptions): Deletes location devices.
-
location.devices.update(id, device, context, httpOptions): Updates a single location device.
-
location.places.register(places, context, httpOptions): Creates one or more places.
-
location.places.remove(id, context, httpOptions): Deletes places.
-
location.places.removeCascade(id, context, httpOptions): Deletes the place that matches the ID as well as all its child places.
-
location.places.update(id, place, context, httpOptions): Updates a single place.
location.assets.register(assets, context, httpOptions)
This method lets you create one or more assets.
Arguments
assets
: Required. JSON object that follows the request root schema (Assets Array) that is shown for the POST /mobile/system/locationManagement/assets
operation in REST API Reference for Oracle Mobile Hub -
Platform APIs. Here’s an example:
{
"items":[
{
"name":"hospital bed #233",
"label":"hospital bed",
"description":"model 1225 hospital bed",
"lastKnownLocation":{
"placeId":244
},
"devices":[
1111
],
"attributes":{
"EquipmentManufacturer":"Example Company",
"SJId":"6754843090"
}
}
]
}
context
: This argument is ignored.
Response
The response body, which shows the stored assets, is a JSON object that follows the response root schema (Assets Array) that is shown for the POST /mobile/system/locationManagement/assets
operation in REST API Reference for Oracle Mobile Hub -
Platform APIs.
Examples
Here’s an example of calling this method.
service.post('/mobile/custom/incidentreport/assets', function (req, res) {
req.oracleMobile.location.assets.register(req.body).then(
function (result) {
res.type('application/json');
res.status(result.statusCode).send(result.result);
},
function (error) {
console.dir(error);
res.status(error.statusCode).send(error.error);
}
);
});
Here’s an example of the response body.
{
"items": [
{
"id": 12,
"createdOn": "2016-11-05T02:33:36.154Z",
"createdBy": "anAdministrator",
"modifiedOn": "2016-11-05T02:33:36.154Z",
"modifiedBy": "anAdministrator",
"name": "hospital bed #233",
"label": "hospital bed",
"description": "model 1225 hospital bed",
"lastKnownLocation": null,
"attributes": {
"EquipmentManufacturer": "Example Company",
"SJId": "6754843090"
},
"links": [
{
"rel": "canonical",
"href": "/mobile/platform/location/assets/12"
},
{
"rel": "self",
"href": "/mobile/platform/location/assets/12"
}
]
}
]
}
location.assets.remove(id, context, httpOptions)
Use this method to delete assets.
Arguments
id
: Required. IDs of the assets to remove. This argument can be either a single value or an array of values.
context
: This argument is ignored.
Response
If you provide a single value, then the service doesn’t return a response body. The status code is 204 if the asset was deleted and 404 if it doesn’t exist.
If you provide an array of IDs, then the status code is 200 for a successful request. The response contains a batch
object with an array of responses for the individual delete requests. For schema details, see the Delete Multiple Assets operation in REST API Reference for Oracle Mobile Hub -
Platform APIs.
Here’s an example:
{
"batch":[
{
"body":{
"id":353,
"message":"asset was deleted successfully."},
"code":200},
{
"body":{
"id":354,
"message":"asset was deleted successfully."},
"code":200},
{
"body":{
"id":355,
"message":"asset not found."},
"code":404}
]
}
Examples
In this example, if the id
query parameter contains multiple IDs, then it converts the query string into an array.
service.delete('/mobile/custom/location/assets', function(req,res) {
var contextObject = {};
var id = req.query.id.split(',');
if (id.length == 0){
id = req.query.id;
}
req.oracleMobile.location.assets.remove(
id,
contextObject
).then(
function (result) {
res.type('application/json');
res.status(result.statusCode).send(result.result);
},
function (error) {
console.dir(error);
res.status(error.statusCode).send(error.error);
}
);
});
location.assets.update(id, asset, context, httpOptions)
This method lets you update an asset.
Arguments
id
: Required. The ID of the asset. This ID must be an existing asset ID.
asset
: Required. JSON object that follows the request root schema (Asset) that is shown for the PUT /mobile/system/locationManagement/assets/{id}
operation in REST API Reference for Oracle Mobile Hub -
Platform APIs. Here’s an example:
{
"lastKnownLocation":{
"gpsPoint":{
"latitude":37.5548,
"longitude":-121.1566
}
},
"devices":[
11
]
}
context
: This argument is ignored.
Response
The response body, which shows the updated asset, is a JSON object that follows the response root schema (Asset) that is shown for the PUT /mobile/system/locationManagement/assets/{id}
operation in REST API Reference for Oracle Mobile Hub -
Platform APIs.
Examples
Here’s an example of calling this method.
service.put('/mobile/custom/incidentreport/assets/:id', function (req, res) {
req.oracleMobile.location.assets.update(
req.params.id, req.body).then(
function (result) {
res.type('application/json');
res.status(result.statusCode).send(result.result);
},
function (error) {
console.dir(error);
res.status(error.statusCode).send(error.error);
}
);
});
Here’s an example of the response body.
{
"id": 11,
"createdOn": "2016-11-08T21:26:38.318Z",
"createdBy": "anAdministrator",
"modifiedOn": "2016-11-08T22:18:24.157Z",
"modifiedBy": "anAdministrator",
"name": "hospital bed #233",
"label": "hospital bed",
"description": "model 1225 hospital bed",
"lastKnownLocation": {
"gpsPoint": {
"longitude": -121.1566,
"latitude": 37.5548
}
},
"devices": [
{
"id": 11,
"createdOn": "2016-11-08T18:01:18.531Z",
"createdBy": "anAdministrator",
"modifiedOn": "2016-11-08T18:01:18.531Z",
"modifiedBy": "anAdministrator",
"name": "RC_WH_01_F01_B016",
"description": "Beacon on 2nd Floor in FixitFast Warehouse in Redwood City",
"beacon": {
"altBeacon": {
"id1": "B9407F30-F5F8-466E",
"id2": "AFF9",
"id3": "25556B57FE6D"
}
},
"attributes": {
"manufacturer": "Abc Company",
"status": "Active",
"manufacturerId": "10D39AE7-020E-4467-9CB2-DD36366F899D",
"visibility": "Public"
},
"links": [
{
"rel": "canonical",
"href": "/mobile/platform/location/devices/11"
},
{
"rel": "self",
"href": "/mobile/platform/location/devices/11"
}
]
}
],
"attributes": {
"EquipmentManufacturer": "Example Company",
"SJId": "6754843090"
},
"links": [
{
"rel": "canonical",
"href": "/mobile/platform/location/assets/11"
},
{
"rel": "self",
"href": "/mobile/platform/location/assets/11"
}
]
}
location.devices.register(devices, context, httpOptions)
This method lets you create one or more devices.
Arguments
devices
: Required. JSON object that follows the request root schema (Devices Array) that is shown for the POST /mobile/system/locationManagement/devices
operation in REST API Reference for Oracle Mobile Hub -
Platform APIs. Here’s an example:
{
"items":[
{
"name":"RC_WH_01_F01_B006",
"description":"Beacon on 2nd Floor in FixitFast Warehouse in Redwood City",
"asset":333,
"beacon":{
"altBeacon":{
"id1":"B9407F30-F5F8-466E",
"id2":"AFF9",
"id3":"25556B57FE6D"
}
},
"attributes":{
"manufacturer":"Abc Company",
"manufacturerId":"10D39AE7-020E-4467-9CB2-DD36366F899D",
"status":"Active",
"visibility":"Public"
}
}
]
}
context
: This argument is ignored.
Response
The response body, which shows the stored devices, is a JSON object that follows the response root schema (Devices Array) that is shown for the POST /mobile/system/locationManagement/devices
operation in REST API Reference for Oracle Mobile Hub -
Platform APIs.
Examples
Here’s an example of calling this method.
service.post('/mobile/custom/incidentreport/devices, function (req, res) {
req.oracleMobile.location.devices.register(
req.body).then(
function (result) {
res.type('application/json');
res.status(result.statusCode).send(result.result);
},
function (error) {
console.dir(error);
res.status(error.statusCode).send(error.error);
}
);
});
Here’s an example of the response body.
{
"items": [
{
"id": 10,
"createdOn": "2016-11-08T15:54:51.603Z",
"createdBy": "anAdministrator",
"modifiedOn": "2016-11-08T15:54:51.603Z",
"modifiedBy": "anAdministrator",
"name": "RC_WH_01_F01_B006",
"description": "Beacon on 2nd Floor in FixitFast Warehouse in Redwood City",
"beacon": {
"altBeacon": {
"id1": "B9407F30-F5F8-466E",
"id2": "AFF9",
"id3": "25556B57FE6D"
}
},
"attributes": {
"manufacturer": "Abc Company",
"manufacturerId": "10D39AE7-020E-4467-9CB2-DD36366F899D",
"status": "Active",
"visibility": "Public"
},
"links": [
{
"rel": "canonical",
"href": "/mobile/platform/location/devices/10"
},
{
"rel": "self",
"href": "/mobile/platform/location/devices/10"
}
]
}
]
}
location.devices.remove(id, context, httpOptions)
Use this method to delete devices.
Arguments
id
: Required. IDs of the devices to remove. This argument can be either a single value or an array of values.
context
: This argument is ignored.
Response
If you provide a single value, then the service doesn’t return a response body. The status code is 204 if the device was deleted and 404 if it doesn’t exist.
If you provide an array of IDs, then the status code is 200 for a successful request. The response contains a batch
object with an array of responses for the individual delete requests. For schema details, see the Delete Multiple Devices operation in REST API Reference for Oracle Mobile Hub -
Platform APIs.
Here’s an example:
{
"batch":[
{
"code":200,
"body":{
"id":121,
"message":"device was deleted successfully."
}
},
{
"code":200,
"body":{
"id":122,
"message":"device was deleted successfully."
}
},
{
"code":404,
"body":{
"id":123,
"message":"device not found."
}
}
]
}
Examples
In this example, if the id
query parameter contains multiple IDs, then it converts the query string into an array.
service.delete('/mobile/custom/location/devices', function(req,res) {
var contextObject = {};
var id = req.query.id.split(',');
if (id.length == 0){
id = req.query.id;
}
req.oracleMobile.location.devices.remove(
id,
contextObject
).then(
function (result) {
res.type('application/json');
res.status(result.statusCode).send(result.result);
},
function (error) {
console.dir(error);
res.status(error.statusCode).send(error.error);
}
);
});
location.devices.update(id, device, context, httpOptions)
This method lets you update a device.
Arguments
id
: Required. The ID of the device. This ID must be an existing device ID.
device
: Required. JSON object that follows the request root schema (Device) that is shown for the PUT /mobile/system/locationManagement/device/{id}
operation in REST API Reference for Oracle Mobile Hub -
Platform APIs. Here’s an example:
{
"attributes":{
"status":"Inactive",
"visibility":"Private"
}
}
context
: This argument is ignored.
Response
The response body, which shows the updated device, is a JSON object that follows the response root schema (Device) that is shown for the PUT /mobile/system/locationManagement/devices/{id}
operation in REST API Reference for Oracle Mobile Hub -
Platform APIs.
Examples
Here’s an example of using this method.
service.put('/mobile/custom/incidentreport/device/:id', function (req, res) {
req.oracleMobile.location.device.update(req.params.id, req.body).then(
function (result) {
res.type('application/json');
res.status(result.statusCode).send(result.result);
},
function (error) {
console.dir(error);
res.status(error.statusCode).send(error.error);
}
);
});
Here’s an example of the response body.
{
"id": 11,
"createdOn": "2016-11-08T18:01:18.531Z",
"createdBy": "anAdministrator",
"modifiedOn": "2016-11-08T22:45:47.545Z",
"modifiedBy": "anAdministrator",
"name": "RC_WH_01_F01_B016",
"description": "Beacon on 2nd Floor in FixitFast Warehouse in Redwood City",
"asset": {
"id": 11,
"createdOn": "2016-11-08T21:26:38.318Z",
"createdBy": "anAdministrator",
"modifiedOn": "2016-11-08T22:18:24.157Z",
"modifiedBy": "anAdministrator",
"name": "hospital bed #233",
"label": "hospital bed",
"description": "model 1225 hospital bed",
"lastKnownLocation": {
"gpsPoint": {
"longitude": -121.1566,
"latitude": 37.5548
}
},
"attributes": {
"EquipmentManufacturer": "Example Company",
"SJId": "6754843090"
},
"links": [
{
"rel": "canonical",
"href": "/mobile/platform/location/assets/11"
},
{
"rel": "self",
"href": "/mobile/platform/location/assets/11"
}
]
},
"beacon": {
"altBeacon": {
"id1": "B9407F30-F5F8-466E",
"id2": "AFF9",
"id3": "25556B57FE6D"
}
},
"attributes": {
"manufacturer": "Abc Company",
"status": "Inactive",
"manufacturerId": "10D39AE7-020E-4467-9CB2-DD36366F899D",
"visibility": "Private"
},
"links": [
{
"rel": "canonical",
"href": "/mobile/platform/location/devices/11"
},
{
"rel": "self",
"href": "/mobile/platform/location/devices/11"
}
]
}
location.places.register(places, context, httpOptions)
This method lets you create one or more places.
Arguments
places
: Required. JSON object that follows the request root schema (Places Array) that is shown for the POST /mobile/system/locationManagement/places
operation in REST API Reference for Oracle Mobile Hub -
Platform APIs. Here’s an example:
{
"items":[
{
"name":"FixItFast Redwood City Warehouse",
"label":"FixItFast Warehouse",
"parentPlace":42,
"description":"FixItFast Warehouse in Redwood City",
"address":{
"gpsPoint":{
"latitude":122,
"longitude":37
}
},
"devices":[
12345
],
"attributes":{
"hours":"9am-6pm"
}
}
]
}
context
: This argument is ignored.
Response
The response body, which shows the stored places, is a JSON object that follows the response root schema (Places Array) that is shown for the POST /mobile/system/locationManagement/places
operation in REST API Reference for Oracle Mobile Hub -
Platform APIs.
Examples
Here’s an example of calling this method.
service.post('/mobile/custom/incidentreport/places', function (req, res) {
req.oracleMobile.location.places.register(req.body).then(
function (result) {
res.type('application/json');
res.status(result.statusCode).send(result.result);
},
function (error) {
console.dir(error);
res.status(error.statusCode).send(error.error);
}
);
});
Here’s an example of the response body.
{
"items": [
{
"id": 10,
"createdOn": "2016-11-08T17:55:21.816Z",
"createdBy": "john.doe",
"modifiedOn": "2016-11-08T17:55:21.816Z",
"modifiedBy": "john.doe",
"name": "FixItFast Redwood City Warehouse",
"label": "FixItFast Warehouse",
"description": "FixItFast Warehouse in Redwood City",
"hasChildren": false,
"address": {
"gpsPoint": {
"longitude": 37,
"latitude": 89
}
},
"attributes": {
"hours": "9am-6pm"
},
"links": [
{
"rel": "canonical",
"href": "/mobile/platform/location/places/10"
},
{
"rel": "self",
"href": "/mobile/platform/location/places/10"
}
]
}
]
}
location.places.remove(id, context, httpOptions)
Use this method to delete places.
Arguments
id
: Required. IDs of the places to remove. This argument can be either a single value or an array of values.
context
: This argument is ignored.
Response
If you provide a single value, then the service doesn’t return a response body. The status code is 204 if the place was deleted and 404 if it doesn’t exist.
If you provide an array of IDs, then the status code is 200 for a successful request. The response contains a batch
object with an array of responses for the individual delete requests. For schema details, see the Delete Multiple Places operation in REST API Reference for Oracle Mobile Hub -
Platform APIs.
Here’s an example:
{
"batch":[
{
"body":{
"id":222,
"message":"place was deleted successfully."},
"code":200},
{
"body":{
"id":223,
"message":"place was deleted successfully."},
"code":200},
{
"body":{
"id":224,
"message":"place not found."},
"code":404}
]
}
Examples
In this example, if the id
query parameter contains multiple IDs, then it converts the query string into an array.
service.delete('/mobile/custom/location/places, function(req,res) {
var contextObject = {};
var id = req.query.id.split(',');
if (id.length == 0){
id = req.query.id;
}
req.oracleMobile.location.places.remove(
id,
contextObject
).then(
function (result) {
res.type('application/json');
res.status(result.statusCode).send(result.result);
},
function (error) {
console.dir(error);
res.status(error.statusCode).send(error.error);
}
);
});
location.places.removeCascade(id, context, httpOptions)
Use this method to delete a parent place and all its child places.
Arguments
id
: Required. The ID of the place. This ID must be an existing place ID.
context
: This argument is ignored.
Examples
In this example, if the cascade
query parameter is true
, then the method calls removeCascade()
instead of remove()
.
service.delete('/mobile/custom/location/places/:id', function(req,res) {
var contextObject = {};
var removeFunc = req.oracleMobile.location.places.remove;
if (req.query.cascade == 'true') {
removeFunc = req.oracleMobile.location.places.removeCascade;
}
removeFunc(
req.params.id,
contextObject
).then(
function (result) {
res.type('application/json');
res.status(result.statusCode).send(result.result);
},
function (error) {
console.dir(error);
res.status(error.statusCode).send(error.error);
}
)
});
location.places.update(id, place, context, httpOptions)
This method lets you update a place.
Arguments
id
: Required. The ID of the place. This ID must be an existing place ID.
place
: Required. JSON object that follows the request root schema (Place) that is shown for the PUT /mobile/system/locationManagement/place/{id}
operation in REST API Reference for Oracle Mobile Hub -
Platform APIs. Here’s an example:
{
"address":{
"gpsPoint":{
"latitude":-121.1566,
"longitude":37.5548
}
},
"devices":[
1111
]
}
context
: This argument is ignored.
Response
The response body, which shows the updated place, is a JSON object that follows the response root schema (Place) that is shown for the PUT /mobile/system/locationManagement/places/{id}
operation in REST API Reference for Oracle Mobile Hub -
Platform APIs.
Examples
Here’s an example of calling this method.
service.put('/mobile/custom/incidentreport/place/:id', function (req, res) {
req.oracleMobile.location.place.update(req.params.id, req.body).then(
function (result) {
res.type('application/json');
res.status(result.statusCode).send(result.result);
},
function (error) {
console.dir(error);
res.status(error.statusCode).send(error.error);
}
);
});
Here’s an example of the response body.
{
"id": 11,
"createdOn": "2016-11-08T23:36:55.371Z",
"createdBy": "anAdministrator",
"modifiedOn": "2016-11-08T23:37:45.576Z",
"modifiedBy": "anAdministrator",
"name": "FixItFast Redwood City Warehouse",
"label": "FixItFast Warehouse",
"description": "FixItFast Warehouse in Redwood City",
"hasChildren": false,
"address": {
"gpsPoint": {
"longitude": 37,
"latitude": 89
}
},
"devices": [
{
"id": 11,
"createdOn": "2016-11-08T18:01:18.531Z",
"createdBy": "anAdministrator",
"modifiedOn": "2016-11-08T22:45:47.545Z",
"modifiedBy": "anAdministrator",
"name": "RC_WH_01_F01_B016",
"description": "Beacon on 2nd Floor in FixitFast Warehouse in Redwood City",
"beacon": {
"altBeacon": {
"id1": "B9407F30-F5F8-466E",
"id2": "AFF9",
"id3": "25556B57FE6D"
}
},
"attributes": {
"manufacturer": "Abc Company",
"status": "Inactive",
"manufacturerId": "10D39AE7-020E-4467-9CB2-DD36366F899D",
"visibility": "Private"
},
"links": [
{
"rel": "canonical",
"href": "/mobile/platform/location/devices/11"
},
{
"rel": "self",
"href": "/mobile/platform/location/devices/11"
}
]
}
],
"attributes": {
"hours": "9am-6pm"
},
"links": [
{
"rel": "canonical",
"href": "/mobile/platform/location/places/11"
},
{
"rel": "self",
"href": "/mobile/platform/location/places/11"
}
]
}
Mobile Devices API
Use this API to configure which devices that are running a mobile app can receive notifications.
This API has the following methods:
-
devices.deregister(device, httpOptions): Deregister a mobile client instance that no longer needs to receive notifications..
-
devices.register(device, httpOptions): Register a mobile client instance that receives notifications.
devices.deregister(device, httpOptions)
Call this method to deregister a a mobile client instance that no longer needs to receive notifications.
Arguments
device
: Required. JSON object that follows the root (mobile client instance) request schema that’s shown for the POST /mobile/platform/devices/deregister
operation in REST API Reference for Oracle Mobile Hub -
Platform APIs.
Examples
Here’s an example of calling this method to deregister a device.
service.post(
'/mobile/custom/incidentreport/devices/deregister',
function (req, res) {
req.oracleMobile.devices.deregister(
{
"notificationToken": "b14d6dfbd9d56e09f098",
"notificationProvider: "APNS",
"mobileClient": {
"id": "my.app.id",
"platform": "IOS"
}
}
).then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
});
devices.register(device, httpOptions)
Call this method to register a new device.
Arguments
device
: Required. JSON object that follows the root (mobile client instance) request schema that’s shown for the POST /mobile/platform/devices/register
operation in REST API Reference for Oracle Mobile Hub -
Platform APIs.
Response
The response body is a JSON object that follows the root (mobile client instance) response schema that’s shown for the POST /mobile/platform/devices/register
operation in REST API Reference for Oracle Mobile Hub -
Platform APIs.
Examples
Here’s an example of calling this method to register a device.
service.post(
'/mobile/custom/incidentreport/devices/register',
function (req, res) {
req.oracleMobile.devices.register(
{
"notificationToken": "b14d6dfbd9d56e09f098",
"notificationProvider: "APNS",
"mobileClient": {
"id": "my.app.id",
"version": "1.0",
"platform": "IOS"
}
}
).then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
});
Here’s an example of the response body:
{
"id": "27fee547-bdd0-4688-9497-475ec5ed0dfd",
"notificationToken": "b14d6dfbd9d56e09f098",
"notificationProvider: "APNS",
"mobileClient": {
"id": "my.app.id",
"user": "joe",
"version": "1.0",
"platform": "IOS"
},
"modifiedOn": "2015-06-17T18:37:59.424Z"
}
My Profile API
The My Profile API let you get information about the current mobile, virtual, or social user.
This API has the following methods:
-
ums.getMe(httpOptions): Retrieves information about the current user. For mobile and virtual users, it retrieves the user’s roles.
-
ums.getUser(options, httpOptions): Retrieves the specified fields for the current mobile user, or, for social and virtual users all fields. For mobile users, you can retrieve the user name, first name, last name, and email address, as well as the fields in the user's profile from Oracle Identity Cloud Service.
-
ums.getUserExtended(options, httpOptions): This operation is deprecated.
-
ums.updateUser(fields, options, httpOptions): Updates the currently authorized mobile user's information. You can update the
firstName
,lastName
, andemail
properties as well as all the properties that are defined in the Oracle Identity Cloud Service User schema except for theusername
property.
ums.getMe(httpOptions)
This method lets you retrieve the information about the currently authorized user.
-
When the user is a mobile user, this operation retrieves the user’s information from Oracle Identity Cloud Service.
-
When the user is a virtual user, this operation retrieves the user name and roles. To learn about virtual users, see Configure SAML Tokens for Virtual Users.
-
When the user is a social user (that is, signed in using social identity), this operation retrieves the user's ID. To learn about social users and social identity, see Facebook Login in Mobile Hub.
Response
If the current user is a social user, then the response body includes the generated userName
, as shown in this example. To learn more about social identity see Facebook Login in Mobile Hub.
{
"userName": "1 :623:165"
}
If the current user is a virtual user, then the response body includes the username
and appRoles
, as shown in this example.
{
"userName":"jdoe",
"urn:ietf:params:scim:schemas:oracle:idcs:extension:user:User":{
"appRoles":[
{
"display":"FIF_TECHNICIAN"
}
]
}
}
In all other cases, the response body contains the same response as provided by Oracle Identity Cloud Service. For example:
{
"idcsCreatedBy":{
"type":"App",
"display":"instance1",
"value":"346373e8a",
"$ref":"https://myIdentity.example.com/admin/v1/Apps/3463731bd0cc43c7ba1b79a9c6e25e8a"
},
"id":"7e56fd80",
"active":true,
"displayName":"Joe Doe",
"idcsLastModifiedBy":{
"value":"346373e8aa",
"display":"instance1",
"type":"App",
"$ref":"https://myIdentity.example.com/admin/v1/Apps/3463731bd0cc43c7ba1b79a9c6e25e8a"
},
"userName":"jdoe",
"emails":[
{
"primary":true,
"value":"jdoe@example.invalid",
"type":"work"
}
],
"name":{
"familyName":"Doe",
"givenName":"Joe",
"formatted":"Joe Doe"
},
"urn:ietf:params:scim:schemas:oracle:idcs:extension:user:User":{
"grants":[
{
"value":"89d8b111",
"grantMechanism":"ADMINISTRATOR_TO_USER",
"appId":"346373e8a",
"$ref":"https://myIdentity.example.com/admin/v1/Grants/89d80073ae7f48838798cc864031b111"
}
],
"appRoles":[
{
"value":"a31245f1dd",
"adminRole":false,
"legacyGroupName":"instance1.ReadWriteRole",
"appId":"346373e8a",
"appName":"instance1_app_name",
"display":"ReadWriteRole",
"$ref":"https://myIdentity.example.com/admin/v1/AppRoles/a31245ce4ed94d2a8563d39cd888f1dd"
}
],
"accounts":[
{
"appId":"346373e8a",
"value":"3819e1be",
"active":true,
"$ref":"https://myIdentity.example.com/admin/v1/AccountMgmtInfos/3819dd966cf34aa593df61809d62e1be"
}
]
},
"urn:ietf:params:scim:schemas:idcs:extension:custom:User": {
"custom_attribute": "1076270704"
},
"schemas":[
"urn:ietf:params:scim:schemas:core:2.0:User"
]
}
Examples
Here’s an example of calling this method:
req.oracleMobile.ums.getMe().then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
ums.getUser(options, httpOptions)
This method retrieves the specified fields for the current mobile user, or, for social and virtual users, all fields. For mobile users, you can retrieve the user name, first name, last name, and email address, as well as the user's profile from Oracle Identity Cloud Service.
-
When the user is a mobile user, this operation retrieves the fields that are specified in
options.fields
, or, if theoptions.fields
property isn't provided, it retrieves the user name, first name, last name, email address, and the user's profile from Oracle Identity Cloud Service. -
When the user is a virtual user, this operation retrieves the user name. To learn about virtual users, see Configure SAML Tokens for Virtual Users.
-
When the user is a social user (that is, signed in using social identity), this operation retrieves the user's ID, identity provider, and access token. To learn about social users and social identity, see Facebook Login in Mobile Hub.
Arguments
options
: Optional. JSON object. For mobile users, this object can have the following property in addition to those listed in Common options Properties:
Property | Description | Type | Default |
---|---|---|---|
fields |
Specifies which user properties to get. For example, you can set options.fields to firstName,lastName to retrieve just those two values. Add attributes to the list to get the user's profile from Oracle Identity Cloud Service. This property is ignored if the current user signed in using virtual or social identity.
|
String | None |
Response
If the current user is a social user, then the response body includes the generated username
as well as the mobileExtended.identityProvider
properties, as shown in this example. To learn more about social identity see Facebook Login in Mobile Hub.
"username": "1 :623:165",
"mobileExtended": {
"identityProvider": {
"facebook": {
"accessToken":"CAAI...YZD"
}
}
}
If the current user is a virtual user, then the response body includes the username
, as shown in this example.
"username": "a24x"
In all other cases, the response body is a JSON object that contains one or more of the following properties, depending on the value of the request’s options.fields
property.
-
id
-
email
-
firstName
-
lastName
-
username
-
attributes
The response body also contains links to the API endpoint for the resource.
Examples
Here’s an example of calling this method to get the user’s first and last name. In this example, the user is a mobile user:
req.oracleMobile.ums.getUser({fields: 'firstName,lastName'}).then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
This example shows the response that you get when you set the options.fields
property to firstname,lastname
:
{
"firstName": "Joe",
"lastName": "Doe"
}
Here's an example of calling this method to get the fields from the users profile in Oracle Identity Cloud Service.
req.oracleMobile.ums.getUser({fields: 'attributes'}).then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
This example shows the response that you get when you set the options.fields
property to attributes
:
{
"attributes": {
"id": "2e63bfeea6a14101b91256b4036dff94",
"displayName": "Joe Doe",
"emails": [
{
"primary": false,
"secondary": false,
"value": "joe.doe@oracle.com",
"type": "recovery",
"verified": false
}
],
"name": {
"givenName": "Joe",
"familyName": "Mobile User",
"formatted": "Test Mobile User"
},
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"employeeNumber": "245562716"
},
"urn:ietf:params:scim:schemas:idcs:extension:custom:User": {
"custom_attribute": "1076270704"
},
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
"urn:ietf:params:scim:schemas:idcs:extension:custom:User"
]
}
}
ums.getUserExtended(options, httpOptions)
This operation has been deprecated.
To get user information, use ums.getMe(httpOptions) or ums.getUser(options, httpOptions) instead.
ums.updateUser(fields, options, httpOptions)
This operation updates the currently authorized mobile user's information. You can update the firstName
, lastName
, and email
properties as well as all the properties that are defined in the Oracle Identity Cloud Service User schema except for the username
property.
Arguments
fields
: Required. A JSON object that contains the fields to update. For example:{lastName: 'Doe'}
.
options
: Optional. A JSON object as described in Common options Properties.
Response
The response body is a JSON object that follows the root response schema that’s shown for the PUT /mobile/platform/users/{username}
operation in REST API Reference for Oracle Mobile Hub -
Platform APIs.
Examples
service.put(
'/mobile/custom/incidentreport/customer',
function (req, res) {
req.oracleMobile.ums.updateUser(
{
lastName: req.body.lastName,
urn:ietf:params:scim:schemas:idcs:extension:custom:User:custom_attribute: req.body.customAttribute
}).then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
});
Notifications API
You can use the Notifications API to send a message to the mobile app users, such as an alert about an upcoming event or news that the user might be interested in. You can specify a target for the message such as a device, user, or operating system, and you can schedule the message. You can also inquire about notifications, and delete scheduled notifications that haven’t been sent.
This API has the following methods:
-
notification.getAll(context, options, httpOptions): Retrieves all notifications.
-
notification.getById(id, context, options, httpOptions): Retrieves a notification for a specific notification ID.
-
notification.post(notification, context, options, httpOptions): Creates a notification.
-
notification.remove(id, context, options, httpOptions): Deletes a notification.
Note that when you access the Notifications API endpoints directly through REST requests, the user that you specify in the Authorization
header must be a team member (not a mobile user) who has the Administrator
or Developer
role.
notification.getAll(context, options, httpOptions)
This method lets you retrieve the notifications that match your criteria. Only the notifications that match ALL the criteria are returned.
Arguments
context
: This argument is ignored.
options
: Optional. JSON object. This object can have these properties in addition to those listed in Common options Properties:
Property | Description | Type | Default |
---|---|---|---|
createdOnOrAfter |
Criteria: Filter by createdOn on or after the given UTC date/time (in YYYY-DD-MM[Thh:mm]Z format).
|
String | None |
createdOnOrBefore |
Criteria: Filter by createdOn on or before the given UTC date/time (in YYYY-DD-MM[Thh:mm]Z format).
|
String | None |
limit |
The maximum number of items to be returned. If the requested limit is too large, then a lower limit is substituted. | Integer | None |
offset |
The zero-based index of the first item to return. | Integer | None |
orderBy |
Specifies the ordering for the query operations. The default sort order is ascending by ID. The format is: "orderBy" "=" 1#( attr [ ":" "asc" | "desc" ] ), where the attr parameter may be id , status , tag , platform , sendOn , createdOn , or processedOn .
|
String | None |
processedOnOrAfter |
Criteria: Filter by processedOn on or after the given UTC date/time (in YYYY-DD-MM[Thh:mm]Z format).
|
String | None |
processedOnOrBefore |
Criteria: Filter by processedOn on or before the given UTC date/time (in YYYY-DD-MM[Thh:mm]Z format).
|
String | None |
q |
Filter results based on a case-insensitive partial match of this string with the tag. For example, q=market returns notifications with tag equal to Marketing , marketing , and markets .
|
String | None |
sendOnOrAfter |
Criteria: Filter by sendOn on or after the given UTC date/time (in YYYY-DD-MM[Thh:mm]Z format).
|
String | None |
sendOnOrBefore |
Criteria: Filter by sendOn on or before the given UTC date/time (in YYYY-DD-MM[Thh:mm]Z format).
|
String | None |
status |
Criteria: Filter by status | String | None |
tag |
Criteria: Filter by tag | String | None |
Response
The response body is a JSON object that follows the notificationPaging
schema that is shown for the GET /mobile/system/notifications/notifications
operation in REST API Reference for Oracle Mobile Hub -
Platform APIs.
Examples
Here’s an example of calling this method:
service.get('/mobile/custom/incidentreport/notifications',
function (req, res) {
req.oracleMobile.notification.getAll()
.then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
});
Here’s an example of a response body.
{
"items": [
{
"id": 2,
"message": "Incident Updated: Broken Dryer",
"users": [
"J Doe"
],
"roles": [],
"notificationTokens": [],
"status": "New",
"createdOn": "2015-09-24T21:58:04.465Z",
"links": [
{
"rel": "canonical",
"href": "/mobile/system/notifications/notifications/2"
},
{
"rel": "self",
"href": "/mobile/system/notifications/notifications/2"
}
]
},
{
"id": 3,
"message": "Incident Updated: Malfunctioning Air Conditioner",
"users": [
"Lynn Smith"
],
"roles": [],
"notificationTokens": [],
"status": "New",
"createdOn": "2015-09-24T21:58:07.413Z",
"links": [
{
"rel": "canonical",
"href": "/mobile/system/notifications/notifications/3"
},
{
"rel": "self",
"href": "/mobile/system/notifications/notifications/3"
}
]
}
],
"hasMore": false,
"limit": 2,
"count": 2,
"links": [
{
"rel": "canonical",
"href": "/mobile/system/notifications/notifications/?offset=0&limit=2"
},
{
"rel": "self",
"href": "/mobile/system/notifications/notifications/"
}
]
}
notification.getById(id, context, options, httpOptions)
This method lets you retrieve a specific notification by its ID.
Arguments
id
: Required. String or integer. The generated notification ID.
context
: This argument is ignored.
options
: Optional. JSON object as described in Common options Properties.
Response
The response body is a JSON object that follows the notification
schema that is shown for the GET /mobile/system/notifications/notifications/{id}
operation in REST API Reference for Oracle Mobile Hub -
Platform APIs.
Examples
Here’s an example of calling the method to get a notification:
service.get('/mobile/custom/incidentreport/notifications/:id',
function (req, res) {
req.oracleMobile.notification.getById(req.params.id)
.then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
});
Here’s an example of a response body.
{
"id": 1,
"message": "Incident Updated: Leaky Faucet",
"users": [
"Lynn Smith"
],
"roles": [],
"notificationTokens": [],
"status": "New",
"createdOn": "2015-09-24T21:44:45.708Z",
"links": [
{
"rel": "canonical",
"href": "/mobile/system/notifications/notifications/1"
},
{
"rel": "self",
"href": "/mobile/system/notifications/notifications/1"
}
]
}
notification.post(notification, context, options, httpOptions)
This method lets you create a notification.
Arguments
notification
: Required. JSON object that follows the notificationCreate
schema that is shown for the POST /mobile/system/notifications/notifications
operation in REST API Reference for Oracle Mobile Hub -
Platform APIs. Here’s an example:
{
message:'This is the alert message.',
tag:'Marketing',
notificationTokens:['APNSdeviceToken']
}
context
: This argument is ignored.
options
: Optional. JSON object as described in Common options Properties.
Response
The return value includes this header:
Header | Description | Type |
---|---|---|
Location |
Canonical resource URI for the notification. | String |
The response body, which shows the stored notification, is a JSON object that follows the notification
schema that is shown for the POST /mobile/system/notifications/notifications
operation in REST API Reference for Oracle Mobile Hub -
Platform APIs.
Examples
In this example of posting a notification, the request body would look like this: {incidentName: 'Leaky Faucet', customerName: 'Lynn Smith'}
.
service.post('/mobile/custom/incidentreport/notifications',
function (req, res) {
var notification = {
sendOn: '2016-06-25T6:00Z',
message: 'Incident Updated: ' +
req.body.incidentName,
users: [req.body.customerName]
};
req.oracleMobile.notification.post(notification)
.then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
});
Here’s an example of the response body.
{
"id": 1,
"message": "Incident Updated: Leaky Faucet",
"users": [
"Lynn Smith"
],
"roles": [],
"notificationTokens": [],
"sendOn": "2016-06-25T06:00Z",
"status": "New",
"createdOn": "2015-06-24T21:44:45.708Z",
"links": [
{
"rel": "canonical",
"href": "/mobile/system/notifications/notifications/1"
},
{
"rel": "self",
"href": "/mobile/system/notifications/notifications/1"
}
]
}
notification.remove(id, context, options, httpOptions)
This method lets you delete a notification. You can delete a notification only if its status is Scheduled
.
Arguments
id
: Required. String or integer. The generated notification ID.
context
: This argument is ignored.
options
: Optional. JSON object as described in Common options Properties.
Example
Here’s an example of calling this method:
service.delete('/mobile/custom/incidentreport/notifications/:id',
function (req, res) {
req.oracleMobile.notification.remove(req.params.id)
.then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
});
Storage API
The Storage API lets you store mobile application objects in the cloud. An object can be text, JSON, or a binary object such as an image. These objects are grouped by collection.
This API has the following methods:
-
storage.doesCollectionExist(collectionId, options, httpOptions): Indicates if a collection exists, and, optionally, whether its ETag matches.
-
storage.doesExist(collectionId, objectId, options, httpOptions): Indicates if an object exists, and, optionally, whether its ETag matches.
-
storage.getAll(collectionId, options, httpOptions): Returns the metadata for every object in a collection.
-
storage.getById(collectionId, objectId, options, httpOptions): Retrieves an object and its metadata.
-
storage.getCollection(collectionId, options, httpOptions): Retrieves metadata about a collection.
-
storage.getCollections(options, httpOptions): Returns metadata about each collection that is available through the mobile backend.
-
storage.remove(collectionId, objectId, options, httpOptions): Removes an object from a collection.
-
storage.store(collectionId, object, options, httpOptions): Adds an object and automatically assigns an ID for it.
-
storage.storeById(collectionId, objectId, object, options, httpOptions): Adds or updates an object based on an ID that you specify.
storage.doesCollectionExist(collectionId, options, httpOptions)
You can use this method to determine whether a collection exists. You can also use it to see if the collection matches (or does not match) an ETag.
Arguments
collectionId
: Required. String. The name of the collection. When you look at the metadata for the collection, this value corresponds to the metadata’s id
value.
options
: Optional. JSON object. This object can have these properties in addition to those listed in Common options Properties:
Property | Description | Type | Default |
---|---|---|---|
encodeURI |
Set to true to URI-encode the collectionId value. This option can be useful for multibyte values.
|
Boolean | false |
ifMatch |
The call returns true only if the ETag of the corresponding object matches one of the values specified in this property.
|
String | None |
ifNoneMatch |
The call returns true only if the ETag of the corresponding object does not match one of the values specified by this property.
|
String | None |
Response
This method returns a Boolean value.
Example
The following example uses this method to verify that the collection exists before it stores an object in it.
req.oracleMobile.storage.doesCollectionExist('attachments').then(
function(result){
if (result) {
req.oracleMobile.storage.store('attachments', {id: 'incident412-pic'}, {inType: 'json'}).then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
} else {
res.status(404).send('Storage has not been configured for this app. Please contact your admin.');
};
},
function(error){
res.status(error.statusCode).send(error.error);
}
);
storage.doesExist(collectionId, objectId, options, httpOptions)
You can use this method to determine whether an object exists. You can also use it to see if the object matches (or does not match) an ETag, or if it was modified after a specified date.
Arguments
collectionId
: Required. String. The name of the collection. When you look at the metadata for the collection, this value corresponds to the metadata’s id
value.
objectId
: Required. String. The object being accessed. If the object was stored using the storage.storeById()
method, then this is the ID that was provided as the id
argument, and, if the object was stored using the storage.store()
method, then the ID was generated. When looking at the object metadata, this argument value corresponds to the metadata’s id
attribute.
options
: Optional. JSON object. This object can have these properties in addition to those listed in Common options Properties:
Property | Description | Type | Default |
---|---|---|---|
contentDisposition |
This property lets you specify the value of the Content-Disposition response header.
|
String | None |
encodeURI |
Set to true to URI-encode the collectionId , objectId , and user values. This option can be useful for multibyte values.
|
Boolean | false |
ifMatch |
The call completes successfully only if the ETag of the corresponding object matches one of the values specified in this property. | String | None |
ifModifiedSince |
Date and time in HTTP-date format. For example, Mon, 30 Jun 2014 19:43:31 GMT . The request completes successfully only if the object was modified after the date specified in this property. You can use this property to reduce the amount of data that is transported by not re-retrieving data if it hasn’t changed.
|
Date | None |
ifNoneMatch |
The call completes successfully only if the ETag of the corresponding object does not match one of the values specified by this property. You can use this property to reduce the amount of data that is transported by not re-retrieving data if it hasn’t changed. | String | None |
ifUnmodifiedSince |
Date and time in HTTP-date format. For example, Mon, 30 Jun 2014 19:43:31 GMT . The request completes successfully only if the object wasn't modified after the date specified in this property.
|
Date | None |
user |
This is the ID (not the user name) of a user. This query parameter allows a user with READ_ALL/READ_WRITE_ALL permission to access another user's isolated space. A user with READ/READ_WRITE permission may access only their own space. | String | If you are inquiring about a shared collection, there is no default.
If you are inquiring about an isolated collection, and you have READ_ALL/READ_WRITE_ALL permission, then the signed-in user is assumed unless you include this property. If you have READ_ALL/READ_WRITE_ALL permission for an isolated collection, you must include this property to inquire about objects in another user’s space. |
Response
This method returns a Boolean value.
Example
In this example, the code calls doesExist
to see if the stored object still has the same ETag as when it was last retrieved ("1"
).
req.oracleMobile.storage.doesExist('attachments', 'incident412-pic', {ifMatch: '\"' + 1 + '\"'}).then(
function (result) {
res.status(200).send('Object has not changed.');
},
function (error) {
res.status(412).send('Object was modified by someone else.');
}
)
storage.getAll(collectionId, options, httpOptions)
This method returns the metadata for every object in a collection.
Arguments
collectionId
: Required. String. The name of the collection. When you look at the metadata for the collection, this value corresponds to the metadata’s id
value.
options
: Optional. JSON object. This object can have these properties in addition to those listed in Common options Properties:
Property | Description | Type | Default |
---|---|---|---|
encodeURI |
Set to true to URI-encode the collectionId , orderBy , and user values. This option can be useful for multibyte values.
|
Boolean | false |
limit |
The maximum number of items to be returned. If the requested limit is greater than 100, then 100 is used instead. | Integer | None |
offset |
The zero-based index of the first item to return. | Integer | None |
orderBy |
Use this property to sort the results by name , modifiedBy , modifiedOn , createdBy , createdOn , or contentLength . You can append :asc or :desc to specify whether to sort in ascending or descending order. For example, modifiedOn:desc .
|
String | None |
q |
The items that are returned are based on a case-insensitive partial match of the id , name , createdBy or modifiedBy property of an item. For example, if you set this property to sam , it could return an object with an id of axsam3 and an object with a createdBy of SAMANTHA .
|
String | None |
sync |
When this property is present and has a value of true , then the return value contains the information required by the Synchronization library to cache the data locally for offline use. You can get this value from the Oracle-Mobile-Sync-Agent request header, when present.
|
Boolean | false |
totalResults |
When this property is present with a value of true , then the response body contains the totalResults attribute with a value that represents the total number of items in the collection. By default, the response does not contain this value.
|
Boolean | false |
user |
This is the ID (not the user name) of a user. Use * (wildcard) to get all users. This query parameter allows a user with READ_ALL/READ_WRITE_ALL permission to access another user's isolated space. A user with READ/READ_WRITE permission may access only their own space.
|
String | If you are inquiring about a shared collection, there is no default.
If you are inquiring about an isolated collection, and you have READ_ALL/READ_WRITE_ALL permission, then the signed-in user is assumed unless you include this property. If you have READ_ALL/READ_WRITE_ALL permission for an isolated collection, you must include this property to inquire about objects in another user’s space. |
Response
The return value includes these headers:
Header | Description | Type |
---|---|---|
Cache-Control |
Describes how the result may be cached. | String |
Oracle-Mobile-Sync-Resource-Type |
The Synchronization library uses this header. | String |
The response body is a JSON object that follows the response body schema that is shown for the GET /mobile/platform/storage/collections/{collection}/objects
operation in REST API Reference for Oracle Mobile Hub -
Platform APIs.
Examples
Here’s an example of calling this method. The response lists the objects by modified date, in descending order. Because the sync
property is set to true
, the client app can cache the response.
// Get metadata about the objects in the attachments collection.
// List most recently modified first.
service.get('/mobile/custom/incidentreport/attachments',
function (req, res) {
req.oracleMobile.storage.getAll('attachments',
{orderBy: 'modifiedOn:desc', sync: true}).then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
});
Here’s an example of a response body:
{
"items":[
{
"eTag":"\"2\"",
"id":"incident412-pic",
"createdBy":"jdoe",
"name":"Incident Picture",
"createdOn":"2014-11-20T19:57:04Z",
"modifiedOn":"2014-11-20T19:58:09Z",
"modifiedBy":"jdoe",
"links":[
{
"rel":"canonical",
"href":"/mobile/platform/storage/collections/attachments/objects/profile-pic"
},
{
"rel":"self",
"href":"/mobile/platform/storage/collections/attachments/objects/profile-pic"
}
],
"contentType":"image/png",
"contentLength":937647
},
{
"eTag":"\"1\"",
"id":"incident131-pic",
"createdBy":"jsmith",
"name":"Incident Picture",
"createdOn":"2014-11-20T18:27:02Z",
"modifiedOn":"2014-11-20T18:27:02Z",
"modifiedBy":"jsmith",
"links":[
{
"rel":"canonical",
"href":"/mobile/platform/storage/collections/attachments/objects/0683d48b-fdc5-4397-8ca2-824e2b0cae65"
},
{
"rel":"self",
"href":"/mobile/platform/storage/collections/attachments/objects/0683d48b-fdc5-4397-8ca2-824e2b0cae65"
}
],
"contentType":"image/jpeg",
"contentLength":5266432
}
],
"hasMore":true,
"limit":2,
"offset":4,
"count":2,
"totalResults":7,
"links":[
{
"rel":"canonical",
"href":"/mobile/platform/storage/collections/attachments/objects/"
},
{
"rel":"self",
"href":"/mobile/platform/storage/collections/attachments/objects?offset=4&limit=2&orderBy=name:asc&totalResults=true"
},
{
"rel":"prev",
"href":"/mobile/platform/storage/collections/attachments/objects?offset=2&limit=2&orderBy=name:asc&totalResults=true"
},
{
"rel":"next",
"href":"/mobile/platform/storage/collections/attachments/objects?offset=6&limit=2&orderBy=name:asc&totalResults=true"
}
]
}
storage.getById(collectionId, objectId, options, httpOptions)
This method retrieves an object and its metadata from a collection based on the object identifier.
Arguments
collectionId
: Required. String. The name of the collection. When you look at the metadata for the collection, this value corresponds to the metadata’s id
value.
objectId
: Required. String. The object being accessed. If the object was stored using the storage.storeById()
method, then this is the ID that was provided as the id
argument, and, if the object was stored using the storage.store()
method, then the ID was generated. When looking at the object metadata, this argument value corresponds to the metadata’s id
attribute.
options
: Optional. JSON object. This object can have these properties in addition to those listed in Common options Properties:
Property | Description | Type | Default |
---|---|---|---|
contentDisposition |
This property lets you specify the value of the Content-Disposition response header.
|
String | None |
encodeURI |
Set to true to URI-encode the collectionId , objectId , and user values. This option can be useful for multibyte values.
|
Boolean | false |
ifMatch |
The call completes successfully only if the ETag of the corresponding object matches one of the values specified in this property. | String | None |
ifModifiedSince |
Date and time in HTTP-date format. For example, Mon, 30 Jun 2014 19:43:31 GMT . The request completes successfully only if the object was modified after the date specified in this property. You can use this property to reduce the amount of data that is transported by not re-retrieving data if it hasn’t changed.
|
Date | None |
ifNoneMatch |
The call completes successfully only if the ETag of the corresponding object does not match one of the values specified by this property. You can use this property to reduce the amount of data that is transported by not re-retrieving data if it hasn’t changed. | String | None |
ifUnmodifiedSince |
Date and time in HTTP-date format. For example, Mon, 30 Jun 2014 19:43:31 GMT . The request completes successfully only if the object wasn't modified after the date specified in this property.
|
Date | None |
range |
This property lets you request a subset of bytes. For example, bytes=0–99 gets the first 100 bytes.
|
String | None |
sync |
When this property is present and has a value of true , then the return value contains the information required by the Synchronization library to cache the data locally for offline use. You can get this value from the Oracle-Mobile-Sync-Agent request header, when present.
|
Boolean | false |
user |
This is the ID (not the user name) of a user. This query parameter allows a user with READ_ALL/READ_WRITE_ALL permission to access another user's isolated space. A user with READ/READ_WRITE permission may access only their own space. | String | If you are inquiring about a shared collection, there is no default.
If you are inquiring about an isolated collection, and you have READ_ALL/READ_WRITE_ALL permission, then the signed-in user is assumed unless you include this property. If you have READ_ALL/READ_WRITE_ALL permission for an isolated collection, you must include this property to get an object from another user’s space. |
Response
The return value includes these headers:
Header | Description | Type |
---|---|---|
Accept-Ranges |
This header indicates that byte ranges may be provided when requesting an object resource. | String |
Cache-Control |
Describes how the result may be cached. | String |
Content-Disposition |
This response header is returned if the options argument included the contentDisposition property. The value for the response header is the same as the value for the property.
|
String |
Content-Length |
The size of the object in bytes. | Number |
Content-Type |
The media type of the object, such as image/jpeg .
|
String |
Etag |
Each item has an ETag value. This value changes each time the item is updated. The value includes the starting and ending quotation marks (for example, "2" ).
|
String |
Last-Modified |
The date and time when the resource was last modified. This date is in RFC-1123 format. For example, Fri, 29 Aug 2014 12:34:56 GMT .
|
Date |
Oracle-Mobile-Canonical-Link |
A relative URI that you can use to uniquely reference this object. | String |
Oracle-Mobile-Created-By |
The user name of the user who created the object. | String |
Oracle-Mobile-Created-On |
The date and time, in ISO 8601 format (for example, 2014-06-30T01:02:03Z ), when the object was created.
|
String |
Oracle-Mobile-Modified-By |
The user name of the user who last modified the object. | String |
Oracle-Mobile-Modified-On |
The date and time, in ISO 8601 format (for example, 2014-06-30T01:02:03Z ), when the object was last modified.
|
String |
Oracle-Mobile-Name |
The display name for the object. | String |
Oracle-Mobile-Self-Link |
A relative URI that you can use to uniquely reference this object within the specified isolation level. | String |
Oracle-Mobile-Sync-Expires |
This header is used by the Synchronization library. | String |
Oracle-Mobile-Sync-No-Store |
This header is used by the Synchronization library. | Boolean |
The response body is the stored object.
Example
Here is an example of calling this method. Because the sync
property is set to true
, the client app can cache the response.
req.oracleMobile.storage.getById('attachments', 'incident412-notes', {sync: true}).then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
storage.getCollection(collectionId, options, httpOptions)
This method returns metadata about a particular collection.
Arguments
collectionId
: Required. String. The name of the collection. When you look at the metadata for the collection, this value corresponds to the metadata’s id
value.
options
: Optional. JSON object. This object can have these properties in addition to those listed in Common options Properties:
Property | Description | Type | Default |
---|---|---|---|
encodeURI |
Set to true to URI-encode the collectionId value. This option can be useful for multibyte values.
|
Boolean | false |
ifMatch |
The call completes successfully only if the ETag of the corresponding object matches one of the values specified in this property. | String | None |
ifNoneMatch |
The call completes successfully only if the ETag of the corresponding object does not match one of the values specified by this property. | String | None |
sync |
When this property is present and has a value of true , then the return value contains the information required by the Synchronization library to cache the data locally for offline use. You can get this value from the Oracle-Mobile-Sync-Agent request header, when present.
|
Boolean | false |
Response
The return value includes these headers:
Header | Description | Type |
---|---|---|
Cache-Control |
Describes how the result may be cached. | String |
Etag |
Each item has an ETag value. This value changes each time the item is updated. The value includes the starting and ending quotation marks (for example, "2" ).
|
String |
The response body is a JSON object that follows the Collection
schema that is shown for the GET /mobile/platform/storage/collections/{collection}
operation in REST API Reference for Oracle Mobile Hub -
Platform APIs.
Examples
Here’s an example of calling this method. Because the sync
property is set to true
, the client app can cache the response.
req.oracleMobile.storage.getCollection('attachments', {sync: true}).then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
Here’s an example of a response body:
{
"id":"attachments",
"description":"Attachments for technician notes.",
"contentLength":6205619,
"eTag":"\"1.0\"",
"links":[
{
"rel":"canonical",
"href":"/mobile/platform/storage/collections/attachments"},
{
"rel":"self",
"href":"/mobile/platform/storage/collections/attachments"}
]}
storage.getCollections(options, httpOptions)
This method returns metadata about each collection that is available through the mobile backend.
Arguments
options
: Optional. JSON Object. This object can have these properties in addition to those listed in Common options Properties:
Property | Description | Type | Default |
---|---|---|---|
limit |
The maximum number of items to be returned. If the requested limit is too large, then a lower limit is substituted. | Integer | None |
offset |
The zero-based index of the first item to return. | Integer | 0 (zero)
|
sync |
When this property is present and has a value of true , then the return value contains the information required by the Synchronization library to cache the data locally for offline use. You can get this value from the Oracle-Mobile-Sync-Agent request header, when present.
|
Boolean | false |
totalResults |
When this property is present with a value of true , then the then the response body contains the totalResults property with a value that represents the total number of items in the collection. By default, this property is not returned.
|
Boolean | false |
Response
The return value includes these headers:
Header | Description | Type |
---|---|---|
Cache-Control |
Describes how the result may be cached. | String |
Oracle-Mobile-Sync-Resource-Type |
The Synchronization library uses this header. | String |
The response body is an array of items
in JSON format that follows the Collection Array
schema that is shown for the GET /mobile/platform/storage/collections
operation in REST API Reference for Oracle Mobile Hub -
Platform APIs.
Example
Here is an example of calling this method. Because the sync
property is set to true
, the client app can cache the response.
req.oracleMobile.storage.getCollections({sync: true}).then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
Here’s an example of a response body:
{
"items":[
{
"id":"logs",
"description":"Application logs.",
"contentLength":0,
"eTag":"\"1.0\"",
"links":[
{
"rel":"canonical",
"href":"/mobile/platform/storage/collections/logs"},
{
"rel":"self",
"href":"/mobile/platform/storage/collections/logs"}
]},
{
"id":"attachments",
"description":"Attachments for technician notes.",
"contentLength":6205619,
"eTag":"\"1.0\"",
"links":[
{
"rel":"canonical",
"href":"/mobile/platform/storage/collections/attachments"},
{
"rel":"self",
"href":"/mobile/platform/storage/collections/attachments"}
]}
],
"hasMore":false,
"limit":100,
"offset":0,
"count":2,
"links":[
{
"rel":"canonical",
"href":"/mobile/platform/storage/collections/"},
{
"rel":"self",
"href":"/mobile/platform/storage/collections?offset=0&limit=100"}
]}
storage.remove(collectionId, objectId, options, httpOptions)
This method removes an object from a collection based on the object identifier.
Arguments
collectionId
: Required. String. The name of the collection. When you look at the metadata for the collection, this value corresponds to the metadata’s id
value.
objectId
: Required. String. The ID of the object to remove.
options
: Optional. JSON object. This object can have these properties in addition to those listed in Common options Properties:
Property | Description | Type | Default |
---|---|---|---|
encodeURI |
Set to true to URI-encode the collectionId , objectId , and user values. This option can be useful for multibyte values.
|
Boolean | false |
ifMatch |
The call completes successfully only if the ETag of the corresponding object matches one of the values specified in this property. You can use this property to ensure that the operation succeeds only if the object wasn't modified after you last requested it. | String | None |
ifModifiedSince |
Date and time in HTTP-date format. For example, Mon, 30 Jun 2014 19:43:31 GMT . The request completes successfully only if the object was modified after the date specified in property.
|
Date | None |
ifNoneMatch |
The call completes successfully only if the ETag of the corresponding object does not match one of the values specified by this property. | String | None |
ifUnmodifiedSince |
Date and time in HTTP-date format. For example, Mon, 30 Jun 2014 19:43:31 GMT . The request completes successfully only if the object wasn't modified after the date specified in this property. You can use this property to ensure that the operation succeeds only if no one modified the object after that time.
|
Date | None |
user |
This is the ID (not the user name) of a user. This query parameter allows a user with READ_ALL/READ_WRITE_ALL permission to access another user's isolated space. A user with READ/READ_WRITE permission may access only their own space. | String | If you are removing an object in a shared collection, there is no default.
If you removing an object in an isolated collection, and you have READ_ALL/READ_WRITE_ALL permission, then the signed-in user is assumed unless you include this property. If you have READ_ALL/READ_WRITE_ALL permission for an isolated collection, you must include this property to remove objects from another user’s space. |
Example
This example removes an object from the attachments
collection:
service.delete('/mobile/custom/incidentreport/attachments/:id',
function (req, res) {
req.oracleMobile.storage.remove('attachments', req.params.id).then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
});
storage.store(collectionId, object, options, httpOptions)
This method lets you store an object and have an identifier automatically assigned to it.
Arguments
collectionId
: Required. String. The name of the collection. When you look at the metadata for the collection, this value corresponds to the metadata’s id
value.
object
: Required. Text, JSON object, file, or binary object. The object to store.
options
: Optional. JSON object. This object can have the following properties in addition to those listed in Common options Properties. Note that the contentType
property plays an important role for Storage, because that also specifies the mediat type to when the object is requested. If you don't include the content
, then the content-type defaults to application/octet-stream.
Property | Description | Type | Default |
---|---|---|---|
contentLength |
The size of the object in bytes. | Number | If the object is a string or a buffer, then the default is object.length . Otherwise, the default is the sum of its members’ lengths.
|
contentType |
The media type of object being stored. This property also specifies the media type to return when the object is requested. | String | If the inType is json , then the Content-Type header is set to application/json automatically. Otherwise, the default isapplication/octet-stream .
|
encodeURI |
Set to true to URI-encode the collectionId , mobileName , and user values. This option can be useful for multibyte values.
|
Boolean | false |
mobileName |
The display name for the object. If you don't include the display name, the name is set to the object identifier that this method generates automatically. | String | None |
user |
This is the ID (not the user name) of a user. This query parameter allows a user with READ_ALL/READ_WRITE_ALL permission to access another user's isolated space. A user with READ/READ_WRITE permission may access only their own space. | String | If you are storing an object in a shared collection, there is no default.
If you storing an object in an isolated collection, and you have READ_ALL/READ_WRITE_ALL permission, then the signed-in user is assumed unless you include this property. If you have READ_ALL/READ_WRITE_ALL permission for an isolated collection, you must include this property to store objects in another user’s space. |
Response
The return value includes this header:
Header | Description | Type |
---|---|---|
Location |
The URI that corresponds to the newly created object. | String |
The response body is a JSON object that follows the schema shown for the response body for the POST /mobile/platform/storage/collections/{collection}/objects
operation in REST API Reference for Oracle Mobile Hub -
Platform APIs.
Examples
In this example, requests can contain JSON objects, files, plain text, images, and so forth. If the input is a JSON object then it must set inType
to json
, and pass in req.body
for the object. Otherwise, it sets inType
to stream
, and passes in req
for the object.
service.post('/mobile/custom/incidentreport/attachments',
function (req, res) {
if (req.is('json')) {
// Must specify JSON because there is no stream to pipe from req
// as Express has read it into json and put it in req.body.
req.oracleMobile.storage.store('attachments', req.body,
{
mobileName: 'Technician Notes',
inType: 'json',
outType: 'stream'
})
.on('error', function (error) {
res.status(error.statusCode).send(error.message)
})
.pipe(res);
} else {
// For streaming, send req instead of req.body
req.oracleMobile.storage.store('attachments', req, {
mobileName: 'Technician Notes',
contentType: req.header('content-type'),
inType: 'stream',
outType: 'stream'
})
.on('error', function (error) {
res.status(error.statusCode).send(error.message)
})
.pipe(res);
}
});
In this example, the request body contains a Base-64 encoded image. The code converts it to a binary image before storing it. The request body would look like this:
{
imageName: 'brokenWaterHose',
base74EncodedImage: '/9j/4AAQSkZJRg...AFFFFAH/2Q=='
}
// Base 64
service.post('/mobile/custom/incidentreport/attachments',
function (req, res) {
// convert Base-64 encoded image to binary image
image = new Buffer(req.body.base64EncodedImage);
req.oracleMobile.storage.store('attachments', image,
{
contentType: 'image/jpeg',
mobileName: req.body.imageName
}
).then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
)
})
Here’s an example of a response body:
{
"eTag":"\"1\"",
"id":"a95edb6f-539d-4bac-9ffa-78ff16b20516",
"createdBy":"jdoe",
"name":"Technician Notes",
"createdOn":"2014-11-20T15:53:05Z",
"modifiedOn":"2014-11-20T15:53:05Z",
"modifiedBy":"jdoe",
"links":[
{
"rel":"canonical",
"href":"/mobile/platform/storage/collections/attachments/objects/a95edb6f-539d-4bac-9ffa-78ff16b20516"
},
{
"rel":"self",
"href":"/mobile/platform/storage/collections/attachments/objects/a95edb6f-539d-4bac-9ffa-78ff16b20516"
}
],
"contentType":"application/json",
"contentLength":9377
}
storage.storeById(collectionId, objectId, object, options, httpOptions)
This method stores an object based on an ID that you specify. You can use it to add an object using your own ID instead of one that is generated automatically, or to update an existing object.
Arguments
collectionId
: Required. String. The name of the collection. When you look at the metadata for the collection, this value corresponds to the metadata’s id
value.
objectId
: Required. String. If you are adding an object, this is the ID to store the object under. If you are updating an object, this is the ID of the object you are replacing.
object
: Required. Text, JSON object, file, or binary object. This is the object to store.
options
: Optional. JSON object. This object can have the following properties in addition to those listed in Common options Properties.
Property | Description | Type | Default |
---|---|---|---|
contentLength |
The size of the object in bytes. | Number | If the object is a string or a buffer, then the default is object.length . Otherwise, the default is the sum of its members’ lengths.
|
contentType |
The media type of object being stored. This property also specifies the media type to return when the object is requested. | String | If the inType is json , then the Content-Type header is set to application/json automatically. Otherwise, the default isapplication/octet-stream .
|
encodeURI |
Set to true to URI-encode the collectionId , objectId , mobileName , and user values. This option can be useful for multibyte values.
|
Boolean | false |
ifMatch |
The call completes successfully only if the ETag of the corresponding object matches one of the values specified in this property. You can use this property to ensure that the operation succeeds only if the object wasn't modified after you last requested it. | String | None |
ifModifiedSince |
Date and time in HTTP-date format. For example, Mon, 30 Jun 2014 19:43:31 GMT . The request completes successfully only if the object was modified after the date specified in property.
|
Date | None |
ifNoneMatch |
The call completes successfully only if the ETag of the corresponding object does not match one of the values specified by this property. | String | None |
ifUnmodifiedSince |
Date and time in HTTP-date format. For example, Mon, 30 Jun 2014 19:43:31 GMT . The request completes successfully only if the object wasn't modified after the date specified in this property. You can use this property to ensure that the operation succeeds only if no one modified the object after that time.
|
Date | None |
mobileName |
The display name for the object. If you don't include the display name, the name is set to the object identifier. | String | None |
user |
This is the ID (not the user name) of a user. This query parameter allows a user with READ_ALL/READ_WRITE_ALL permission to access another user's isolated space. A user with READ/READ_WRITE permission may access only their own space. | String | If you are storing an object in a shared collection, there is no default.
If you storing an object in an isolated collection, and you have READ_ALL/READ_WRITE_ALL permission, then the signed-in user is assumed unless you include this property. If you have READ_ALL/READ_WRITE_ALL permission for an isolated collection, you must include this property to store objects in another user’s space. |
Response
The response body is a JSON object that follows the schema shown for the response body for the PUT /mobile/platform/storage/collections/{collection}/objects/{object}
operation in REST API Reference for Oracle Mobile Hub -
Platform APIs.
Examples
In this example, the request can contain JSON objects, files, plain text, images, and so forth. If the input is a JSON object then it must set inType
to json
, and pass in req.body
for the object. Otherwise, it sets inType
to stream
, and passes in req
for the object.
service.put('/mobile/custom/incidentreport/attachments/:id',
function (req, res) {
if (req.is('json')) {
// Must specify JSON because there is no stream to pipe from req
// as Express has read it into json and put it in req.body.
req.oracleMobile.storage.storeById('attachments', req.params.id, req.body,
{
contentLength: req.body.length,
mobileName: 'Technician Notes',
inType: 'json',
outType: 'stream'
})
.on('error', function (error) {
res.status(error.statusCode).send(error.message)
})
.pipe(res);
} else {
// For streaming, send req instead of req.body
req.oracleMobile.storage.storeById('attachments', req.params.id, req, {
mobileName: 'Technician Notes',
contentType: req.header('content-type'),
inType: 'stream',
outType: 'stream'
})
.on('error', function (error) {
res.status(error.statusCode).send(error.message)
})
.pipe(res);
}
});
Here’s an example of a response body:
{
"eTag":"\"2\"",
"id":"incident412-notes",
"createdBy":"jdoe",
"name":"Technician Notes",
"createdOn":"2014-11-20T15:57:04Z",
"modifiedOn":"2014-11-20T15:58:09Z",
"modifiedBy":"jdoe",
"links":[
{
"rel":"canonical",
"href":"/mobile/platform/storage/collections/attachments/incident412-notes"},
{
"rel":"self",
"href":"/mobile/platform/storage/collections/attachments/incident412-notes"}
],
"contentType":"application/json",
"contentLength":9377
}
Call a Connector API from Custom Code
To use a connector, you must create a custom API and implement code that calls the SDK’s connector methods.
The custom code SDK provides two namespaces for sending requests to connectors:
-
oracleMobile.connectors.<connector>
: To use the methods in this namespace, you must explicitly declare a connector dependency inpackage.json
. The automatically generated implementations use this namespace. -
oracleMobile.connectors
: To use the methods in this namespace, you don’t need to explicitly declare a connector dependency inpackage.json
.
There are several reasons for declaring the dependency in package.json
, such as making it easier to track dependencies, and ensuring that dependent APIs are published when you publish your API. Here's an example:
{
"name" : "incidentreports",
"version" : "1.0.0",
"description" : "FixItFast Incident Reports API",
"main" : "incidentreports.js",
"oracleMobile" : {
"dependencies" : {
"connectors" : {"/mobile/connector/geocoder": "1.0"}
}
}
}
Both namespaces provide methods for each HTTP operation, as shown in this table:
HTTP Method | oracleMobile.connectors Signature | oracleMobile.connectors.<connector> Signature |
---|---|---|
GET |
get(connector, resourceName, options, httpOptions) |
get(resourceName, options, httpOptions) |
PUT |
put(connector, resourceName, object, options, httpOptions) | put(resourceName, object, options, httpOptions) |
POST |
post(connector, resourceName, object, options, httpOptions) | post(resourceName, object, options, httpOptions) |
DELETE |
del(connector, resourceName, options, httpOptions) |
del(resourceName, options, httpOptions) |
HEAD |
head(connector, resourceName, options, httpOptions) |
head(resourceName, options, httpOptions) |
OPTIONS |
options(connector, resourceName, options, httpOptions) |
options(resourceName, options, httpOptions) |
PATCH |
patch(connector, resourceName, object, options, httpOptions) | patch(resourceName, object, options, httpOptions) |
Network_HttpPatch
environment policy to control the behavior of PATCH
requests.
-
HEADER
sends aPOST
request with anX-HTTP-Method-Override
header set toPATCH
. This enables you to sendPATCH
requests when the target server doesn’t support thePATCH
method. -
LEGACY
sends aPATCH
request with anX-HTTP-Method-Override
header set toPATCH
. -
METHOD
sends aPATCH
request without anX-HTTP-Method-Override
header set toPATCH
. This is the default.
Here’s an example of using a policy setting to change the policy for MyRESTConnector:
*.connector/MyRESTConnector(1.0).Network_HttpPatch=HEADER
The method's optional options
argument can have the following connector properties in addition to the common options
properties.
Property | Description | Type | Default |
---|---|---|---|
externalAuthorization |
If you haven’t configured a security policy for the connector, then put the Authorization value for the external service in the options.externalAuthorization property. When this property is present, the connector sets the outgoing Authorization header with the value in options.externalAuthorization property before it sends the request to the external service.
|
String | None |
versionToInvoke |
The version of the connector.
When you use the When you use the |
String | The version that is declared in the package.json file. When you use the oracleMobile.connectors.<connector> namespace, the API version must be declared in package.json .
|
Here’s an example of calling the /mobile/connector/globalweather
connector using the oracleMobile.connectors
namespace:
req.oracleMobile.connectors.post('globalweather', 'GetWeather', body,
{inType: 'json', versionToInvoke: '1.0'}).then(
function (result) {
console.info("result is: " + result.statusCode);
res.status(result.statusCode).send(result.result);
},
function (error) {
console.info("error is: " + error.statusCode);
res.status(error.statusCode).send(error.error);
}
);
Here’s an example of calling the /mobile/connector/globalweather
connector using the oracleMobile.connectors.<connector>
namespace.
req.oracleMobile.connectors.globalweather.post('GetWeather', body, {inType: 'json'}).then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
If your connector is a REST API that you created using a valid descriptor, then you can create the custom API and its implementation automatically. From the Connectors page, select the connector, click More and then click Generate Custom API. If you use the automatic-generation feature, you typically don’t need to know how to use the SDK’s connector methods described here unless you are using the customizer
method that is in the generated code. For example, you might need to use a customizer to pass options.externalAuthorization
. Sometimes, you might need to replace a call to the callConnector
method with your own code, such as when you need to send multipart form data or the http
options object.
Call a REST Connector
You need the connector name and the resource name to call a REST API connector. You form the resource name by removing the base URI from the endpoint. Say, for example, that your git
connector maps to https://example.com
. To call https://example.com/{owner}/{repo}/contents/{path}
, set the resourceName
to {owner}/{repo}/contents/{path}
.
You also need to pass the authorization in either options.externalAuthorization
or httpOptions.headers['oracle-mobile-external-authorization']
.
Here’s an example of sending a PUT request to a REST connector:
service.put('/mobile/custom/incidentreport/connectors/git/:owner/:repo/contents/:path',
function (req, res) {
req.oracleMobile.connectors.idmsamples.put(
'repos/' + req.params.owner + '/' + req.params.repo + '/contents/' + req.params.path,
req.body,
{externalAuthorization: req.header('external-authorization'), inType: 'json'},
null).then(
function (result) {
// include the target service's response headers
res.set(result.headers);
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
});
You use the httpOptions
object to pass headers and query parameters to a connector.
A connector to a REST web service can have rules that set default query parameters. If you specify values for those same parameters, then your values take precedence and override the default parameters in the connector rules.
Here’s an example of passing query parameters and headers in the httpOptions
object:
service.get('/mobile/custom/incidentreport/connectors/git/:owner/:repo/contents/:path',
function (req, res) {
req.oracleMobile.connectors.idmsamples.get(
'repos/' + req.params.owner + '/' + req.params.repo + '/contents/' + req.params.path,
{externalAuthorization: req.header('external-authorization')},
{qs: {"branch": req.query.branch}, headers: {"accept": req.header('accept')}}
).then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
});
Tip:
When you usehttpOptions.qs
to pass the query string, you can use encodeURIComponent(<string>)
for the qs
value to ensure that your code handles multibyte characters.
Call a SOAP Connector
The body for a message that you send to a SOAP connector must be in either the XML or JSON form of a SOAP envelope, with an optional Header
, a required Body
, and an optional Fault
.
JSON requests are translated automatically to XML, and XML responses are translated to JSON. This means that you can interact with SOAP services without having to work with XML. If you choose to provide the message in XML, then remember to do the following:
-
To request that the response body is in XML format, set
options.accept
toapplication/xml
. -
When the request body is in XML format, set
options.contentType
toapplication/xml; charset=utf-8
. -
The XML in a request body must be wrapped in a SOAP envelope, which must include any necessary SOAP headers, as shown in this example. If you configured a security policy on a connector that requires a SOAP header to be sent in the message, That header is added automatically so you don’t need to include it in your message.
<?xml version="1.0" ?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemad.xmlsoap.org/soap/envelope"> <SOAP-ENV:Header> <!-- Add any SOAP headers here --> </SOAP-ENV> <SOAP-ENV:Body> <!-- Add the Body element here --> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
To see a sample message for a connector’s operation, go to the Test page for the connector, select the operation, and then click Examples.
Note that with SOAP connectors, if your options.contentType
property doesn’t specify the character set, then UTF-8 is assumed.
Here’s an example of calling a connector to a SOAP service. In this example, the request body is in JSON format:
service.get('/mobile/custom/incidentreport/connectors/numberConvert/:number/words',
function (req, res) {
var body = {
Header: null,
Body: {
"NumberToWords": {
"ubiNum": req.params.number
}
}
};
req.oracleMobile.connectors.post('numberConvert', 'words', body,
{inType: 'json', versionToInvoke: '1.0'}).then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
});
Call a Connector that Requires Form Data
If a connector’s operation requires a content type of multipart/form-data
, use Multer to pass the form data to the connector. Multer is a library for Node.js that handles multipart form data.
To call a connector with a request body of type multipart/form-data
:
-
Add
multer
as a dependency inpackage.json
, as shown in the following example, and then runnpm install
.{ "name": "sendformdata", "version": "1.0.0", "description": "Sends form data to a connector API.", "main": "sendformdata.js", "dependencies": { "multer": "latest" }, ... }
-
In the custom code, add the following statements:
var multer = require('multer'); var storage = multer.memoryStorage(); var upload = multer({storage: storage});
Multer adds the following objects to the incoming request body when it is of type
multipart/form-data
:-
body
: Contains the text fields that are in the form. -
files
: Contains the files that are uploaded using the form.
-
-
In the method for the operation, pass
upload.array
as the second argument and provide the name of the form’s file parameter and the maximum number of uploaded files. For example:service.post('/mobile/custom/SendFormData/upload', upload.array("avatar", 12), function (req, res)
-
Extract the content from the
body
andfiles
objects and pass it to the connector via thehttpOptions.formData
object. Note that you must make the file object look like a stream.
Here’s an example. In this example, the POST /mobile/custom/SendFormData/upload
operation requires the following form parameters:
-
username
, which is of typetext
. -
avatar
, which is of typefile
.
var multer = require('multer');
var storage = multer.memoryStorage();
var upload = multer({storage: storage});
module.exports = function (service) {
service.post('/mobile/custom/SendFormData/upload', upload.array("avatar", 12), function (req, res) {
// Because the uploaded file is a buffer in memory, you must modify it
// to look like a stream before you send it to the connector.
var uploadedFile = {
value: req.files[0].buffer,
options: {
filename: req.files[0].originalname,
contentType: req.files[0].mimetype
}
};
var formData = {
username: req.body.username,
avatar: uploadedFile
};
// FormData is the name of the connector.
// The formData object is passed in the httpOptions argument.
// The options.contentType is set to multipart/form-data automatically.
req.oracleMobile.connectors.FormData.post("upload", null, null, {
formData: formData
}).then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
});
});
};
For information about Multer, see https://www.npmjs.com/package/multer.
Pass Headers to the Target Service
With the exception of the following headers, you must use httpOptions.headers
to pass headers and their values:
-
Authorization
: If the connector doesn’t have a connectorAuthorization
header rule, or if you don’t want to use the rule’s default value, then you must pass the authorization information in either theoptions.externalAuthorization
property or thehttpOptions.headers['oracle-mobile-external-authorization']
property, as shown here. -
Connection
: Don’t set this header. -
Content-Length
: Don’t set this header. -
Host
: Don’t set this header. -
User-Agent
: Don’t set this header.
The original request’s Accept
value isn’t passed to the target service. To pass that value to the target service, use either the httpOptions.headers.accept
property or the options.accept
property.
The headers that you pass in your request override any related default values that are set by connector rules.
Here’s an example that passes headers to the target service:
var httpOptions={'headers':{}};
// You must pass the Accept header if you don't want to use the target server's default.
if (req.header('accept')) {
// You can pass the accept value using options.accept or httpOptions.header, as shown here:
httpOptions.headers.accept = req.header('accept');
};
// If the connector doesn't have an Authorization rule,
// or if you don't want to use the rule's default,
// pass the authorization information using options.externalAuthorization or
// httpOptions.headers.oracle-mobile-external-authorization.
// Note the ['']syntax to prevent the hyphen from being interpreted as a minus.
if (req.header('external-authorization')) {
httpOptions.headers['oracle-mobile-external-authorization'] =
req.header('external-authorization');
};
// Pass any custom headers
if (req.header('if-none-match')) {
httpOptions.headers['if-none-match'] = req.header('if-none-match');
};
req.oracleMobile.connectors.git.get('repos/fixItFast/incidentreport/contents/README.md',
null,
httpOptions).then(
function (result) {
// include the target service's headers
res.set(result.headers);
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
Override SSL Settings for Connectors
You might encounter issues with external services, such as the service has an invalid SSL certificate or it redirects the request but it doesn't preserve the cookies over the redirect.
To resolve these issues, you use the options
argument to customize the outgoing HTTP requests, which go through a proxy. You can get the proxy from req.oracleMobile.proxy.httpProxy
. Here’s an example of how to override the strictSSL setting in order to ignore SSL validation issues.
var res = {};
var options = {
uri: req.body.externalURI,
strictSSL: false,
proxy: 'http://' + req.oracleMobile.proxy.httpProxy
}
req(options).pipe(res);
To learn more about request options, see https://github.com/request/request#requestoptions-callback
.
Call a Custom API from Custom Code
The custom code SDK provides two namespaces for sending requests to other custom APIs:
-
oracleMobile.custom.<apiName>
: To use the methods in this namespace, you must explicitly declare inpackage.json
a dependency on the custom API. -
oracleMobile.custom
: To use the methods in this namespace, you don’t need to explicitly declare inpackage.json
a dependency on the custom API.
There are several reasons for declaring the dependency in package.json
, such as making it easier to track dependencies, and ensuring that dependent APIs are published when you publish your API. Here's an example:
{
"name" : "incidentreports",
"version" : "1.0.0",
"description" : "FixItFast Incident Reports API",
"main" : "incidentreports.js",
"oracleMobile" : {
"dependencies" : {
"apis" : {"/mobile/custom/motd" : "1.0"}
}
}
}
Both namespaces provide methods for each HTTP operation, as shown in this table:
HTTP Operation | oracleMobile.custom Method | oracleMobile.custom.<apiName> Method |
---|---|---|
GET |
get(apiName, resourceName, options, httpOptions) |
get(resourceName, options, httpOptions) |
PUT |
put(apiName, resourceName, object, options, httpOptions) | put(resourceName, object, options, httpOptions) |
POST |
post(apiName, resourceName, object, options, httpOptions) | post(resourceName, object, options, httpOptions) |
DELETE |
del(apiName, resourceName, options, httpOptions) |
del(resourceName, options, httpOptions) |
HEAD |
head(apiName, resourceName, options, httpOptions) |
head(resourceName, options, httpOptions) |
OPTIONS |
options(apiName, resourceName, options, httpOptions) |
options(resourceName, options, httpOptions) |
PATCH |
patch(apiName, resourceName, object, options, httpOptions) | patch(resourceName, object, options, httpOptions) |
The optional options
argument can have the versionToInvoke
property in addition to the common options
properties.
Property | Description | Type | Default |
---|---|---|---|
versionToInvoke |
The version of the custom API.
When you use the When you use the |
String | The version that is declared in the package.json file.
|
Here are examples of how to call another custom API from custom code using both namespaces . These examples call the motd
custom API, and send a POST request to its years/{year}/months/{month}/days
resource.
/**
* oracle.Mobile.custom.<apiName> namespace example:
*
* <namespace>.post(<resource>, <body>, <options>)
*
* Note: Because it uses the
* oracleMobile.custom.<apiName> namespace,
* the dependency on the motd API must
* be specified in package.json.
* options.versionToInvoke isn't required. You can use
* it to override the version that is declared in
* package.json.
*/
req.oracleMobile.custom.motd.post(
'years/2018/months/1/days',
req.body,
{inType: 'json'}).then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
/**
* oracle.Mobile.custom namespace example:
*
* post(<namespace>, <resource>, <body>, <options>)
*
* You must include the versionToInvoke option if
* the API isn't declared in package.json.
*/
req.oracleMobile.custom.post(
'motd',
'years/2018/months/1/days',
req.body,
{versionToInvoke: '1.0', inType: 'json'}).then(
function (result) {
res.status(result.statusCode).send(result.result);
},
function (error) {
res.status(error.statusCode).send(error.error);
}
);
Specify the API Version in Calls to Custom and Connector APIs
When you call connector APIs or other custom APIs, you must always specify the API version. You can specify the API version in one of the following ways:
-
Explicitly state the version dependency in the implementation’s
package.json
file, as shown here. You must do this if you are using methods in theoracleMobile.connectors.<connector>
ororacleMobile.custom.<apiName>
namespace.{ "name" : "incidentreports", "version" : "1.0.0", "description" : "FixItFast Incident Reports API", "main" : "incidentreports.js", "oracleMobile" : { "dependencies" : { "apis" : {"/mobile/custom/motd" : "1.0"}, "connectors" : {"/mobile/connector/geocoder": "1.0"} } } }
In this example, a call to any method in the
oracleMobile.custom.motd
namespace uses version 1.0 by default. -
Include the
options.versionToInvoke
property in the request and set it to the version that you want to use (represented as a string). If you specify the version number this way, then it overrides what you may have specified in thepackage.json
file.req.oracleMobile.custom.post( 'motd', 'years/2018/months/1/days', req.body, {versionToInvoke: '1.0', inType: 'json'}).then( function (result) { res.status(result.statusCode).send(result.result); }, function (error) { res.status(error.statusCode).send(error.error); } );
If you are using a method from the generic
oracleMobile.rest
namespace, put the version in theOracle-Mobile-API-Version
header instead of theoptions.versionToInvoke
property.
When you declare dependencies using the package.json
file, then it’s easier to keep track of those dependencies than when you use the options.versionToInvoke
property to declare dependencies. When you use package.json
for this purpose, the API Designer displays the dependencies in a table below the list of implementations. When you prepare to publish your API, you’re prompted to publish any unpublished dependent APIs.
However, if you use the options.versionToInvoke
property to declare the version of a dependent API, the API Designer won’t be aware of that dependency and won’t prompt you with information when you publish the calling API. In this case, you’ll need to remember to publish the dependent API yourself.
Legacy Generic REST Methods
Earlier versions of the custom code SDK used oracleMobile.rest
methods to access custom, platform, and connector APIs. To ensure backwards compatibility, these methods continue to be available.
The legacy methods take two options: optionsList
, which you use to pass request details, and handler
, which is an optional function to be executed by the method. If you don’t include the handler
argument, then the method returns a promise. A promise represents the result of an asynchronous request. At the time it is issued, the request may or may not have completed. You typically use a promise with the then
function.
If the handler
function makes calls to other custom, platform, or connector APIs, then you must follow Request.js conventions as described at https://github.com/request/request
.
handler
argument. They always return a promise.
HTTP Operation | oracleMobile.rest Methods |
---|---|
GET |
get(optionsList, handler)
|
PUT |
put(optionsList, handler)
|
POST |
post(optionsList, handler)
|
DELETE |
del(optionsList, handler)
|
HEAD |
head(optionsList, handler)
|
OPTIONS |
options(optionsList, handler)
|
PATCH |
patch(optionsList, handler)
|
Here’s an example of using an oracleMobile.rest
method to access the Database Service API. Notice how it uses optionsList
to pass in the URI and query string, and to convert the request body to JSON.
// The request body looks like this
// {title:'Water heater is leaking', technician:'jwhite',customer:'Lynn Smith'}
service.post('/mobile/custom/incidentreport/incidents',
function (req, res) {
var optionsList = {
uri: '/mobile/platform/database/objects/FIF_Incidents',
qs: req.query,
json: req.body,
headers: {
'Oracle-Mobile-Extra-Fields': 'createdBy,createdOn'
}
};
req.oracleMobile.rest.post(optionsList, function (error, response, body) {
var message = error ? error.message : body;
res.status(response.statusCode).send(message);
});
});
optionsList Argument
You use the optionsList
argument to pass request details in oracleMobile.rest
calls, such as the URI, the body, and the headers. Here are some examples of the options that you can configure:
- body
-
This option contains the body for a
patch
,post
, orput
request. The value must be aBuffer
or aString
unlessOptionsList.json
is set totrue
. IfOptionsList.json
istrue
, then the body must be a JSON-serializable object. See also thejson
option in this list. - headers
-
This option contains a list of HTTP headers. For example:
optionsList.headers= {Content-Type : 'application/json;charset=UTF-8'};
Note:
When you use thejson
option, you do not need to provide the Content-Type header. For all other cases, when the request has a body, include this header and specify the charset. - json
- This option can be used in two ways:
-
To hold a JavaScript object. In this case, when the request is sent, the object is converted to JSON and put in the HTTP body, and the
Content-Type: application/json
header is added automatically. -
To indicate, by setting the value to
true
, that theoptionsList.body
value is a JavaScript object. In this case, when the request is sent, theoptionsList.body
value is converted to JSON and put in the HTTP body, and theContent-Type: application/json;charset=UTF-8
header is added automatically.
-
- timeout
-
This option specifies the number of milliseconds to wait for a request to respond before terminating the request. If you don’t provide this option, then the timeout value defaults to the time out that’s specified by the
Network_HttpRequestTimeout
environment policy.The value shouldn’t be greater than the
Network_HttpRequestTimeout
environment policy for the environment that the implementation is deployed to. Ask your cloud administrator for the value of this policy setting.If the target URI is a connector, then the value should be greater than the
Network_HttpConnectTimeout
andNetwork_HttpReadTimeout
policies for the connector. These values are displayed on the connector’s configuration page. - uri
-
This required option contains the URL fragment that uniquely identifies the API to call. For example:
/mobile/platform/storage/collections/coll1/objects
In addition to the options listed here, you can provide any of the options that are specified by the Request.js API. Go to the API documentation at https://github.com/request/request
and scroll down to the section entitled "request(options, callback)
".
Learn About Your Instance's Custom, Platform, and Connector APIs
You can use the API catalog to learn about the platform, custom, and connector APIs. To access the API catalog, click to open the side menu and then select APIs.
-
To see the endpoints for a platform API, scroll to the bottom of the API Catalog, and then select the API.
-
To see the endpoints for a custom API or connector API, open a custom API, click Implementations, and then click Custom Code API Catalog. From the Show list, select Connector APIs or select Mobile APIs depending on the API type, and then select the API to view its endpoints.
In addition to the API Catalog, REST API Reference for Oracle Mobile Hub - Platform APIs provides information about the platform APIs. For example, it provides cURL examples as well as details about request and response bodies and headers.