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

Get entitlements

get

/apiplatform/management/v1/apis/{apiId}/entitlements

Returns the collection of entitlements for the {apiID} API.

User must have Gateway Manger, Plan Manager or API Manager roles. This call is made in the content of API so the user must have Manage API or View All Details grants on the API.

Request

Supported Media Types

application/json

Path Parameters

apiId: string

A unique ID referencing a specific API.

Query Parameters

expand(optional): array

Collection Format: csv

Pass optional fields, separated by commas, in this parameter to return them in the response. See the operation's description for a list of expand values.

[0]: string

{
    "name":"expand",
    "in":"query",
    "description":"Pass optional fields, separated by commas, in this parameter to return them in the response. See the operation's description for a list of expand values.",
    "required":false,
    "type":"array",
    "items":{
        "type":"string"
    },
    "collectionFormat":"csv"
}

fields(optional): array

Collection Format: csv

Pass optional fields, separated by commas, in this parameter to return them in the response. See the operation's description for a list of field values.

[0]: string

{
    "name":"fields",
    "in":"query",
    "description":"Pass optional fields, separated by commas, in this parameter to return them in the response. See the operation's description for a list of field values.",
    "required":false,
    "type":"array",
    "items":{
        "type":"string"
    },
    "collectionFormat":"csv"
}

limit(optional): integer(int32)

Number of items to retrieve. 1 is the minumum; 128 is the maximum.

Default Value: 128

links(optional): array

Collection Format: csv

Filter the specified link rel's.

[0]: string

{
    "name":"links",
    "in":"query",
    "description":"Filter the specified link rel's.",
    "required":false,
    "type":"array",
    "items":{
        "type":"string"
    },
    "collectionFormat":"csv"
}

offset(optional): integer(int32)

Offset the list returned results by this amount. Default is zero.

Default Value: 0

orderBy(optional): array

Collection Format: csv

Pass sorting criteria, comma separated.

[0]: string

{
    "name":"orderBy",
    "in":"query",
    "description":"Pass sorting criteria, comma separated.",
    "required":false,
    "type":"array",
    "items":{
        "type":"string"
    },
    "collectionFormat":"csv"
}

q(optional): string

Pass filtering criteria, using the SCIM filter expression syntax
totalResults(optional): boolean

Include the total result count in the response.

Default Value: false

Response

Supported Media Types

application/json

200 Response

The collection of entitlements

Root Schema : GetEntitlementsResponse

Match All

Show Source

object CollectionResponseFeature
object CollectionResponsePagingFeature
object LinksResponseFeature
object GetEntitlementsResponse-allOf[3]

{
    "allOf":[
        {
            "$ref":"#/definitions/CollectionResponseFeature"
        },
        {
            "$ref":"#/definitions/CollectionResponsePagingFeature"
        },
        {
            "$ref":"#/definitions/LinksResponseFeature"
        },
        {
            "type":"object",
            "properties":{
                "items":{
                    "type":"array",
                    "items":{
                        "$ref":"#/definitions/GetEntitlementsItem"
                    }
                }
            }
        }
    ]
}

Nested Schema : CollectionResponseFeature

Type: object

Show Source

count(optional): integer(int32)

The number of items in this collection.

{
    "properties":{
        "count":{
            "type":"integer",
            "format":"int32",
            "description":"The number of items in this collection."
        }
    }
}

Nested Schema : CollectionResponsePagingFeature

Type: object

Show Source

totalResults(optional): integer(int32)

The total number of results available. Only provided if the showTotalResults query parameter is set to true

{
    "properties":{
        "totalResults":{
            "type":"integer",
            "format":"int32",
            "description":"The total number of results available. Only provided if the showTotalResults query parameter is set to true"
        }
    }
}

Nested Schema : LinksResponseFeature

Type: object

Show Source

links(optional): array links

Includes 'canonical'.

{
    "properties":{
        "links":{
            "type":"array",
            "description":"Includes 'canonical'.",
            "items":{
                "$ref":"#/definitions/HATEOASLink"
            }
        }
    }
}

Nested Schema : GetEntitlementsResponse-allOf[3]

Type: object

Show Source

items(optional): array items

{
    "type":"object",
    "properties":{
        "items":{
            "type":"array",
            "items":{
                "$ref":"#/definitions/GetEntitlementsItem"
            }
        }
    }
}

Nested Schema : links

Type: array

Includes 'canonical'.

Show Source

Array of: object HATEOASLink

{
    "type":"array",
    "description":"Includes 'canonical'.",
    "items":{
        "$ref":"#/definitions/HATEOASLink"
    }
}

Nested Schema : HATEOASLink

Type: object

Show Source

href(optional): string

Link href.
method(optional): string

HTTP Operation GET, POST, PUT
rel(optional): string

Link relation.

{
    "type":"object",
    "properties":{
        "method":{
            "type":"string",
            "description":"HTTP Operation GET, POST, PUT"
        },
        "rel":{
            "type":"string",
            "description":"Link relation."
        },
        "href":{
            "type":"string",
            "description":"Link href."
        }
    }
}

Nested Schema : items

Type: array

Show Source

Array of: GetEntitlementsItem

{
    "type":"array",
    "items":{
        "$ref":"#/definitions/GetEntitlementsItem"
    }
}

Nested Schema : GetEntitlementsItem

Match All

Show Source

Entitlement
object ResourceLinksProperties

{
    "allOf":[
        {
            "$ref":"#/definitions/Entitlement"
        },
        {
            "$ref":"#/definitions/ResourceLinksProperties"
        }
    ]
}

Nested Schema : Entitlement

Match All

Show Source

object EntitlementId
object EntitlementDef
object Entitlement-allOf[2]
object Entitlement-allOf[3]
object EntitlementState
object Entitlement-allOf[5]
object EntitlementMetadata

{
    "allOf":[
        {
            "$ref":"#/definitions/EntitlementId"
        },
        {
            "$ref":"#/definitions/EntitlementDef"
        },
        {
            "type":"object",
            "properties":{
                "api":{
                    "$ref":"#/definitions/Api"
                }
            }
        },
        {
            "type":"object",
            "properties":{
                "plan":{
                    "$ref":"#/definitions/Plan"
                }
            }
        },
        {
            "$ref":"#/definitions/EntitlementState"
        },
        {
            "type":"object",
            "properties":{
                "publication":{
                    "$ref":"#/definitions/EntitlementPublication"
                }
            }
        },
        {
            "$ref":"#/definitions/EntitlementMetadata"
        }
    ]
}

Nested Schema : ResourceLinksProperties

Type: object

Show Source

links(optional): array links

Includes 'canonical'.

{
    "properties":{
        "links":{
            "type":"array",
            "description":"Includes 'canonical'.",
            "items":{
                "$ref":"#/definitions/HATEOASLink"
            }
        }
    }
}

Nested Schema : EntitlementId

Type: object

Show Source

id: string

The entitlement's ID.

{
    "type":"object",
    "required":[
        "id"
    ],
    "properties":{
        "id":{
            "type":"string",
            "description":"The entitlement's ID."
        }
    }
}

Nested Schema : EntitlementDef

Type: object

Nested Schema : Entitlement-allOf[2]

Type: object

Show Source

api(optional): object Api

{
    "type":"object",
    "properties":{
        "api":{
            "$ref":"#/definitions/Api"
        }
    }
}

Nested Schema : Entitlement-allOf[3]

Type: object

Show Source

plan(optional): object Plan

{
    "type":"object",
    "properties":{
        "plan":{
            "$ref":"#/definitions/Plan"
        }
    }
}

Nested Schema : EntitlementState

Type: object

Show Source

state(optional): string

The entitlement's state.
stateComments(optional): string

Comments regarding the entitlement's state.
stateUpdatedAt(optional): string

The date and time the entitlement's state was last updated.
stateUpdatedBy(optional): string

The user who last updated the entitlement's state.

{
    "type":"object",
    "properties":{
        "state":{
            "type":"string",
            "description":"The entitlement's state."
        },
        "stateComments":{
            "type":"string",
            "description":"Comments regarding the entitlement's state."
        },
        "stateUpdatedBy":{
            "type":"string",
            "description":"The user who last updated the entitlement's state."
        },
        "stateUpdatedAt":{
            "type":"string",
            "description":"The date and time the entitlement's state was last updated."
        }
    }
}

Nested Schema : Entitlement-allOf[5]

Type: object

Show Source

publication(optional): object EntitlementPublication

{
    "type":"object",
    "properties":{
        "publication":{
            "$ref":"#/definitions/EntitlementPublication"
        }
    }
}

Nested Schema : EntitlementMetadata

Type: object

Show Source

createdAt(optional): string

The date and time the entitlement was created.
createdBy(optional): string

The user who created the entitlement.
updatedAt(optional): string

The date and time the entitlement was last updated.
updatedBy(optional): string

The user who last updated the entitlement.

{
    "type":"object",
    "properties":{
        "createdBy":{
            "type":"string",
            "description":"The user who created the entitlement."
        },
        "createdAt":{
            "type":"string",
            "description":"The date and time the entitlement was created."
        },
        "updatedBy":{
            "type":"string",
            "description":"The user who last updated the entitlement."
        },
        "updatedAt":{
            "type":"string",
            "description":"The date and time the entitlement was last updated."
        }
    }
}

Nested Schema : Api

Type: object

Nested Schema : Plan

Type: object

Nested Schema : EntitlementPublication

Type: object

Show Source

state(optional): string

The entitlement's publication state. This value determines if the entitlement is published to the Plan. Valid values are PUBLISHED and UNPUBLISHED.
stateComments(optional): string

Comments about the publication's state.
stateUpdatedAt(optional): string

The date and time the publication state was last updated.
stateUpdatedBy(optional): string

The user who last updated the publication state.

{
    "type":"object",
    "properties":{
        "state":{
            "type":"string",
            "description":"The entitlement's publication state. This value determines if the entitlement is published to the Plan. Valid values are PUBLISHED and UNPUBLISHED."
        },
        "stateComments":{
            "type":"string",
            "description":"Comments about the publication's state."
        },
        "stateUpdatedBy":{
            "type":"string",
            "description":"The user who last updated the publication state."
        },
        "stateUpdatedAt":{
            "type":"string",
            "description":"The date and time the publication state was last updated."
        }
    }
}

Nested Schema : links

Type: array

Includes 'canonical'.

Show Source

Array of: object HATEOASLink

{
    "type":"array",
    "description":"Includes 'canonical'.",
    "items":{
        "$ref":"#/definitions/HATEOASLink"
    }
}

403 Response

Forbidden.

Root Schema : Error

Type: object

Show Source

detail(optional): string

Detailed error message
errorCode(optional): string

Application specific error code
errorDetails(optional): array errorDetails

additional errors
errorPath(optional): string
instance(optional): string

URI to the link that provides more detail about the error
status(optional): string

HTTP status code
title: string

Summary error message
type: string

Error type

{
    "type":"object",
    "required":[
        "title",
        "type"
    ],
    "properties":{
        "type":{
            "type":"string",
            "description":"Error type"
        },
        "title":{
            "type":"string",
            "description":"Summary error message"
        },
        "detail":{
            "type":"string",
            "description":"Detailed error message"
        },
        "instance":{
            "type":"string",
            "description":"URI to the link that provides more detail about the error"
        },
        "errorCode":{
            "type":"string",
            "description":"Application specific error code"
        },
        "errorPath":{
            "type":"string"
        },
        "status":{
            "type":"string",
            "description":"HTTP status code"
        },
        "errorDetails":{
            "type":"array",
            "description":"additional errors",
            "items":{
                "$ref":"#/definitions/Error"
            }
        }
    }
}

Nested Schema : errorDetails

Type: array

additional errors

Show Source

Array of: object Error

{
    "type":"array",
    "description":"additional errors",
    "items":{
        "$ref":"#/definitions/Error"
    }
}

500 Response

Unexpected error.

Root Schema : Error

Type: object

Show Source

detail(optional): string

Detailed error message
errorCode(optional): string

Application specific error code
errorDetails(optional): array errorDetails

additional errors
errorPath(optional): string
instance(optional): string

URI to the link that provides more detail about the error
status(optional): string

HTTP status code
title: string

Summary error message
type: string

Error type

{
    "type":"object",
    "required":[
        "title",
        "type"
    ],
    "properties":{
        "type":{
            "type":"string",
            "description":"Error type"
        },
        "title":{
            "type":"string",
            "description":"Summary error message"
        },
        "detail":{
            "type":"string",
            "description":"Detailed error message"
        },
        "instance":{
            "type":"string",
            "description":"URI to the link that provides more detail about the error"
        },
        "errorCode":{
            "type":"string",
            "description":"Application specific error code"
        },
        "errorPath":{
            "type":"string"
        },
        "status":{
            "type":"string",
            "description":"HTTP status code"
        },
        "errorDetails":{
            "type":"array",
            "description":"additional errors",
            "items":{
                "$ref":"#/definitions/Error"
            }
        }
    }
}

Nested Schema : errorDetails

Type: array

additional errors

Show Source

Array of: object Error

{
    "type":"array",
    "description":"additional errors",
    "items":{
        "$ref":"#/definitions/Error"
    }
}

Examples

The following example shows how to retrieve the collection of entitlements for the {apiID} API by submitting a GET request on the REST resource using cURL. For more information about cURL, see Use cURL.

curl -i -X GET 
-H "Authorization: Bearer access_token"
https://example.com/apiplatform/management/v1/apis/{apiId}/entitlements

{apiId} is the unique ID for an API. To retrieve available API IDs, see Get APIs.

Example of Response Headers

The following shows an example of the response headers.

HTTP/1.1 200 OK
Server: Oracle-Traffic-Director/12.2.1.0.0
Date:  Mon, 12 Feb 2018 12:13:12 GMT
Content-Length:  2811
Content-Type:  application/json
X-oracle-dms-ecid:  a7070a18-e96d-4e69-a511-58eafd07a798-0000cda8
X-oracle-dms-rid:  0
Via: 1.1 otd_opc
Proxy-agent: Oracle-Traffic-Director/12.2.1.0.0

Example of Response Body

The following example shows the contents of the response body in JSON format, including the details of the associated plan and API.

{
    "offset": 0,
    "count": 2,
    "limit": 128,
    "hasMore": false,
    "links": [
        {
            "templated": "true",
            "method": "GET",
            "rel": "self",
            "href": "http://example.com:443/apiplatform/management/v1/apis/100/entitlements?offset=0=128"
        },
        {
            "templated": "true",
            "method": "GET",
            "rel": "canonical",
            "href": "http://example.com:443/apiplatform/management/v1/apis/100/entitlements"
        },
        {
            "templated": "true",
            "method": "POST",
            "rel": "add",
            "href": "http://example.com:443/apiplatform/management/v1/apis/100/entitlements"
        },
        {
            "templated": "true",
            "method": "GET",
            "rel": "plans",
            "href": "http://example.com:443/apiplatform/management/v1/apis/100/entitlements/plans"
        }
    ],
    "items": [
        {
            "createdAt": "2018-02-05T10:27:30-0800",
            "updatedBy": "admin",
            "createdBy": "admin",
            "publication": {
                "state": "PUBLISHED"
            },
            "links": [
                {
                    "templated": "true",
                    "method": "GET",
                    "rel": "self",
                    "href": "http://example.com:443/apiplatform/management/v1/apis/100/entitlements/100"
                },
                {
                    "templated": "true",
                    "method": "GET",
                    "rel": "canonical",
                    "href": "http://example.com:443/apiplatform/management/v1/apis/100/entitlements/100"
                },
                {
                    "templated": "true",
                    "method": "PUT",
                    "rel": "inactivate",
                    "href": "http://example.com:443/apiplatform/management/v1/apis/100/entitlements/100/state"
                },
                {
                    "templated": "true",
                    "method": "PUT",
                    "rel": "unpublish",
                    "href": "http://example.com:443/apiplatform/management/v1/apis/100/entitlements/100/publication"
                },
                {
                    "templated": "true",
                    "method": "PUT",
                    "rel": "edit",
                    "href": "http://example.com:443/apiplatform/management/v1/apis/100/entitlements/100"
                }
            ],
            "state": "ACTIVE",
            "api": {
                "id": "100"
            },
            "id": "100",
            "plan": {
                "id": "100"
            },
            "updatedAt": "2018-02-05T10:27:30-0800"
        },
        {
            "createdAt": "2018-02-05T22:57:31-0800",
            "updatedBy": "admin",
            "createdBy": "admin",
            "publication": {
                "state": "UNPUBLISHED"
            },
            "links": [
                {
                    "templated": "true",
                    "method": "GET",
                    "rel": "self",
                    "href": "http://example.com:443/apiplatform/management/v1/apis/100/entitlements/110"
                },
                {
                    "templated": "true",
                    "method": "GET",
                    "rel": "canonical",
                    "href": "http://example.com:443/apiplatform/management/v1/apis/100/entitlements/110"
                },
                {
                    "templated": "true",
                    "method": "PUT",
                    "rel": "inactivate",
                    "href": "http://example.com:443/apiplatform/management/v1/apis/100/entitlements/110/state"
                },
                {
                    "templated": "true",
                    "method": "PUT",
                    "rel": "publish",
                    "href": "http://example.com:443/apiplatform/management/v1/apis/100/entitlements/110/publication"
                },
                {
                    "templated": "true",
                    "method": "PUT",
                    "rel": "edit",
                    "href": "http://example.com:443/apiplatform/management/v1/apis/100/entitlements/110"
                },
                {
                    "templated": "true",
                    "method": "DELETE",
                    "rel": "remove",
                    "href": "http://example.com:443/apiplatform/management/v1/apis/100/entitlements/110"
                }
            ],
            "state": "ACTIVE",
            "api": {
                "id": "100"
            },
            "id": "110",
            "plan": {
                "id": "107"
            },
            "updatedAt": "2018-02-05T22:57:31-0800"
        }
    ]
}