Manage models

Overview

A model defines the structure of HTTP request and response data for your APIs. In API Gateway, you use JSON Schema to create models that describe request and response parameters — including data types, formats, and value constraints.

When a model is referenced in an API definition, API Gateway automatically generates a POJO (Plain Old Java Object) class in the SDKs for that API group. This makes it easier to construct requests and deserialize response data.

Limits

API Gateway models follow the JSON Schema Draft-04 standard. The following limits apply:

JSON schemas must be of the object type.
API definitions can only reference models you have created. Retrieve the $ref address by calling the CreateModel or DescribeModels operation.
Circular references are not supported.

Model definition example

The following example defines a model with required fields, typed properties, a cross-model reference, a regex pattern constraint, and a nested object:

{
        "required": ["name", "photoUrls"],
        "type": "object",
        "properties": {
                "id": {
                        "format": "int64",
                        "type": "integer"
                },
                "category": {
                        "$ref": "https://apigateway.aliyun.com/models/bbc725be4b0b48b79bdd2f6ebbdcc8c0/a5e7741d8a3a4bcb9746275a0db15fcf"
                },
                "name": {
                        "pattern": "^\\d{3}-\\d{2}-\\d{4}$",
                        "type": "string"
                },
                "status": {
                        "type": "string"
                },
                "dogProject": {
                        "type": "object",
                        "properties": {
                                "id": {
                                        "format": "int64",
                                        "maximum": 100,
                                        "exclusiveMaximum": true,
                                        "type": "integer"
                                },
                                "name": {
                                        "maxLength": 10,
                                        "type": "string"
                                }
                        }
                }
        }
}

In this example:

id is an integer in int64 format.
category uses $ref to reference another model by its URI.
name is a string that must match the regex pattern ^\d{3}-\d{2}-\d{4}$.
dogProject is a nested object. Its id field has an exclusive maximum of 100, and its name field is limited to 10 characters.

Create a model

Create a model using the API Gateway console, the CreateModel API operation, or by importing an OpenAPI Specification file.

Create a model in the console

Log on to the API Gateway console.
In the left-side navigation pane, choose Manage APIs > API Groups.
On the API Groups page, find the target API group and click Manage Model in the Actions column.
On the Models page, click Create Model.

Create a model by importing an OpenAPI Specification file

Define models in an OpenAPI Specification file and import it into API Gateway. After the import, API Gateway automatically creates the models for the corresponding API group. For more information, see Import Swagger files to create APIs with API Gateway extensions.

Important

If a model in the imported file has the same name as an existing model in the console, the imported model silently replaces the existing one without any notification.

View and modify a model

After you create a model, view it on the Models page. The model details page shows the model name, model definition, and the URI that the system assigns to the model. Use this URI to reference the model from other model definitions with the $ref:{URI} format.

To modify a model, click Modify in the upper-right corner of the model details page.

Important

Modifying a model does not change its URI. Existing references to the model continue to work.

Delete a model

You can delete a model that belongs to an API group.

Important

Deleting a model also removes all request and response definitions associated with it. If an API that references the model has been published to the production environment, SDK export for that API group may fail. Proceed with caution.