1. Overview and limits

A model is used to configure HTTP request and response information for API operations. 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 operation, API Gateway automatically generates a POJO class in the SDKs of the API group to which the API operation belongs. This makes it easier for you to configure request and response information for an API operation 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. Take note of the following limits when you create a model: You can create JSON schemas only of the object type. When you define request and response information for an API operation, you can reference only a model that is created by you. You can call the Create Model and Get a model you've created operations to query the URI of a model that you can use to reference the model. 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 Create Model operation, provided by Alibaba Cloud, 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. In the left-side navigation pane, choose Publish APIs > API Groups.
  2. On the Group List page, find the target API group and click View Models in the Operation column.

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 Create APIs By Importing Swagger. 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. Note that if a model in the OpenAPI specification file has the same name as an existing model in the API Gateway console, the model in the OpenAPI specification file will replace the existing model and you will not be notified.

3. Modify and view a model

After you create a model, you can view the model on the Model Management page. On the model details page, you can view the model name, the 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. Note that after a model is modified, its URI is not changed.

4. Delete a model

You can delete a model that is defined for an API group. Note that after you delete a model, the request and response information that is defined by the model for an API operation will also be deleted. For an API operation that references the model and is published to the production environment, the SDKs of the API group to which the API operation belongs may fail to be exported. Therefore, proceed with caution when you delete a model.