REST API for the Management Service in Oracle API Platform Cloud Service

Quick Start

Create your first API using the REST API for the Management Service in Oracle API Platform Cloud Service by performing the following tasks.

Prerequisites

Prerequisite	More Information
Provision your Oracle API Platform Cloud Service instance.	See Creating an Oracle API Platform Cloud Service Instance in Using Oracle API Platform Cloud Service.

User Roles and Permissions

Roles determine which resource a user is authorized to access and the grants they are eligible to receive. Each resource in this document describes the roles and grants required to perform the action.

Note:

System Administrators possess the rights of all other roles and are eligible to receive grants for all objects in the system.

For more information on Roles and Grants, see About Oracle API Platform Cloud Service Roles, Resources, Actions, and Grants in Using Oracle API Platform Cloud Service.

Step 1: Obtain Account Information

From your account administrator, obtain the appropriate account credentials to enable you to create APIs. Specifically, you will need:

Username and password
The API Manager role in Oracle API Platform Cloud Service or membership to a group assigned the API Manager role

Note: other operations may require different roles and grants. See each operation for details.

Step 2: Install cURL

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

To connect securely to the server, you must install a version of cURL 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 cURL.
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 cacert.pem 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=cacert.pem

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

Step 3: Create Your First API

The following cURL example creates an API with Oracle API Platform Cloud Service. No polices are applied (also known as a passthrough API); only the API Request URL and Service Request URL are configured.

curl -i -X POST 
-H "Authorization: Bearer access_token" 
-H "Content-Type: application/json"
-d @api.json
https://example.com/apiplatform/management/v1/apis

Note:

In releases prior to 18.2.5, the REST endpoints were protected using Basic Authorization instead of OAuth. If you are using an earlier version, you must specify an Authorization header whose value contains the base 64-encrypted user name and password (separated by a colon) of an Oracle API Platform Cloud Service user with authorization to perform the requested operation. This header looks like:

Authorization: Basic base64-encrypted-username:base64-encrypted-password

The following is the sample of the request body to create your first API. Use this template (after editing the name and version) to create an empty API:

{
	"name": "weather",
	"version": "v1",
	"implementation":
	{
		"policies":[
					{ "id":"1", "type":"o:ApiRequest", "version":"1.0", "draft":true, "config":{}},
					{ "id":"2", "type":"o:ServiceRequest", "version":"1.0", "draft":true, "config":{}},
					{ "id":"3", "type":"o:ServiceResponse", "version":"1.0", "config":{}},
					{ "id":"4", "type":"o:ApiResponse", "version":"1.0", "config":{}}
		],
		"executions":{ "request":["1","2"], "response":["3","4"] }
	}
}

The following is the sample of the response body for the create API request, you made.

{
    "id": "107",
    "iterationId": "1"
}

You can view the details of the API using the /apiplatform/management/v1/apis/{apiId} endpoint. See Get API details.

The following is the sample of the response body that returns the details of an API.

{
    "updatedBy": "apicsadmin",
    "implementation": {
        "executions": {
            "request": [
                "1",
                "2"
            ],
            "response": [
                "3",
                "4"
            ]
        },
        "policies": [
            {
                "draft": true,
                "id": "1",
                "type": "o:ApiRequest",
                "version": "1.0",
                "config": {}
            },
            {
                "draft": true,
                "id": "2",
                "type": "o:ServiceRequest",
                "version": "1.0",
                "config": {}
            },
            {
                "id": "3",
                "type": "o:ServiceResponse",
                "version": "1.0",
                "config": {}
            },
            {
                "id": "4",
                "type": "o:ApiResponse",
                "version": "1.0",
                "config": {}
            }
        ]
    },
    "version": "v1",
    "createdAt": "2018-02-08T23:36:11-0800",
    "createdBy": "apicsadmin",
    "publication": {
        "visibility": "PROTECTED",
        "state": "UNPUBLISHED"
    },
    "name": "weather",
    "details": {},
    "links": [
        {
            "templated": "true",
            "method": "GET",
            "rel": "self",
            "href": "http://example.com:443/apiplatform/management/v1/apis/107"
        },
        {
            "templated": "true",
            "method": "GET",
            "rel": "canonical",
            "href": "http://example.com:443/apiplatform/management/v1/apis/107"
        },
        {
            "templated": "true",
            "method": "GET",
            "rel": "iteration",
            "href": "http://example.com:443/apiplatform/management/v1/apis/107/iterations/1"
        },
        {
            "templated": "true",
            "method": "GET",
            "rel": "history",
            "href": "http://example.com:443/apiplatform/management/v1/apis/107/history"
        },
        {
            "templated": "true",
            "method": "PUT",
            "rel": "edit",
            "href": "http://example.com:443/apiplatform/management/v1/apis/107"
        },
        {
            "templated": "true",
            "method": "PUT",
            "rel": "rename",
            "href": "http://example.com:443/apiplatform/management/v1/apis/107/identity"
        },
        {
            "templated": "true",
            "method": "DELETE",
            "rel": "delete",
            "href": "http://example.com:443/apiplatform/management/v1/apis/107"
        },
        {
            "templated": "true",
            "method": "POST",
            "rel": "validate",
            "href": "http://example.com:443/apiplatform/management/v1/apis/107/validation"
        },
        {
            "templated": "true",
            "method": "PUT",
            "rel": "lifecycle",
            "href": "http://example.com:443/apiplatform/management/v1/apis/107/state"
        },
        {
            "templated": "true",
            "method": "PUT",
            "rel": "unpublish",
            "href": "http://example.com:443/apiplatform/management/v1/apis/107/publication"
        },
        {
            "templated": "true",
            "method": "GET",
            "rel": "references",
            "href": "http://example.com:443/apiplatform/management/v1/apis/107/references"
        },
        {
            "templated": "true",
            "method": "GET",
            "rel": "references.applications",
            "href": "http://example.com:443/apiplatform/management/v1/apis/107/references/applications"
        },
        {
            "templated": "true",
            "method": "GET",
            "rel": "references.gateways",
            "href": "http://example.com:443/apiplatform/management/v1/apis/107/references/gateways"
        },
        {
            "templated": "true",
            "method": "GET",
            "rel": "references.services",
            "href": "http://example.com:443/apiplatform/management/v1/apis/107/references/services"
        },
        {
            "templated": "true",
            "method": "GET",
            "rel": "references.serviceaccounts",
            "href": "http://example.com:443/apiplatform/management/v1/apis/107/references/serviceaccounts"
        },
        {
            "templated": "true",
            "method": "GET",
            "rel": "entitlements",
            "href": "http://example.com:443/apiplatform/management/v1/apis/107/entitlements"
        },
        {
            "templated": "true",
            "method": "GET",
            "rel": "deployments",
            "href": "http://example.com:443/apiplatform/management/v1/apis/107/deployments"
        },
        {
            "templated": "true",
            "method": "GET",
            "rel": "grants",
            "href": "http://example.com:443/apiplatform/management/v1/apis/107/grants"
        }
    ],
    "state": "ALPHA",
    "id": "107",
    "iterationId": "1",
    "updatedAt": "2018-02-08T23:36:11-0800",
    "artifacts": []
}