Conventions

A consistent set of conventions are followed to provide an easy and reliable environment to learn and use the Oracle IoT Production Monitoring Cloud Service REST API.

URL Structure

Access the Oracle IoT Production Monitoring Cloud Service REST API resources using the following URL structure :

https://instanceName-identityName.dataCenter.oraclecloud.com/productionMonitoring/clientapi/v2/resource-path

Where:

• instanceName - Name you chose for your Oracle IoT Cloud Service when it was provisioned.

• identityName - Identity name you chose when you signed up with Oracle Public Cloud.

• dataCenter - Data center that your service is set up to use.

• resource-path - Relative path that defines the resource. For a complete list of resources, see REST Endpoints.

The following example illustrates how to use this URL structure:

GET https://myiotcsiotjls-agallardo.uscom-central-1..oraclecloud.com/productionMonitoring/clientapi/v2

URN Syntax

Uniform Resource Names (URNs) represents persistent, location-independent, resource identifiers.

All URNs have the following syntax: <URN> ::= "urn" <NID> ":" <NSS>

Note that the leading "urn" sequence is case insensitive.

<NID> is the namespace identifier and <NSS> is the namespace specific string.

Content Types

The JSON content produced by Oracle IoT Production Monitoring Cloud Service is pretty printed, meaning that it is produced in a human readable format with line breaks and tabs. It is expected that most clients will utilize gzip encoding to compress requests and responses.

HATEOAS Responses

Calls made to the Oracle IoT Cloud Service REST API returns various responses that are based on HATEOAS (Hypermedia as the Engine of Application State). This means that, in various responses, a client always receives links to additional information, rather than having to hard-code or provide special-case handling of responses to construct subsequent links. See The Spring Framework for a good definition.

Within Oracle IoT Production Monitoring Cloud Service, responses for every document (except Messaging) contain links to the URI that produced the document, as well as a link to the root document URI. The following example shows a request for endpoints:

GET https://myiotcsiotjls-agallardo.uscom-central-1.oraclecloud.com/productionMonitoring/clientapi/v2/products?fields=id,description

The resulting response is shown below:

{
     "items":[
        {
           "id": 0-MI,
           "description": "Tab"
        },
        {
           "id": 0-AH, 
           "description": "Cubes" 
        },
        {
           "id": 0-IG,
           "description": "Thermostat"
        }
     ],
     "links":[
        {  "rel":"canonical",
           "href":http://iotserver/iot/api/v1/products },
        {  "rel":"self",
           "href":http://iotserver/iot/api/products?fields=id,description 
     ]
}

In the above response, the cannonicalLink and selfLink info are included. The canonicalLink is a link to the base URI for this resource and the selfLink refers to the actual URI used to retrieve this specific resource representation, including query parameters (but not headers).

Additional attributes are returned for documents where the results are due to pagination results of a query (i.e.: using offset and limit query parameters).

Naming Conventions

By convention, resource collections are always plural, and each resource is given a unique ID. For example, the resource representing the collection of all products would be /productionMonitoring/clientapi/v2/products, while the resource representing the endpoint with id 101 would be /productionMonitoring/clientapi/v2/products/101. This is referred to in the documentation as /productionMonitoring/clientapi/v2/products/{product-id}.

Also by convention, the API is versioned as v1 or v1.1. We only include the decimal in the version number when required, and prefix with a lower-case letter "v". Every API access includes the version.

Date Formats

When sending dates in requests and responses in JSON, the date is always formatted as YYYY-MM-DDTHH:MM:SS[.sss]Z. In the Java language, this can be constructed by the following code snippet:

new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'")

Requests with incorrectly formatted dates will be refused.