1. MySQL Cloud Service REST APIREST API for MySQL Cloud Service
  2. Send Requests

Send Requests

Use the following guidelines when sending requests using the MySQL Cloud Service REST API.

General Considerations

When defining a RESTful query, it is helpful to understand the following:

  • Multiple queries might have identical URLs (resource-path) but use different HTTP methods. For example, viewing a MySQL service instance's details (GET) and deleting the same instance (PUT).

  • Most queries use application/json for the Content-Type HTTP header, but some queries require setting Content-Type to a different value. The same is true for the Accept HTTP header.

  • Most queries do not use a request body (data) and instead define all options using the resource-path or HTTP headers. Those that do define a request body typically require one, even if it's an empty JSON object: {}.

  • The Basic HTTP Authentication method is used for all queries. The X-ID-TENANT-NAME HTTP header is required for all queries, and is set to your identity domain.

  • Most cURL examples in this document pass in the -i curl parameter to include HTTP headers in the response, but this is optional.

  • The documentation page for each query is separated into three sections. The Request section is specific to creating the request (what you send to the server), the Response section describes the response that the server sends back after you make the request, and the Examples section demonstrates usage and also includes additional details.

URL Structure

Use the following URL structure to access the REST endpoints: 
https://region-prefix.oraclecloud.com/resource-path
Where:

  • region-prefix

    The URL prefix based on general region. Typical values include:

    • United States: psm.us

      For example: https://psm.us.oraclecloud.com/resource-path

    • Europe: psm.europe

      For example: https://psm.europe.oraclecloud.com/resource-path

    To find the region prefix for a cloud service REST endpoint:

    1. Sign in to the My Services dashboard for your identity domain.

    2. Click one of your cloud services and go its Service Details page.

    3. The REST Endpoint field shows the URL to the REST server for this service, including your region prefix.

  • resource-path

    A relative path that defines the REST endpoint. For a complete list of REST endpoints, see All REST Endpoints. Documentation under the Tasks section describes these endpoints, as does the associated swagger.json file listed under Download.

    • Path Variables:

      Most resource-path definitions include strings surrounded by curly braces, such as {identityDomainId} and {serviceId}. Replace these with your own values.

      Common path variables defined in most resource-path definitions are:

      • {identityDomainId}: The identity domain, this is also used when you login to Oracle Cloud. This is also known as the "tenant.".

      • {serviceId}: Also known as "Service Name", this id is set when the MySQL service is created. It is a unique name within the identity domain.

      Other values include:

      • {jobId}: Most actions create job ids and return their value in the response, and some paths accept this numeric value.

      • {ruleName}: Name of an access rule defined for a MySQL service. User-defined for new rules, and default rules also exist.

      • {backupId}: Each MySQL service backup has an associated unique backup id.

      • {snapshotName}: Unique name for the snapshot defined when the snapshot is created. User-defined.

      • {patchId}: Identifier of the available patch, such as "5.7.16-EE".

      • {rollbackId}: Applied patches define a rollback id that is used to roll back (undo) a patch. View a patch's status to find this numeric id.

      • {credentialName}: Name of the particular SSH credential, such as "vmspublickey" when adding a public SSH key. Also known as "credName".

      • {function}: Used when controlling the service's lifecycle state, such as start, stop, or restart.

    • An Example Path:

      /paas/api/v1.1/instancemgmt/{identityDomainId}/services/MySQLCS/instances/{serviceId}

      Where {identityDomainId} and {serviceId} are replaced with your values.

    • Note:

      It is important that the correct combination of resource-path and HTTP method is used. For example, two different options might have the same exact path but with a different HTTP method.

Tip: One method to beautify returned JSON is to redirect (pipe) output into a JSON formatter, such as json_pp. For example, curl -X GET ... https://rest_server_url/paas/api/v1.1/... |json_pp where "..." are replaced with your values. Note that Curl's "-i" is not used as json_pp only expects JSON, and not the HTTP header information.

Supported Methods

Perform basic CRUD operations (create, read, update, and delete) on your MySQL Cloud Service using standard HTTP request methods.

HTTP Method Description
GET Retrieve information about the MySQL Cloud Service instance.
POST Create, scale, backup, start, or stop the MySQL Cloud service instance.
PUT Update or delete the MySQL Cloud Service instance.

Media Types

The following media types are supported by the Oracle MySQL Cloud Service REST API:

  • application/json

    Used by most requests.

  • application/vnd.com.oracle.oraclecloud.provisioning.Service+json

    For example, the required Content-Type value for the "Create an Oracle MySQL Cloud Service Instance" query.

Supported Headers

The REST API supports headers that may be passed in the header section of an HTTP request or response.

Header Description Example
Content-Type Media type of the body of the request. Required for POST and PUT requests, and the supported types vary with each endpoint. Content-Type: application/json
Accept Media type of the body of the response. Accept: application/json
X-ID-TENANT-NAME Identity domain ID of the MySQL Cloud Service, used for basic authentication. This is required for all queries. X-ID-TENANT-NAME:ExampleIdentityDomain