API Gateway:Manage models

1. Overview and limits

A model is used to configure HTTP request and response information for APIs. API Gateway allows you to use JSON Schema to create a model that defines API request and response information, such as request and response parameters and their value ranges. If you create a model and reference the model when you create an API, API Gateway automatically generates a POJO class in the SDKs of the API group to which the API belongs. This makes it easier for you to configure request and response information for an API and deserialize response data.

In API Gateway, models are created based on the standards in JSON Schema Draft-04. For more information, see JSON Schema: core definitions and terminology draft-zyp-json-schema-04. Take note of the following limits when you create a model:

1. You can create JSON schemas only of the object type.

2. When you define request and response information for an API, you can reference only a model that is created by you. You can obtain the address for reference ('ref') by calling the CreateModel and DescribeModels operations. Circular reference is not supported.

The following code snippet shows an example of a model definition.

{
        "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"
                                }
                        }
                }
        }
}

2. Create a model

You can call the CreateModel operation to create a model in API Gateway. Alternatively, you can create a model in the API Gateway console.

Create a model in the API Gateway console

1. Log on to the API Gateway console.

2. In the left-side navigation pane, choose Manage APIs] > API Groups.

3. On the API Groups page, find the target API group and click Manage Modle in the Actions column. On the Models page, click Create Model.

Create a model by importing an OpenAPI specification file

API Gateway allows you to create a model by importing an OpenAPI specification file. For more information, see Import Swagger files to create APIs with API Gateway extensions. After you import an OpenAPI specification file in which a model is defined for an API group, the model is automatically created for the API group in the API Gateway console.

3. Modify and view a model

After you create a model, you can view the model on the Models page. On the model details page, you can view the model name, model definition, and the URI that is allocated to the model by the system. When you define a model, you can reference another model by using the $ref:{URI} format.

If you need to modify the model, click Modify in the upper-right corner.

4. Delete a model

You can delete a model that is defined for an API group.