APIVersion Object
Includes information about an API version.
This object is used by the following operations:
- POST /api/apis/{APIID}/versions (in the response)
- GET /api/apis/versions/{APIVersionID} (in the response)
- Operations that reference the API object
- Operations that reference the ContractAPI object
- Operations that reference the APIVersions object
- Operations that reference the ReferencedObjects object
The properties included in the APIVersion object are listed below. Specific properties are optional unless otherwise stated.
| Property | Type | Description |
|---|---|---|
| APIVersionID | string | The unique ID for a specific API version. Required except when adding a new API version. |
| APIID | string |
The unique ID for a specific API. Required. |
| Name | string | The name of the API version. |
| Description | string | The description of the API version. |
| Environment | string | The environment the API is valid for. |
| Type | string | The type for the API version. Deprecated. For values, see API Types. |
| DefaultProfile | string | The default profile for the API version. This determines default media type values for request and response messages. In the user interface, the default profile is automatically used for new operations, although it can be changed. |
| DefaultInputContentType | string | Default content-type for request messages. |
| DefaultOutputContentType | string | Default content-type for response messages. |
| DefaultFaultContentType | string | The default content type (MIME type) for fault response messages for this operation. |
| Tag | string[ ] | One or more user-defined tags assigned to the discussion. |
| ProductionEndpoint | anyURI | The Production endpoint listed for the API version in the API Details page in the user interface. This is typically the same as the URI for the Live endpoint defined within the Endpoints object. |
| ProductionEndpointOAuthDetails | EndpointOAuthDetails |
The OAuth configuration details for the Production endpoint, such as OAuth version and URLs. Used only in response messages. |
| SandboxEndpoint | anyURI | The Sandbox endpoint listed for the API version in the API Details page in the user interface. This is typically the same as the URI for the Sandbox endpoint defined within the Endpoints object. |
| SandboxEndpointOAuthDetails | EndpointOAuthDetails |
The OAuth configuration details for the Sandbox endpoint, such as OAuth version and URLs. Used only in response messages. |
| Descriptor | Descriptor | For SOAP APIs only. Includes information about the WSDL that contains the technical details about the API version. For SOAP APIs, this is required in the request message when adding or updating an API version. Not used in response messages. |
| Operations | Operations | Used for REST APIs only: Information about the operations that are valid for the API version. |
| Endpoints | Endpoints | Information about the endpoints that are valid for the API version. |
|
Policies (Versions up to 2020.2.0) |
Policies |
Contains information about the policies assigned to an API, at the API level or at the operation level. Note: In version 2020.2.0 and later, policies are not returned as a top-level property in the APIVersion object. Policy information is returned as part of APIImplementations > APIImplementation which are part of the APIVersion model object. |
| TargetAPI | TargetAPI | Includes information about the target API—the destination endpoint, or next hop, defined when an API is using the platform as a proxy. |
| Visibility | string | The visibility setting for the API; either Public, which is visible to all users, or Limited, which is visible only to API Administrators and API Scope Group members. |
| Created | dateTime | The date/time stamp when the resource was first created. Used only in response messages. |
| Updated | dateTime | The date/time stamp when the resource was last updated. Used only in response messages. |
| State | string | For request messages, if a state is specified, only API versions in that state are returned. |
| ProductionEndpointAccessAutoApproved | boolean | Indicates whether a request for production access for the API is automatically approved. Defaults to false; unless set to true, production access must be approved by an API Administrator. |
| SandboxEndpointAccessAutoApproved | boolean | Indicates whether a request for sandbox access for the API is automatically approved. Defaults to true; unless set to false, sandbox access is automatic and immediate upon request. |
| RatingSummary | RatingSummary | An aggregated, averaged summary of individual user ratings for the resource, including the current ratings count for each possible value (1, 2, 3, 4, or 5). Used only in response messages. |
| ProductionEndpointExists | boolean | Indicates whether a Production endpoint exists for this API. For internal use only. |
| SandboxEndpointExists | boolean | Indicates whether a Sandbox endpoint exists for this API. For internal use only. |
| SandboxAnonymousAccessAllowed | boolean | Indicates whether users who are not logged in can use the Sandbox endpoint for this API version. Defaults to false. |
| ProductionAnonymousAccessAllowed | boolean | Indicates whether users who are not logged in can use the Production endpoint for this API version. Defaults to false. |
| APIVersionSettings | APIVersionSettings | Includes information about the settings for an API version; for example, whether access is auto approved and whether ratings and reviews are supported. If not specified for the API version, settings are inherited from the API, business, or tenant. |
| APIVersionResourceDetails | APIVersionResourceDetails | Contains details about operation-specific scope mapping for an API version, if operation-specific scope mapping is in use for the API version. |
| ResourceLevelPermissionsSupported | boolean | Indicates whether resource-level permissions are supported for the API. Default: false. If resource-level permissions are supported, set to true. |
| APIOwnedImplementations | boolean |
If the API was created on the platform (API with New Service option, the default) this value is true. If the API was created using the API With Existing Service option, the service implementation is owned by Policy Manager; in this case, the value is false. Default: true. |
| ProductionServiceKey | string | The unique UDDI key used for the API binding in Policy Manager, for the production endpoint for this API version. When adding an API from existing service, use the valid service key for the service in Policy Manager. For existing API versions, this field is included in response messages. |
| SandboxServiceKey | string | The service key for the sandbox endpoint for this API version. |
| APIImplementations | APIImplementations | Contains information about one or more API implementations. |
| TargetResources | TargetResources | Contains information about one or more resources associated with the current resource. Used only in response messages. |
| APIDesign | APIDesign | Contains information about the design for a specific API. |
| APIVersionOAuthResourceMapping | APIVersionOAuthResourceMapping | Contains information about one or more resources (grants) applicable to an API-wide resource. |
| BindingType | string[ ] | The API binding type; for example, binding.http. For valid values, see API Binding Types. |
| classifiers | classifiers |
Applicable with Lifecycle Repository integration only. Contains a property name and an array of one or more values for the property. For an example, see POST /api/users/completeSignup. The user interface shows custom properties as a single concept, but on the API, app, or user they exist as classifiers and artifacts. The artifacts have URLs ("by-ref" artifacts). Classifiers and artifacts are only applicable if the Repository Extension is enabled and custom properties configured. |
| artifacts | artifacts |
Applicable with Lifecycle Repository integration only. Contains entries with an artifact name and value. The value is always a URL. For an example, see POST /api/users/completeSignup. The user interface shows custom properties as a single concept, but on the API, app, or user they exist as classifiers and artifacts. The artifacts have URLs ("by-ref" artifacts). Classifiers and artifacts are only applicable if the Repository Extension is enabled and custom properties configured. |