Azure API Management template data model reference
This topic describes the entity and type representations for common items used in the data models for the developer portal templates in Azure API Management.
For more information about working with templates, see How to customize the API Management developer portal using templates.
Note
The following documentation content is about the deprecated developer portal. You can continue to use it, as per usual, until its retirement in October 2023, when it will be removed from all API Management services. The deprecated portal will only receive critical security updates. Refer to the following articles for more details:
Availability
Important
This feature is available in the Premium, Standard, Basic, and Developer tiers of API Management.
For feature availability in the v2 tiers (preview), see the v2 tiers overview.
Reference
- API
- API summary
- Application
- Attachment
- Code sample
- Comment
- Filtering
- Header
- HTTP Request
- HTTP Response
- Issue
- Operation
- Operation menu
- Operation menu item
- Paging
- Parameter
- Product
- Provider
- Representation
- Subscription
- Subscription summary
- User account info
- User sign-in
- User sign-up
API
The API entity has the following properties:
| Property | Type | Description |
|---|---|---|
id |
string | Resource identifier. Uniquely identifies the API within the current API Management service instance. The value is a valid relative URL in the format of apis/{id} where {id} is an API identifier. This property is read-only. |
name |
string | Name of the API. Must not be empty. Maximum length is 100 characters. |
description |
string | Description of the API. Must not be empty. May include HTML formatting tags. Maximum length is 1000 characters. |
serviceUrl |
string | Absolute URL of the backend service implementing this API. |
path |
string | Relative URL uniquely identifying this API and all of its resource paths within the API Management service instance. It is appended to the API endpoint base URL specified during the service instance creation to form a public URL for this API. |
protocols |
array of number | Describes on which protocols the operations in this API can be invoked. Allowed values are 1 - http and 2 - https, or both. |
authenticationSettings |
Authorization server authentication settings | Collection of authentication settings included in this API. |
subscriptionKeyParameterNames |
object | Optional property that can be used to specify custom names for query and/or header parameters containing the subscription key. When this property is present, it must contain at least one of the two following properties.{ "subscriptionKeyParameterNames": { "query": “customQueryParameterName", "header": “customHeaderParameterName" } } |
API summary
The API summary entity has the following properties:
| Property | Type | Description |
|---|---|---|
id |
string | Resource identifier. Uniquely identifies the API within the current API Management service instance. The value is a valid relative URL in the format of apis/{id} where {id} is an API identifier. This property is read-only. |
name |
string | Name of the API. Must not be empty. Maximum length is 100 characters. |
description |
string | Description of the API. Must not be empty. May include HTML formatting tags. Maximum length is 1000 characters. |
Application
The application entity has the following properties:
| Property | Type | Description |
|---|---|---|
Id |
string | The unique identifier of the application. |
Title |
string | The title of the application. |
Description |
string | The description of the application. |
Url |
URI | The URI for the application. |
Version |
string | Version information for the application. |
Requirements |
string | A description of requirements for the application. |
State |
number | The current state of the application. - 0 - Registered - 1 - Submitted - 2 - Published - 3 - Rejected - 4 - Unpublished |
RegistrationDate |
DateTime | The date and time the application was registered. |
CategoryId |
number | The category of the application (Finance, entertainment, etc.) |
DeveloperId |
string | The unique identifier of the developer that submitted the application. |
Attachments |
Collection of Attachment entities. | Any attachments for the application such as screenshots or icons. |
Icon |
Attachment | The icon the for the application. |
Attachment
The attachment entity has the following properties:
| Property | Type | Description |
|---|---|---|
UniqueId |
string | The unique identifier for the attachment. |
Url |
string | The URL of the resource. |
Type |
string | The type of attachment. |
ContentType |
string | The media type of the attachment. |
Code sample
| Property | Type | Description |
|---|---|---|
title |
string | The name of the operation. |
snippet |
string | This property is deprecated and should not be used. |
brush |
string | Which code syntax coloring template to be used when displaying the code sample. Allowed values are plain, php, java, xml, objc, python, ruby, and csharp. |
template |
string | The name of this code sample template. |
body |
string | A placeholder for the code sample portion of the snippet. |
method |
string | The HTTP method of the operation. |
scheme |
string | The protocol to use for the operation request. |
path |
string | The path of the operation. |
query |
string | Query string example with defined parameters. |
host |
string | The URL of the API Management service gateway for the API that contains this operation. |
headers |
Collection of Header entities. | Headers for this operation. |
parameters |
Collection of Parameter entities. | Parameters that are defined for this operation. |
Comment
The API entity has the following properties:
| Property | Type | Description |
|---|---|---|
Id |
number | The ID of the comment. |
CommentText |
string | The body of the comment. May include HTML. |
DeveloperCompany |
string | The company name of the developer. |
PostedOn |
DateTime | The date and time the comment was posted. |
Issue
The issue entity has the following properties.
| Property | Type | Description |
|---|---|---|
Id |
string | The unique identifier for the issue. |
ApiID |
string | The ID for the API for which this issue was reported. |
Title |
string | Title of the issue. |
Description |
string | Description of the issue. |
SubscriptionDeveloperName |
string | First name of the developer that reported the issue. |
IssueState |
string | The current state of the issue. Possible values are Proposed, Opened, Closed. |
ReportedOn |
DateTime | The date and time the issue was reported. |
Comments |
Collection of Comment entities. | Comments on this issue. |
Attachments |
Collection of Attachment entities. | Any attachments to the issue. |
Services |
Collection of API entities. | The APIs subscribed to by the user that filed the issue. |
Filtering
The filtering entity has the following properties:
| Property | Type | Description |
|---|---|---|
Pattern |
string | The current search term; or null if there is no search term. |
Placeholder |
string | The text to display in the search box when there is no search term specified. |
Header
This section describes the parameter representation.
| Property | Type | Description |
|---|---|---|
name |
string | Parameter name. |
description |
string | Parameter description. |
value |
string | Header value. |
typeName |
string | Data type of header value. |
options |
string | Options. |
required |
boolean | Whether the header is required. |
readOnly |
boolean | Whether the header is read-only. |
HTTP Request
This section describes the request representation.
| Property | Type | Description |
|---|---|---|
description |
string | Operation request description. |
headers |
array of Header entities. | Request headers. |
parameters |
array of Parameter | Collection of operation request parameters. |
representations |
array of Representation | Collection of operation request representations. |
HTTP Response
This section describes the response representation.
| Property | Type | Description |
|---|---|---|
statusCode |
positive integer | Operation response status code. |
description |
string | Operation response description. |
representations |
array of Representation | Collection of operation response representations. |
Operation
The operation entity has the following properties:
| Property | Type | Description |
|---|---|---|
id |
string | Resource identifier. Uniquely identifies the operation within the current API Management service instance. The value is a valid relative URL in the format of apis/{aid}/operations/{id} where {aid} is an API identifier and {id} is an operation identifier. This property is read-only. |
name |
string | Name of the operation. Must not be empty. Maximum length is 100 characters. |
description |
string | Description of the operation. Must not be empty. May include HTML formatting tags. Maximum length is 1000 characters. |
scheme |
string | Describes on which protocols the operations in this API can be invoked. Allowed values are http, https, or both http and https. |
uriTemplate |
string | Relative URL template identifying the target resource for this operation. May include parameters. Example: customers/{cid}/orders/{oid}/?date={date} |
host |
string | The API Management gateway URL that hosts the API. |
httpMethod |
string | Operation HTTP method. |
request |
HTTP Request | An entity containing request details. |
responses |
array of HTTP Response | Array of operation HTTP Response entities. |
Operation menu
The operation menu entity has the following properties:
| Property | Type | Description |
|---|---|---|
ApiId |
string | The ID of the current API. |
CurrentOperationId |
string | The ID of the current operation. |
Action |
string | The menu type. |
MenuItems |
Collection of Operation menu item entities. | The operations for the current API. |
Operation menu item
The operation menu item entity has the following properties:
| Property | Type | Description |
|---|---|---|
Id |
string | The ID of the operation. |
Title |
string | The description of the operation. |
HttpMethod |
string | The Http method of the operation. |
Paging
The paging entity has the following properties:
| Property | Type | Description |
|---|---|---|
Page |
number | The current page number. |
PageSize |
number | The maximum results to be displayed on a single page. |
TotalItemCount |
number | The number of items for display. |
ShowAll |
boolean | Whether to sho all results on a single page. |
PageCount |
number | The number of pages of results. |
Parameter
This section describes the parameter representation.
| Property | Type | Description |
|---|---|---|
name |
string | Parameter name. |
description |
string | Parameter description. |
value |
string | Parameter value. |
options |
array of string | Values defined for query parameter values. |
required |
boolean | Specifies whether parameter is required or not. |
kind |
number | Whether this parameter is a path parameter (1), or a querystring parameter (2). |
typeName |
string | Parameter type. |
Product
The product entity has the following properties:
| Property | Type | Description |
|---|---|---|
Id |
string | Resource identifier. Uniquely identifies the product within the current API Management service instance. The value is a valid relative URL in the format of products/{pid} where {pid} is a product identifier. This property is read-only. |
Title |
string | Name of the product. Must not be empty. Maximum length is 100 characters. |
Description |
string | Description of the product. Must not be empty. May include HTML formatting tags. Maximum length is 1000 characters. |
Terms |
string | Product terms of use. Developers trying to subscribe to the product will be presented and required to accept these terms before they can complete the subscription process. |
ProductState |
number | Specifies whether the product is published or not. Published products are discoverable by developers on the developer portal. Non-published products are visible only to administrators. The allowable values for product state are: - 0 - Not Published- 1 - Published- 2 - Deleted |
AllowMultipleSubscriptions |
boolean | Specifies whether a user can have multiple subscriptions to this product at the same time. |
MultipleSubscriptionsCount |
number | Maximum number of subscriptions to this product a user is allowed to have at the same time. |
Provider
The provider entity has the following properties:
| Property | Type | Description |
|---|---|---|
Properties |
string dictionary | Properties for this authentication provider. |
AuthenticationType |
string | The provider type. (Microsoft Entra ID, Facebook login, Google Account, Microsoft Account, Twitter). |
Caption |
string | Display name of the provider. |
Representation
This section describes a representation.
| Property | Type | Description |
|---|---|---|
contentType |
string | Specifies a registered or custom content type for this representation, for example, application/xml. |
sample |
string | An example of the representation. |
Subscription
The subscription entity has the following properties:
| Property | Type | Description |
|---|---|---|
Id |
string | Resource identifier. Uniquely identifies the subscription within the current API Management service instance. The value is a valid relative URL in the format of subscriptions/{sid} where {sid} is a subscription identifier. This property is read-only. |
ProductId |
string | The product resource identifier of the subscribed product. The value is a valid relative URL in the format of products/{pid} where {pid} is a product identifier. |
ProductTitle |
string | Name of the product. Must not be empty. Maximum length is 100 characters. |
ProductDescription |
string | Description of the product. Must not be empty. May include HTML formatting tags. Maximum length is 1000 characters. |
ProductDetailsUrl |
string | Relative URL to the product details. |
state |
string | The state of the subscription. Possible states are: - 0 - suspended – the subscription is blocked, and the subscriber cannot call any APIs of the product.- 1 - active – the subscription is active.- 2 - expired – the subscription reached its expiration date and was deactivated.- 3 - submitted – the subscription request has been made by the developer, but has not yet been approved or rejected.- 4 - rejected – the subscription request has been denied by an administrator.- 5 - cancelled – the subscription has been canceled by the developer or administrator. |
DisplayName |
string | Display name of the subscription. |
CreatedDate |
dateTime | The date the subscription was created, in ISO 8601 format: 2014-06-24T16:25:00Z. |
CanBeCancelled |
boolean | Whether the subscription can be canceled by the current user. |
IsAwaitingApproval |
boolean | Whether the subscription is awaiting approval. |
StartDate |
dateTime | The start date for the subscription, in ISO 8601 format: 2014-06-24T16:25:00Z. |
ExpirationDate |
dateTime | The expiration date for the subscription, in ISO 8601 format: 2014-06-24T16:25:00Z. |
NotificationDate |
dateTime | The notification date for the subscription, in ISO 8601 format: 2014-06-24T16:25:00Z. |
primaryKey |
string | The primary subscription key. Maximum length is 256 characters. |
secondaryKey |
string | The secondary subscription key. Maximum length is 256 characters. |
CanBeRenewed |
boolean | Whether the subscription can be renewed by the current user. |
HasExpired |
boolean | Whether the subscription has expired. |
IsRejected |
boolean | Whether the subscription request was denied. |
CancelUrl |
string | The relative Url to cancel the subscription. |
RenewUrl |
string | The relative Url to renew the subscription. |
Subscription summary
The subscription summary entity has the following properties:
| Property | Type | Description |
|---|---|---|
Id |
string | Resource identifier. Uniquely identifies the subscription within the current API Management service instance. The value is a valid relative URL in the format of subscriptions/{sid} where {sid} is a subscription identifier. This property is read-only. |
DisplayName |
string | The display name of the subscription |
User account info
The user account info entity has the following properties:
| Property | Type | Description |
|---|---|---|
FirstName |
string | First name. Must not be empty. Maximum length is 100 characters. |
LastName |
string | Last name. Must not be empty. Maximum length is 100 characters. |
Email |
string | Email address. Must not be empty and must be unique within the service instance. Maximum length is 254 characters. |
Password |
string | User account password. |
NameIdentifier |
string | Account identifier, the same as the user email. |
ProviderName |
string | Authentication provider name. |
IsBasicAccount |
boolean | True if this account was registered using email and password; false if the account was registered using a provider. |
User sign in
The user sign in entity has the following properties:
| Property | Type | Description |
|---|---|---|
Email |
string | Email address. Must not be empty and must be unique within the service instance. Maximum length is 254 characters. |
Password |
string | User account password. |
ReturnUrl |
string | The URL of the page where the user clicked sign in. |
RememberMe |
boolean | Whether to save the current user's information. |
RegistrationEnabled |
boolean | Whether registration is enabled. |
DelegationEnabled |
boolean | Whether delegated sign in is enabled. |
DelegationUrl |
string | The delegated sign in url, if enabled. |
SsoSignUpUrl |
string | The single sign on URL for the user, if present. |
AuxServiceUrl |
string | If the current user is an administrator, this is a link to the service instance in the Azure portal. |
Providers |
Collection of Provider entities | The authentication providers for this user. |
UserRegistrationTerms |
string | Terms that a user must agree to before signing in. |
UserRegistrationTermsEnabled |
boolean | Whether terms are enabled. |
User sign up
The user sign up entity has the following properties:
| Property | Type | Description |
|---|---|---|
PasswordConfirm |
boolean | Value used by the sign-upsign-up control. |
Password |
string | User account password. |
PasswordVerdictLevel |
number | Value used by the sign-upsign-up control. |
UserRegistrationTerms |
string | Terms that a user must agree to before signing in. |
UserRegistrationTermsOptions |
number | Value used by the sign-upsign-up control. |
ConsentAccepted |
boolean | Value used by the sign-upsign-up control. |
Email |
string | Email address. Must not be empty and must be unique within the service instance. Maximum length is 254 characters. |
FirstName |
string | First name. Must not be empty. Maximum length is 100 characters. |
LastName |
string | Last name. Must not be empty. Maximum length is 100 characters. |
UserData |
string | Value used by the sign-up control. |
NameIdentifier |
string | Value used by the sign-upsign-up control. |
ProviderName |
string | Authentication provider name. |
Next steps
For more information about working with templates, see How to customize the API Management developer portal using templates.