Jump to

• Request
• Response
• Examples

Get details for an API's published iteration

get

/developers/services/v1/apis/{vanityName}

Returns details about the iteration of the {vanityName} API published to the Developer Portal.

All authenticated users can request this resource. Only details for APIs that are published to the Developer Portal and the requesting user is issued the Manage API, View Public Details, Register, or Request Register API grant for are returned.

Request

Path Parameters

• vanityName: string
  An API's unique vanity name. This is the URI path of the details page for the API on the Developer Portal (like https://example.com/developers/apis/weatherService.

Back to Top

Response

Supported Media Types

• application/json

200 Response

JSON structure with details of the API.

Body ()

API resource representation.

Root Schema : PortalApi

Type: object

API resource representation.

Show Source

• allVersions(optional): array allVersions
  List of the API's available versions.
• createdAt(optional): string
  The date and time the API was created.
• createdBy(optional): string
  The name of the user who created the API.
• description(optional): string
  The API's description.
• details(optional): object ApiDetailArtifact
  API detail artifact representation
• icon(optional): string
  Artifact containing the API's icon, if changed.
• id: integer(int32)
  The API's ID.
• iterationId(optional): integer(int32)
  The API's iteration ID.
• links(optional): array links
  HATEOAS links for the API.
• name: string
  The API's name.
• plans(optional): array plans
  The API's deployment plans.
• state(optional): string
  Allowed Values: [ "ALPHA", "BETA", "RETIRED", "RELEASED", "DEPRECATED" ]

  The API's state. Valid values: ALPHA, BETA, RELEASED, DEPRECATED, and RETIRED.
• vanityName: string
  The API's vanity name.
• version: string
  The API's version.
• visibility(optional): string
  Allowed Values: [ "PROTECTED", "INTERNAL", "PUBLIC" ]

  {dto.Api.visibility}

{
    "type":"object",
    "required":[
        "id",
        "name",
        "vanityName",
        "version"
    ],
    "properties":{
        "vanityName":{
            "type":"string",
            "description":"The API's vanity name."
        },
        "visibility":{
            "type":"string",
            "description":"{dto.Api.visibility}",
            "enum":[
                "PROTECTED",
                "INTERNAL",
                "PUBLIC"
            ]
        },
        "icon":{
            "type":"string",
            "description":"Artifact containing the API's icon, if changed."
        },
        "description":{
            "type":"string",
            "description":"The API's description."
        },
        "version":{
            "type":"string",
            "description":"The API's version."
        },
        "createdAt":{
            "type":"string",
            "description":"The date and time the API was created."
        },
        "createdBy":{
            "type":"string",
            "description":"The name of the user who created the API."
        },
        "plans":{
            "type":"array",
            "description":"The API's deployment plans.",
            "items":{
                "$ref":"#/definitions/PlanForApi"
            }
        },
        "allVersions":{
            "type":"array",
            "description":"List of the API's available versions.",
            "items":{
                "$ref":"#/definitions/ApiVersion"
            }
        },
        "name":{
            "type":"string",
            "description":"The API's name."
        },
        "details":{
            "description":"Artifact containing the API's details.",
            "$ref":"#/definitions/ApiDetailArtifact"
        },
        "links":{
            "type":"array",
            "description":"HATEOAS links for the API.",
            "items":{
                "$ref":"#/definitions/GenericLink"
            }
        },
        "id":{
            "type":"integer",
            "format":"int32",
            "description":"The API's ID."
        },
        "state":{
            "type":"string",
            "description":"The API's state. Valid values: <code>ALPHA</code>, <code>BETA</code>, <code>RELEASED</code>, <code>DEPRECATED</code>, and <code>RETIRED</code>.",
            "enum":[
                "ALPHA",
                "BETA",
                "RETIRED",
                "RELEASED",
                "DEPRECATED"
            ]
        },
        "iterationId":{
            "type":"integer",
            "format":"int32",
            "description":"The API's iteration ID."
        }
    },
    "description":"API resource representation."
}

Nested Schema : allVersions

Type: array

List of the API's available versions.

Show Source

• Array of: object ApiVersion
  API version resource representation.

{
    "type":"array",
    "description":"List of the API's available versions.",
    "items":{
        "$ref":"#/definitions/ApiVersion"
    }
}

Nested Schema : ApiDetailArtifact

Type: object

API detail artifact representation

Show Source

• documentation(optional): object ApiDetailsItem
  API detail representation for overview and documentation subtypes.
• overview(optional): object ApiDetailsItem
  API detail representation for overview and documentation subtypes.

{
    "type":"object",
    "properties":{
        "overview":{
            "description":"Markdown overview text.",
            "$ref":"#/definitions/ApiDetailsItem"
        },
        "documentation":{
            "description":"The documentation URL.",
            "$ref":"#/definitions/ApiDetailsItem"
        }
    },
    "description":"API detail artifact representation"
}

Nested Schema : links

Type: array

HATEOAS links for the API.

Show Source

• Array of: object GenericLink
  HATEOAS generic link representation.

{
    "type":"array",
    "description":"HATEOAS links for the API.",
    "items":{
        "$ref":"#/definitions/GenericLink"
    }
}

Nested Schema : plans

Type: array

The API's deployment plans.

Show Source

• Array of: object PlanForApi
  Plan for a given API resource representation.

{
    "type":"array",
    "description":"The API's deployment plans.",
    "items":{
        "$ref":"#/definitions/PlanForApi"
    }
}

Nested Schema : ApiVersion

Type: object

API version resource representation.

Show Source

• vanityName: string
  The API's vanity name.
• version: string
  The API's version.

{
    "type":"object",
    "required":[
        "vanityName",
        "version"
    ],
    "properties":{
        "vanityName":{
            "type":"string",
            "description":"The API's vanity name."
        },
        "version":{
            "type":"string",
            "description":"The API's version."
        }
    },
    "description":"API version resource representation."
}

Nested Schema : ApiDetailsItem

Type: object

API detail representation for overview and documentation subtypes.

Show Source

• data(optional): string
  The documentation data as a string.
• dataType(optional): string
  The documentation data type.
• docType(optional): string
  The documentation type.

{
    "type":"object",
    "properties":{
        "data":{
            "type":"string",
            "description":"The documentation data as a string."
        },
        "docType":{
            "type":"string",
            "description":"The documentation type."
        },
        "dataType":{
            "type":"string",
            "description":"The documentation data type."
        }
    },
    "description":"API detail representation for overview and documentation subtypes."
}

Nested Schema : GenericLink

Type: object

HATEOAS generic link representation.

Show Source

• href: string
  Link reference string.
• method(optional): string
  HTTP method used with the link.
• rel: string
  Link relation string Value is either canonical or a specific string value.
• templated(optional): string
  Allowed Values: [ "true", "false" ]

  Indicates if the link has templated parts.

{
    "type":"object",
    "required":[
        "href",
        "rel"
    ],
    "properties":{
        "templated":{
            "type":"string",
            "description":"Indicates if the link has templated parts.",
            "enum":[
                "true",
                "false"
            ]
        },
        "method":{
            "type":"string",
            "description":"HTTP method used with the link."
        },
        "rel":{
            "type":"string",
            "description":"Link relation string Value is either <code>canonical</code> or a specific string value."
        },
        "href":{
            "type":"string",
            "description":"Link reference string."
        }
    },
    "description":"HATEOAS generic link representation."
}

Nested Schema : PlanForApi

Type: object

Plan for a given API resource representation.

Show Source

• constraints(optional): object Constraints
  Plan subscription constraints.
• description(optional): string
  The plan's description.
• icon(optional): string
  The plan's icon.
• id: integer(int32)
  The plan's ID.
• links(optional): array links
  HATEOAS links.
• name: string
  The plan's name.
• publicationSettings(optional): object PublicationSettings
  Publication settings for the given plan.
• subscriptions(optional): array subscriptions
  List of applications registered to the API.
• vanityName: string
  {dto.PlanForApi.vanityName}

{
    "type":"object",
    "required":[
        "id",
        "name",
        "vanityName"
    ],
    "properties":{
        "vanityName":{
            "type":"string",
            "description":"{dto.PlanForApi.vanityName}"
        },
        "subscriptions":{
            "type":"array",
            "description":"List of applications registered to the API.",
            "items":{
                "$ref":"#/definitions/Subscription"
            }
        },
        "publicationSettings":{
            "description":"The plan publication settings (information display related flags)",
            "$ref":"#/definitions/PublicationSettings"
        },
        "name":{
            "type":"string",
            "description":"The plan's name."
        },
        "icon":{
            "type":"string",
            "description":"The plan's icon."
        },
        "description":{
            "type":"string",
            "description":"The plan's description."
        },
        "links":{
            "type":"array",
            "description":"HATEOAS links.",
            "items":{
                "$ref":"#/definitions/GenericLink"
            }
        },
        "id":{
            "type":"integer",
            "format":"int32",
            "description":"The plan's ID."
        },
        "constraints":{
            "description":"The plan subscription constraints, such as rate, limit, etc.",
            "$ref":"#/definitions/Constraints"
        }
    },
    "description":"Plan for a given API resource representation."
}

Nested Schema : Constraints

Type: object

Plan subscription constraints.

Show Source

• rate(optional): object Rate
  Rate for plan subscription constraints.

{
    "type":"object",
    "properties":{
        "rate":{
            "description":"Subscription rate (for invocations).",
            "$ref":"#/definitions/Rate"
        }
    },
    "description":"Plan subscription constraints."
}

Nested Schema : links

Type: array

HATEOAS links.

Show Source

• Array of: object GenericLink
  HATEOAS generic link representation.

{
    "type":"array",
    "description":"HATEOAS links.",
    "items":{
        "$ref":"#/definitions/GenericLink"
    }
}

Nested Schema : PublicationSettings

Type: object

Publication settings for the given plan.

Show Source

• constraints(optional): object ConstraintSettings
  Plan publication setting's constraint display options.
• description(optional): object DescriptionSettings
  Plan publication setting's description display options.
• icon(optional): object IconSettings
  Plan publication setting's plan icon options.
• recommended(optional): boolean
  Default Value: false

  Flag whether the plan should be listed as recommended.

{
    "type":"object",
    "properties":{
        "icon":{
            "description":"Plan icon display setting.",
            "$ref":"#/definitions/IconSettings"
        },
        "description":{
            "description":"Plan description setting.",
            "$ref":"#/definitions/DescriptionSettings"
        },
        "constraints":{
            "description":"Constraint related display settings.",
            "$ref":"#/definitions/ConstraintSettings"
        },
        "recommended":{
            "type":"boolean",
            "description":"Flag whether the plan should be listed as recommended.",
            "default":false
        }
    },
    "description":"Publication settings for the given plan."
}

Nested Schema : subscriptions

Type: array

List of applications registered to the API.

Show Source

• Array of: Subscription

{
    "type":"array",
    "description":"List of applications registered to the API.",
    "items":{
        "$ref":"#/definitions/Subscription"
    }
}

Nested Schema : Rate

Type: object

Rate for plan subscription constraints.

Show Source

• invocations(optional): array invocations
  Invocation constraint parameters list.

{
    "type":"object",
    "properties":{
        "invocations":{
            "type":"array",
            "description":"Invocation constraint parameters list.",
            "items":{
                "$ref":"#/definitions/Invocation"
            }
        }
    },
    "description":"Rate for plan subscription constraints."
}

Nested Schema : invocations

Type: array

Invocation constraint parameters list.

Show Source

• Array of: object Invocation
  Plan constraint - invocation parameters.

{
    "type":"array",
    "description":"Invocation constraint parameters list.",
    "items":{
        "$ref":"#/definitions/Invocation"
    }
}

Nested Schema : Invocation

Type: object

Plan constraint - invocation parameters.

Show Source

• limit: string
  Maximum number of invocations for the given period.
• period: string
  Time period, such as minutes, days, months, etc.

{
    "type":"object",
    "required":[
        "limit",
        "period"
    ],
    "properties":{
        "period":{
            "type":"string",
            "description":"Time period, such as minutes, days, months, etc."
        },
        "limit":{
            "type":"string",
            "description":"Maximum number of invocations for the given period."
        }
    },
    "description":"Plan constraint - invocation parameters."
}

Nested Schema : ConstraintSettings

Type: object

Plan publication setting's constraint display options.

Show Source

• rate(optional): object RateSettings
  Plan publication setting's invocation rate display options flag.

{
    "type":"object",
    "properties":{
        "rate":{
            "description":"Subscription rate display settings.",
            "$ref":"#/definitions/RateSettings"
        }
    },
    "description":"Plan publication setting's constraint display options."
}

Nested Schema : DescriptionSettings

Type: object

Plan publication setting's description display options.

Show Source

• displayed(optional): boolean
  Default Value: false

  Display flag (boolean).

{
    "type":"object",
    "properties":{
        "displayed":{
            "type":"boolean",
            "description":"Display flag (boolean).",
            "default":false
        }
    },
    "description":"Plan publication setting's description display options."
}

Nested Schema : IconSettings

Type: object

Plan publication setting's plan icon options.

Show Source

• displayed(optional): boolean
  Default Value: false

  Display flag (boolean).

{
    "type":"object",
    "properties":{
        "displayed":{
            "type":"boolean",
            "description":"Display flag (boolean).",
            "default":false
        }
    },
    "description":"Plan publication setting's plan icon options."
}

Nested Schema : RateSettings

Type: object

Plan publication setting's invocation rate display options flag.

Show Source

• invocations(optional): object InvocationSettings
  Plan invocation's display options.

{
    "type":"object",
    "properties":{
        "invocations":{
            "description":"Invocation display options.",
            "$ref":"#/definitions/InvocationSettings"
        }
    },
    "description":"Plan publication setting's invocation rate display options flag."
}

Nested Schema : InvocationSettings

Type: object

Plan invocation's display options.

Show Source

• displayed(optional): boolean
  Default Value: false

  Display flag (boolean).
• displayText(optional): string
  Text to display.

{
    "type":"object",
    "properties":{
        "displayed":{
            "type":"boolean",
            "description":"Display flag (boolean).",
            "default":false
        },
        "displayText":{
            "type":"string",
            "description":"Text to display."
        }
    },
    "description":"Plan invocation's display options."
}

Nested Schema : Subscription

Match All

Show Source

• object SubscriptionId
• object Subscription-allOf[1]
• object Subscription-allOf[2]
• object SubscriptionState
• object SubscriptionMetadata

{
    "allOf":[
        {
            "$ref":"#/definitions/SubscriptionId"
        },
        {
            "type":"object",
            "properties":{
                "application":{
                    "$ref":"#/definitions/Application"
                }
            }
        },
        {
            "type":"object",
            "properties":{
                "plan":{
                    "$ref":"#/definitions/Plan"
                }
            }
        },
        {
            "$ref":"#/definitions/SubscriptionState"
        },
        {
            "$ref":"#/definitions/SubscriptionMetadata"
        }
    ]
}

Nested Schema : SubscriptionId

Type: object

Show Source

• id: string
  The subscription's ID.

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

Nested Schema : Subscription-allOf[1]

Type: object

Show Source

• application(optional): object Application

{
    "type":"object",
    "properties":{
        "application":{
            "$ref":"#/definitions/Application"
        }
    }
}

Nested Schema : Subscription-allOf[2]

Type: object

Show Source

• plan(optional): object Plan

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

Nested Schema : SubscriptionState

Type: object

Show Source

• state(optional): string
  The subscription's state.
• stateComments(optional): string
  Comments regarding the subscription's state.
• stateUpdatedAt(optional): string
  The date and time the subscription's state was last updated.
• stateUpdatedBy(optional): string
  The user who last updated the subscription's state.

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

Nested Schema : SubscriptionMetadata

Type: object

Show Source

• createdAt(optional): string
  The date and time the subscription was created.
• createdBy(optional): string
  The user who created the subscription.
• updatedAt(optional): string
  The date and time the subscription was last updated.
• updatedBy(optional): string
  The user who last updated the subscription.

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

Nested Schema : Application

Type: object

Nested Schema : Plan

Type: object

400 Response

Bad request: indicates a problem with the input parameters.

401 Response

Authentication required.

404 Response

API not found.

500 Response

Server error.

Back to Top

Examples

The following example shows how to retrieve details about the iteration of the {vanityName} API published to the Developer Portal by submitting a GET request on the REST resource using cURL. For more information about cURL, see Use cURL.

curl -i -X GET 
-u apicsadmin:password
https://example.com:443/developers/services/v1/apis/{vanityName}

{vanityName} is an API's unique vanity name. This is the URI path of the details page for the API on the Developer Portal (like https://example.com/developers/apis/weatherService, 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
Date: Wed, 20 Dec 2017 05:19:46 GMT
Content-type: application/json
X-oracle-dms-ecid: 6^3rv0_eR00000000
X-oracle-dms-rid: 0:1

Example of Response Body

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

{
    "vanityName": "creditcheck",
    "visibility": "PROTECTED",
    "version": "18.1.1",
    "createdAt": "2017-12-19T20:32:07-0800",
    "createdBy": "apicsadmin",
    "plans": [
        {
            "registeredApps": [
                {
                    "name": "Portal",
                    "id": 101,
                    "state": "REGISTERED"
                },
                {
                    "name": "Mobile",
                    "id": 100,
                    "state": "REGISTERED"
                }
            ],
            "name": "Mobile Device 18.1.1",
            "description": "default",
            "links": [
                {
                    "method": "POST",
                    "templated": "true",
                    "rel": "register",
                    "href": "http://example.com:443/developers/services/v1/plans/102/subscriptions"
                }
            ],
            "id": 102
        }
    ],
    "allVersions": [
        {
            "vanityName": "creditcheck",
            "version": "18.1.1"
        }
    ],
    "name": "Mobile Device",
    "details": {
        "overview": {
            "data": "Mobile",
            "docType": "html",
            "dataType": "text"
        }
    },
    "links": [
        {
            "method": "GET",
            "templated": "true",
            "rel": "canonical",
            "href": "http://example.com:443/developers/services/v1/apis/creditcheck"
        }
    ],
    "id": 102,
    "state": "ALPHA",
    "iterationId": 3
}

Back to Top