Modelos de datos para las API de REST - Amazon API Gateway
Creación de modelos más complejosUso de modelos de datos de salidaSiguientes pasos

Modelos de datos para las API de REST

En API Gateway, un modelo define la estructura de datos de una carga. En API Gateway, los modelos se definen mediante el borrador 4 del esquema JSON. El siguiente objeto JSON incluye datos de muestra del ejemplo de la tienda de mascotas (Pet Store).

{
    "id": 1,
    "type": "dog",
    "price": 249.99
}

Los datos contienen el id, type y price de la mascota. Un modelo de estos datos le permite:

  • Utilizar la validación básica de solicitudes.

  • Crear plantillas de mapeo para la transformación de datos.

  • Crear un tipo de datos definido por el usuario (UDT) al generar un SDK.

Ejemplo de modelo de datos JSON para la API de PetStore.

En este modelo:

  1. El objeto $schema representa un identificador de versión válido del esquema JSON. Este esquema es la versión 4 del borrador del esquema JSON.

  2. El objeto title es un identificador descriptivo del modelo. Este título es PetStoreModel.

  3. La palabra clave de validación required requiere type y price para la validación básica de solicitudes.

  4. Las properties del modelo son id, type y price. Cada objeto tiene propiedades que se describen en el modelo.

  5. El objeto type solo puede tener los valores dog, cat o fish.

  6. El objeto price es un número y está restringido con un valor minimum de 25 y un valor maximum de 500.

1 {
2 "$schema": "http://json-schema.org/draft-04/schema#",
3  "title": "PetStoreModel",
4  "type" : "object",
5  "required" : [ "price", "type" ],
6  "properties" : {
7    "id" : {
8      "type" : "integer"
9    },
10    "type" : {
11      "type" : "string",
12      "enum" : [ "dog", "cat", "fish" ]
13    },
14    "price" : {
15      "type" : "number",
16      "minimum" : 25.0,
17      "maximum" : 500.0
18    }
19  }
20 }

En este modelo:

  1. En la línea 2, el objeto $schema representa un identificador de versión válido del esquema JSON. Este esquema es la versión 4 del borrador del esquema JSON.

  2. En la línea 3, el objeto title es un identificador descriptivo del modelo. Este título es PetStoreModel.

  3. En la línea 5, la palabra clave de validación required requiere type y price para la validación básica de solicitudes.

  4. En las líneas 6 a 17, las properties del modelo son id, type y price. Cada objeto tiene propiedades que se describen en el modelo.

  5. En la línea 12, el objeto type solo puede tener los valores dog, cat o fish.

  6. En las líneas 14 a 17, el objeto price es un número y está restringido con un valor minimum de 25 y un valor maximum de 500.

Creación de modelos más complejos

Puede utilizar la primitiva $ref para crear definiciones reutilizables para modelos más largos. Por ejemplo, puede crear una definición llamada Price en la sección definitions que describa el objeto price. El valor de $ref es la definición de Price. 

{
  "$schema" : "http://json-schema.org/draft-04/schema#",
  "title" : "PetStoreModelReUsableRef",
  "required" : ["price", "type" ],
  "type" : "object",
  "properties" : {
    "id" : {
      "type" : "integer"
    },
    "type" : {
      "type" : "string",
      "enum" : [ "dog", "cat", "fish" ]
    },
    "price" : {
        "$ref": "#/definitions/Price"
    }
  },
  "definitions" : {
      "Price": {
        "type" : "number",
        "minimum" : 25.0,
        "maximum" : 500.0
            }
      }
}

También puede hacer referencia a otro esquema de modelo definido en un archivo de modelo externo. Defina el valor de la propiedad $ref en la ubicación del modelo. En el siguiente ejemplo, el modelo Price se define en el modelo PetStorePrice de la API a1234.

{
  "$schema" : "http://json-schema.org/draft-04/schema#",
  "title" : "PetStorePrice",
  "type": "number",
  "minimum": 25,
  "maximum": 500
}

El modelo más largo puede hacer referencia al modelo PetStorePrice.

{
  "$schema" : "http://json-schema.org/draft-04/schema#",
  "title" : "PetStoreModelReusableRefAPI",
  "required" : [ "price", "type" ],
  "type" : "object",
  "properties" : {
    "id" : {
      "type" : "integer"
    },
    "type" : {
      "type" : "string",
      "enum" : [ "dog", "cat", "fish" ]
    },
    "price" : {
        "$ref": "https://apigateway.amazonaws.com/restapis/a1234/models/PetStorePrice"
    }
  }
}

Uso de modelos de datos de salida

Si transforma sus datos, puede definir un modelo de carga en la respuesta de integración. Se puede utilizar un modelo de carga al generar un SDK. Para lenguajes con establecimiento inflexible de tipos, como Java, Objective-C o Swift, el objeto se corresponde con un tipo de datos definido por el usuario (UDT). API Gateway crea un UDT si le facilita un modelo de datos al generar un SDK. Para obtener más información sobre las transformaciones de datos, consulte Plantillas de asignación para las API de REST.

En el siguiente ejemplo se muestran datos de salida de una respuesta de integración.

{
[
  {
    "description" : "Item 1 is a dog.",
    "askingPrice" : 249.99
  },
  {
    "description" : "Item 2 is a cat.",
    "askingPrice" : 124.99
  },
  {
    "description" : "Item 3 is a fish.",
    "askingPrice" : 0.99
  }
]
}

En el siguiente ejemplo se muestra un modelo de carga que describe los datos de salida.

{
"$schema": "http://json-schema.org/draft-04/schema#",
  "title": ”PetStoreOutputModel",
  "type" : "object",
  "required" : [ "description", "askingPrice" ],
  "properties" : {
    "description" : {
      "type" : "string"
    },
    "askingPrice" : {
      "type" : "number",
      "minimum" : 25.0,
      "maximum" : 500.0
    }
  }
}

Con este modelo, puede llamar a un SDK para recuperar los valores de las propiedades description y askingPrice al leer las propiedades PetStoreOutputModel[i].description y PetStoreOutputModel[i].askingPrice. Si no se proporciona un modelo, API Gateway utiliza el modelo vacío para crear un UDT predeterminado.

Siguientes pasos