Oracle Management Cloud APM REST API

Quick Start

Set up your environment and use Oracle Application Performance Monitoring Cloud Service REST APIs by following the steps below.

Prerequisites

Obtain a trial or paid subscription to Oracle Application Performance Monitoring Cloud Service (APMCS). For more information, see Manage Subscriptions.

Step 1: Obtain Account Information

From your account administrator, obtain the appropriate account credentials to access Oracle APMCS. Specifically, you need:

User name and password
Identity domain name

Step 2: Install cURL

The examples within this document use the cURL command-line tool to demonstrate how to access the Oracle APMCS REST APIs.

For information about downloading and installing cURL, see http://curl.haxx.se/download.html. You must install a version of cURL that supports SSL.

Once installed, set the cURL environment variable, CURL_CA_BUNDLE, to the location of an SSL certificate authority (CA) certificate file or bundle to authenticate against the Verisign CA certificate. Alternatively, you can specify the location of your local CA certificate bundle on the command line, using the cacert command line option. For example, on a Windows system you would use:

C:\curl> set CURL_CA_BUNDLE=ca-bundle.crt

You can download an SSL CA certificate bundle from http://curl.haxx.se/docs/caextract.html or provide your own. For information about CA certificate verification using cURL, see: http://curl.haxx.se/docs/sslcerts.html.

Step 3: Using cURL

Specify one or more of the following command-line options, as required, to direct the execution of cURL. The following table summarizes the cURL options used in the command examples in this document.

For more command line options refer to http://curl.haxx.se/docs/manpage.html.

`cURL` Option	Description
`-d, --data @file.json`	Identifies the request document, in JSON format, on the local machine.
`-F, --form @file.json`	Identifies form data, in JSON format, on the local machine.
`-H, --header headerInfo`	Defines one or both of the following: Content type of the request document (for example, `-H "Content-type:application/json"`) Custom header, `X-ID-TENANT-NAME` or `X-USER-IDENTITY-DOMAIN-NAME`, to identify the identity domain
`-i, --include`	Include HTTP response header information in the output. Useful for those commands that do not generate a JSON response.
`-u, --user username:password`	Specifies the user name and password for the Oracle APMCS account.
`-X, --request requestType`	Indicates the type of request (for example, `GET`, `POST`, and so on). If none specified then defaults to `GET`).

Step 4: Authentication

Oracle APMCS uses a certificate authority (CA) certificate, issued by Verisign, to enable clients to connect securely to the server.

Ensure that you have the appropriate log-in credentials for accessing Oracle APMCS REST APIs.

To access the REST resources over HTTPS, you must provide the following information for authentication:

An SSL certificate authority (CA) certificate file or bundle to authenticate against the Verisign CA certificate.
User name and password for your Oracle APMCS account.
Custom header, X-ID-TENANT-NAME or X-USER-IDENTITY-DOMAIN-NAME, to identify the identity domain.

Step 5: Run Your First REST API Client

If you're a pro, or you're already familiar with APMCS, then you're now ready to send requests to Oracle APMCS REST API using cURL. The following example retrieves Server Request metric data, which is returned as JSON:

curl -X GET -u sandy@example.com:Welcome1!
  -H "X-USER-IDENTITY-DOMAIN-NAME: APMExampleIdentityDoamin"
  https://apmcs.oraclecloud.com/serviceapi/apm.dataserver/api/v1/requests

If, on the other hand, you're just getting to know APMCS and the REST API resources and operations, then read the brief APMCS Overview, and follow that with the quick tutorial, From UI to REST API, to learn how the APMCS UI uses the REST API described further in this document. After that you'll be ready to try it out yourself.

Prerequisites

Here are the prerequisites you will need to have before using the REST API for Oracle Management Cloud.

From your account administrator, obtain the appropriate account credentials for accessing Oracle Management Cloud. Specifically, you will need:

Username
Password
REST URL

You can find your REST URL by:

Login to your Oracle Management Cloud UI.
Select Administration, then click Agents.
Select the Navigation Menu, then click Download Agents.
In Agent Type, select Cloud Agent.

OMC_URL is the REST endpoint you need to use to communicate with the REST API for Oracle Management Cloud.

OMC_URL follows the format: https://<subdomain>.<domain>.com:<port>/<resource-path>

Install cURL

The examples within this document use the cURL command-line tool to demonstrate how to access the Oracle Management Cloud REST API.

To connect securely to the server, install a cURL version that supports SSL and provide an SSL certificate authority (CA) certificate file or bundle to authenticate against the Verisign CA certificate. For more information about:

Using cURL, see Use cURLs.
Authentication, see Authentication.

The following procedure demonstrates how to install cURL on a Windows 64-bit system.

In your browser, navigate to the cURL home page at http://curl.haxx.se and click Download in the left navigation menu.
On the cURL Releases and Downloads page, locate the SSL-enabled version of the cURL software that corresponds to your operating system, click the link to download the ZIP file, and install the software.
Navigate to the cURL CA Certs page at http://curl.haxx.se/docs/caextract.html and download the ca-bundle.crt SSL CA certificate bundle in the folder where you installed cURL.
Open a command window, navigate to the directory where you installed cURL, and set the cURL environment variable, CURL_CA_BUNDLE, to the location of an SSL certificate authority (CA) certificate bundle. For example:

C:\curl> set CURL_CA_BUNDLE=ca-bundle.crt

You are now ready to send requests to the Oracle Management Cloud REST API using cURL.

Note:

You will be prompted for a password if it's not passed as a header.

Send Requests

Use the following guidelines when sending requests using the REST API for Oracle Management Cloud.

URL Structure

Access the Oracle Management Cloud REST resources using the following URL structure:

https://<subdomain>.<domain>.com:<port>/<resource-path>

Where:

<subdomain.domain>.com:<port> is the REST endpoint URL of the site in which you want to manage Oracle Management Cloud resources.
<resource-path> Relative path that defines the resource.

Supported Methods

You can perform basic CRUD operations (create, read, update, and delete) using standard HTTP method requests, as summarized in the following table.

HTTP Method	Description
`GET`	Retrieve information about Oracle Management Cloud resources such as entities or entity types.
`HEAD`	Retrieve header information about Oracle Management Cloud.
`POST`	Create or update resources for Oracle Management Cloud such as entities or entity Types.
`PUT`	Update Oracle Management Cloud resources.

Media Types

The following media types are supported by the REST API for Oracle Management Cloud:

application/json

Supported Headers

The REST API for Oracle Management Cloud supports the following headers that may be passed in the header section of the HTTP request or response.

Header	Description	Example
`Accept-Encoding`	List of acceptable encodings to support compression.	`Accept-Encoding: gzip`
`Content-Encoding`	List of acceptable encodings to support compression.	`Content-Encoding: deflate`
`Content-Type`	Media type of the body of the request. Required for POST and PUT requests.	`Content-Type: application/json`
`X-ID-TENANT-NAME`	Identity domain name of the <product name>, used for authentication.	`X-ID-TENANT-NAME:ExampleIdentityDomain`

cURL Access

The examples within this document use cURL to demonstrate how to access the REST API for Oracle Management Cloud.

Invoke cURL and specify one or more of the command-line options defined in the following table, as required, to direct its execution

cURL Option	Description
`-d, --data @file.json`	Identifies the request document, in JSON format, on the local machine.
`-F, --form @file.json`	Identifies form data, in JSON format, on the local machine.
`-H`	Defines one or both of the following: Content type of the request document Custom header, `X-ID-TENANT-NAME`, to identify the identity domain
`-i`	Displays response header information.
`-u, --user username:password`	Specifies the user name and password for the Oracle Management Cloud account.
`-X`	Indicates the type of request (for example, GET, POST, and so on).

For example:

curl -X GET -u <username>:<password> -H <request-header>:<value> https://<subdomain>.<domain>.com/<path>/<resource-path>

Status Codes

When you call any of the Oracle Management Cloud REST resources, the Response header returns one of the standard HTTP status codes defined in the following table. :

HTTP Status Code	Description
`200 OK`	The request was successfully completed. A 200 status is returned for a successful `GET` or `POST` method.
`201 Created`	The request has been fulfilled and resulted in a new resource being created. The response includes a Location header containing the canonical URI for the newly created resource. A 201 status is returned from a synchronous resource creation or an asynchronous resource creation that completed before the response was returned.
`202 Accepted`	The request has been accepted for processing, but the processing has not been completed. The request may or may not eventually be acted upon, as it may be disallowed at the time processing actually takes place. When specifying an asynchronous (`__detached=true`) resource creation (for example, when deploying an application), or update (for example, when redeploying an application), a 202 is returned if the operation is still in progress. If `__detached=false`, a 202 may be returned if the underlying operation does not complete in a reasonable amount of time. The response contains a Location header of a job resource that the client should poll to determine when the job has finished. Also, returns an entity that contains the current state of the job
`400 Bad Request`	The request could not be processed because it contains missing or invalid information (such as, a validation error on an input field, a missing required value, and so on). For `limit` parameters, the value cannot exceed the maximum of 2000.
`401 Unauthorized`	The request is not authorized. The authentication credentials included with this request are missing or invalid.
`403 Forbidden`	The user cannot be authenticated. The user does not have authorization to perform this request.
`404 Not Found`	The request includes a resource URI that does not exist.
`405 Method Not Allowed`	The HTTP verb specified in the request (`DELETE`, `GET`, `POST`, `PUT`) is not supported for this request URI.
`406 Not Acceptable`	The resource identified by this request is not capable of generating a representation corresponding to one of the media types in the Accept header of the request. For example, the client's Accept header request XML be returned, but the resource can only return JSON.
`409 Incorrect State`	The specified group already exists. A group name must be unique and cannot be updated once created.
`415 Not Acceptable`	The client's ContentType header is not correct (for example, the client attempts to send the request in XML, but the resource can only accept JSON).
`500 Internal Server Error`	The server encountered an unexpected condition that prevented it from fulfilling the request.
`503 Service Unavailable`	The server is unable to handle the request due to temporary overloading or maintenance of the server. The Oracle Management Cloud REST web application is not currently running.