# Desarrollo de API de REST mediante OpenAPI en API Gateway Puede utilizar API Gateway para importar una API REST desde un archivo de definición externo a API Gateway. Actualmente, API Gateway es compatible con los archivos de definición [OpenAPI v2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md) y [OpenAPI v3.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md), con las excepciones que se indican en [Notas importantes de Amazon API Gateway para las API REST](api-gateway-known-issues.md#api-gateway-known-issues-rest-apis). Puede actualizar una API sobrescribiéndola con una nueva definición o puede combinar una definición con una API existente. Las opciones se especifican utilizando un parámetro de consulta `mode` en la URL de solicitud. Para ver un tutorial sobre el uso de la característica Importar API desde la consola de API Gateway, consulte [Tutorial: Crear una API de REST importando un ejemplo](api-gateway-create-api-from-example.md). **Topics** + [Importación de una API optimizada para bordes en API Gateway](import-edge-optimized-api.md) + [Importación de una API regional en API Gateway](import-export-api-endpoints.md) + [Importación de un archivo de OpenAPI para actualizar una definición de la API existente](api-gateway-import-api-update.md) + [Establezca la propiedad `basePath` de OpenAPI](api-gateway-import-api-basePath.md) + [Variables de AWS para la importación de OpenAPI](import-api-aws-variables.md) + [Errores y advertencias al importar la API a API Gateway](api-gateway-import-api-errors-warnings.md) + [Exportación de una API REST desde API Gateway](api-gateway-export-api.md) # Importación de una API optimizada para bordes en API Gateway Puede importar un archivo de definición de OpenAPI de la API para crear una nueva API optimizada para bordes especificando el tipo de punto de conexión `EDGE` como entrada adicional, además del archivo de OpenAPI, en la operación de importación. Puede hacerlo mediante la consola de API Gateway, la AWS CLI o un SDK de AWS. Para ver un tutorial sobre el uso de la característica Importar API desde la consola de API Gateway, consulte [Tutorial: Crear una API de REST importando un ejemplo](api-gateway-create-api-from-example.md). **Topics** + [Importación de una API optimizada para bordes mediante la consola de API Gateway](#import-edge-optimized-api-with-console) + [Importación de una API optimizada para bordes a través de la AWS CLI](#import-edge-optimized-api-with-awscli) ## Importación de una API optimizada para bordes mediante la consola de API Gateway Si desea importar una API optimizada para bordes a través de la consola de API Gateway, haga lo siguiente: 1. Inicie sesión en la consola de API Gateway, en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Seleccione **Crear API**. 1. En **API de REST**, elija **Importar**. 1. Copie una definición de OpenAPI de la API y péguela en el editor de código o elija **Elegir archivo** para cargar un archivo de OpenAPI de una unidad local. 1. En **Tipo de punto de conexión de la API**, seleccione **Optimizado para bordes**. 1. Elija **Crear API** para empezar a importar las definiciones de OpenAPI. ## Importación de una API optimizada para bordes a través de la AWS CLI El siguiente comando [import-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-rest-api.html) permite importar una API desde un archivo de definición de OpenAPI para crear una API optimizada para bordes: ``` aws apigateway import-rest-api \ --fail-on-warnings \ --body 'file://path/to/API_OpenAPI_template.json' ``` También puede establecer explícitamente el parámetro de la cadena de consulta `endpointConfigurationTypes` en `EDGE`: ``` aws apigateway import-rest-api \ --parameters endpointConfigurationTypes=EDGE \ --fail-on-warnings \ --body 'file://path/to/API_OpenAPI_template.json' ``` # Importación de una API regional en API Gateway Al importar una API, puede elegir la configuración del punto de conexión regional de la API. Puede utilizar la consola de API Gateway, la AWS CLI o un SDK de AWS. Al exportar una API, la configuración del punto de conexión de la API no se incluye en las definiciones de API exportadas. Para ver un tutorial sobre el uso de la característica Importar API desde la consola de API Gateway, consulte [Tutorial: Crear una API de REST importando un ejemplo](api-gateway-create-api-from-example.md). **Topics** + [Importar una API regional mediante la consola de API Gateway](#import-regional-api-with-console) + [Importación de una API regional con la AWS CLI](#import-regional-api-with-awscli) ## Importar una API regional mediante la consola de API Gateway Para importar una API de un punto de conexión regional mediante la consola de API Gateway, haga lo siguiente: 1. Inicie sesión en la consola de API Gateway, en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Seleccione **Crear API**. 1. En **API REST**, elija **Importar**. 1. Copie una definición de OpenAPI de la API y péguela en el editor de código o elija **Elegir archivo** para cargar un archivo de OpenAPI de una unidad local. 1. En **Tipo de punto de conexión de la API**, seleccione **Regional**. 1. Elija **Crear API** para empezar a importar las definiciones de OpenAPI. ## Importación de una API regional con la AWS CLI El siguiente comando [import-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-rest-api.html) importa un archivo de definición de OpenAPI y establece el tipo de punto de conexión en Regional: ``` aws apigateway import-rest-api \ --parameters endpointConfigurationTypes=REGIONAL \ --fail-on-warnings \ --body 'file://path/to/API_OpenAPI_template.json' ``` # Importación de un archivo de OpenAPI para actualizar una definición de la API existente Puede importar las definiciones de la API únicamente para actualizar una API existente, sin cambiar la configuración del punto de enlace, así como las etapas y las variables de etapa o referencias a las claves de API. La operación de importar para actualizar puede producirse de dos modos: combinación o sobreescritura. Cuando una API (`A`) se combina con otra (`B`), la API resultante conserva las definiciones de `A` y `B` si las dos API no comparten definiciones contradictorias. Si surge un conflicto, las definiciones de método de la combinación de la API (`A`) invalida las definiciones de método correspondientes de la API combinada (`B`). Suponga, por ejemplo, que `B` ha declarado los siguientes métodos para devolver las respuestas `200` y `206`: ``` GET /a POST /a ``` y `A` declara el siguiente método para devolver las respuestas `200` y `400`: ``` GET /a ``` Cuando `A` se combina con `B`, la API resultante presenta los siguientes métodos: ``` GET /a ``` que devuelve las respuestas `200` y `400`, y ``` POST /a ``` que devuelve las respuestas `200` y `206`. Combinar una API es útil cuando ha descompuesto sus definiciones de API externas en varias partes más pequeñas y solo desea aplicar los cambios de una de esas partes a la vez. Esto podría ocurrir, por ejemplo, si varios equipos son responsables de diferentes partes de una API y han realizado cambios disponibles en diferentes partes. En este modo, los elementos de la API existente que no están específicamente definidos en la definición importada se dejan tal como están. Cuando una API (`A`) sobrescribe otra API (`B`), la API resultante adopta las definiciones de la API sobrescrita (`A`). Sobrescribir una API es útil cuando una definición de API externa contiene la definición completa de una API. En este modo, los elementos de una API existente que no están específicamente definidos en la definición importada se eliminan. Para combinar una API, envíe una solicitud `PUT` a `https://apigateway..amazonaws.com/restapis/?mode=merge`. El valor del parámetro de ruta `restapi_id` especifica la API con la que debe combinarse la definición de API proporcionada. El siguiente fragmento de código muestra un ejemplo de la solicitud `PUT` para combinar una definición de la API de OpenAPI en JSON, como la carga, con la API ya especificada en API Gateway. ``` PUT /restapis/?mode=merge Host:apigateway..amazonaws.com Content-Type: application/json Content-Length: ... An OpenAPI API definition in JSON ``` La operación de actualización por combinación toma dos definiciones de API completas y las combina. Para un cambio pequeño e incremental, puede usar la operación [resource update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateResource.html). Para sobrescribir una API, envíe una solicitud `PUT` a `https://apigateway..amazonaws.com/restapis/?mode=overwrite`. El parámetro de ruta `restapi_id` especifica la API que se sobrescribirá con las definiciones de API proporcionadas. El siguiente fragmento de código muestra un ejemplo de una solicitud de sobrescritura con la carga de una definición de OpenAPI con formato JSON: ``` PUT /restapis/?mode=overwrite Host:apigateway..amazonaws.com Content-Type: application/json Content-Length: ... An OpenAPI API definition in JSON ``` Cuando no se especifica el parámetro de consulta `mode`, se supone que se trata de una combinación. **nota** Las operaciones `PUT` son idempotentes, pero no atómicas. Eso significa que si se produce un error del sistema durante el procesamiento, la API puede acabar en mal estado. Sin embargo, si se repite la operación de forma exitosa, la API acaba en el mismo estado final que tendría si la primera operación se hubiera realizado con éxito. # Establezca la propiedad `basePath` de OpenAPI En [OpenAPI 2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md), puede utilizar la propiedad `basePath` para proporcionar una o varias partes de la ruta que preceden a cada una de las rutas definidas en la propiedad `paths`. Como API Gateway tiene varias maneras de expresar la ruta de un recurso, la característica Importar API ofrece las siguientes opciones para interpretar la propiedad `basePath` durante una importación: "ignore", "prepend" y "split". En [https://swagger.io/docs/specification/api-host-and-base-path/](https://swagger.io/docs/specification/api-host-and-base-path/), `basePath` ya no es una propiedad de nivel superior. En su lugar, API Gateway utiliza una [variable de servidor](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#serverVariableObject) como una convención. La característica Import API proporciona las mismas opciones para interpretar la ruta base durante la importación. La ruta base se identifica como se indica a continuación: + Si la API no contiene ninguna variable `basePath`, la característica Import API comprueba la cadena `server.url` para ver si contiene una ruta más allá `"/"`. Si es así, esa ruta se utiliza como la base de la ruta. + Si la API contiene una única variable `basePath`, la característica Import API la utiliza como la ruta base, incluso si no se hace referencia en el `server.url`. + Si la API contiene varias variables `basePath`, la característica Import API utiliza únicamente la primera como la ruta base. ## Ignore Si el archivo de OpenAPI tiene un valor `basePath` de `/a/b/c` y la propiedad `paths` contiene `/e` y `/f`, la siguiente solicitud `POST` o `PUT`: ``` POST /restapis?mode=import&basepath=ignore ``` ``` PUT /restapis/api_id?basepath=ignore ``` produce los siguientes recursos en la API: + `/` + `/e` + `/f` El efecto consiste en tratar `basePath` como si no estuviera presente, y todos los recursos de la API declarados se sirven en relación con el host. Esto puede utilizarse, por ejemplo, cuando disponga de un nombre de dominio personalizado con una asignación de API que no incluya un valor *Base Path* ni *Stage* que haga referencia a la etapa de producción. **nota** API Gateway crea automáticamente un recurso raíz, aunque no se haya declarado explícitamente en el archivo de definición. Cuando no se especifica, `basePath` toma `ignore` como valor predeterminado. ## Anexar Si el archivo de OpenAPI tiene un valor `basePath` de `/a/b/c` y la propiedad `paths` contiene `/e` y `/f`, la siguiente solicitud `POST` o `PUT`: ``` POST /restapis?mode=import&basepath=prepend ``` ``` PUT /restapis/api_id?basepath=prepend ``` produce los siguientes recursos en la API: + `/` + `/a` + `/a/b` + `/a/b/c` + `/a/b/c/e` + `/a/b/c/f` El efecto consiste en tratar `basePath` como si especificara recursos adicionales (sin métodos) y añadiera estos recursos al conjunto de recursos declarados. Esto puede utilizarse, por ejemplo, cuando diferentes equipos sean responsables de diferentes partes de una API y `basePath` pueda hacer referencia a la ubicación de ruta de la parte de la API de cada equipo. **nota** API Gateway crea automáticamente los recursos intermedios, aunque no se hayan declarado explícitamente en la definición. ## Split Si el archivo de OpenAPI tiene un valor `basePath` de `/a/b/c` y la propiedad `paths` contiene `/e` y `/f`, la siguiente solicitud `POST` o `PUT`: ``` POST /restapis?mode=import&basepath=split ``` ``` PUT /restapis/api_id?basepath=split ``` produce los siguientes recursos en la API: + `/` + `/b` + `/b/c` + `/b/c/e` + `/b/c/f` El efecto consiste en tratar la parte de la ruta superior, `/a`, como el principio de la ruta de cada recurso y crear recursos adicionales (sin método) dentro de la propia API. Esto podría usarse, por ejemplo, cuando `a` es un nombre de etapa que desee exponer como parte de la API. # Variables de AWS para la importación de OpenAPI Puede utilizar las siguientes variables de AWS en las definiciones de OpenAPI. API Gateway resuelve las variables cuando se importa la API. Para especificar una variable, utilice `${variable-name}`. En la siguiente tabla se describen las variables de AWS disponibles. | Nombre de variable | Descripción | | --- | --- | | AWS::AccountId | El ID de cuenta de AWS que importa la API. Por ejemplo: 123456789012. | | AWS::Partition | La partición de AWS en la que se importa la API. Para las regiones estándar de AWS, la partición es aws. | | AWS::Region | La región de AWS en la que se importa la API. Por ejemplo, us-east-2. | ## Ejemplo de variables de AWS En el siguiente ejemplo, se utilizan variables de AWS para especificar una función de AWS Lambda para una integración. ------ #### [ OpenAPI 3.0 ] ``` openapi: "3.0.1" info: title: "tasks-api" version: "v1.0" paths: /: get: summary: List tasks description: Returns a list of tasks responses: 200: description: "OK" content: application/json: schema: type: array items: $ref: "#/components/schemas/Task" 500: description: "Internal Server Error" content: {} x-amazon-apigateway-integration: uri: arn:${AWS::Partition}:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/arn:${AWS::Partition}:lambda:${AWS::Region}:${AWS::AccountId}:function:LambdaFunctionName/invocations responses: default: statusCode: "200" passthroughBehavior: "when_no_match" httpMethod: "POST" contentHandling: "CONVERT_TO_TEXT" type: "aws_proxy" components: schemas: Task: type: object properties: id: type: integer name: type: string description: type: string ``` ------ # Errores y advertencias al importar la API a API Gateway Al importar el archivo de definición externo a API Gateway, API Gateway puede generar advertencias y errores. En las siguientes secciones se describen los errores y las advertencias que pueden producirse durante la importación. ## Errores durante la importación Durante la importación, se pueden generar errores por problemas graves, como un documento de OpenAPI no válido. Los errores se devuelven como excepciones (por ejemplo, `BadRequestException`) en una respuesta incorrecta. Cuando se produce un error, la nueva definición de la API se descarta y no se realiza ningún cambio en la API existente. ## Advertencias durante la importación Durante la importación, se pueden generar advertencias por problemas menores, como la falta de una referencia del modelo. Si se produce una advertencia, la operación continuará si la expresión de consulta `failonwarnings=false` se añade a la URL de la solicitud. De lo contrario, las actualizaciones se revertirán. De forma predeterminada, `failonwarnings` está establecido en `false`. En estos casos, las advertencias se devuelven como un campo en el recurso [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) resultante. De lo contrario, las advertencias se devuelven como un mensaje en la excepción. # Exportación de una API REST desde API Gateway Una vez que haya creado y configurado una API REST en API Gateway mediante la consola de API Gateway o de otra forma, puede exportarla a un archivo de OpenAPI mediante la característica Exportar API de API Gateway, que forma parte del servicio de control de Amazon API Gateway. Para usar la API de exportación de API Gateway, debe firmar sus solicitudes de API. Para obtener más información sobre la firma de solicitudes, consulte [Firma de solicitudes de AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html) en la *Guía del usuario de IAM*. Dispone de opciones para incluir las extensiones de integración de API Gateway, así como las extensiones [Postman](https://www.postman.com), en el archivo de definición de OpenAPI exportado. **nota** Al exportar la API utilizando la AWS CLI, asegúrese de incluir el parámetro de la extensión tal y como se muestra en el siguiente ejemplo, para garantizar que se incluye la extensión `x-amazon-apigateway-request-validator`: ``` aws apigateway get-export --parameters extensions='apigateway' --rest-api-id abcdefg123 --stage-name dev --export-type swagger latestswagger2.json ``` No puede exportar una API si sus cargas no son del tipo `application/json`. Si lo intenta, obtendrá una respuesta de error en la que se indica que no se encuentran los modelos del cuerpo JSON. ## Solicitud de exportación de una API de REST Con la API Export, puede exportar una API de REST existente enviando una solicitud GET en la que se especifique la API que se va exportar como parte de las rutas URL. La URL de la solicitud debe tener el siguiente formato: ------ #### [ OpenAPI 3.0 ] ``` https:///restapis//stages//exports/oas30 ``` ------ #### [ OpenAPI 2.0 ] ``` https:///restapis//stages//exports/swagger ``` ------ Puede asociar la cadena de consulta `extensions` para especificar si desea incluir extensiones de API Gateway (con el valor `integration`) o extensiones de Postman (con el valor `postman`). Además, puede establecer el encabezado `Accept` en `application/json` o `application/yaml` para recibir la salida de la definición de la API en formato JSON o YAML, respectivamente. Para obtener más información sobre cómo enviar solicitudes GET utilizando la función Exportar API de API Gateway, consulte [GetExport](https://docs.aws.amazon.com/apigateway/latest/api/API_GetExport.html). **nota** Si define modelos en la API, deben ser para el tipo de contenido de "application/json" para que API Gateway pueda exportar el modelo. De lo contrario, API Gateway produce una excepción con el mensaje de error "Only found non-JSON body models for ...". Los modelos deben contener propiedades o definirse como un tipo de JSONSchema determinado. ## Descarga de la definición de OpenAPI de la API de REST en JSON Para exportar y descargar una API de REST en definiciones de OpenAPI con formato JSON: ------ #### [ OpenAPI 3.0 ] ``` GET /restapis//stages//exports/oas30 Host: apigateway..amazonaws.com Accept: application/json ``` ------ #### [ OpenAPI 2.0 ] ``` GET /restapis//stages//exports/swagger Host: apigateway..amazonaws.com Accept: application/json ``` ------ Aquí, `` podría ser, por ejemplo, `us-east-1`. Para todas las regiones donde API Gateway está disponible, consulte [Regiones y puntos de conexión](https://docs.aws.amazon.com/general/latest/gr/rande.html#apigateway_region). ## Descarga de la definición de OpenAPI de la API de REST en YAML Para exportar y descargar una API de REST en definiciones de OpenAPI con formato YAML: ------ #### [ OpenAPI 3.0 ] ``` GET /restapis//stages//exports/oas30 Host: apigateway..amazonaws.com Accept: application/yaml ``` ------ #### [ OpenAPI 2.0 ] ``` GET /restapis//stages//exports/swagger Host: apigateway..amazonaws.com Accept: application/yaml ``` ------ ## Descarga de la definición de OpenAPI de la API de REST con extensiones Postman en JSON Para exportar y descargar una API de REST en definiciones de OpenAPI con Postman en formato JSON: ------ #### [ OpenAPI 3.0 ] ``` GET /restapis//stages//exports/oas30?extensions=postman Host: apigateway..amazonaws.com Accept: application/json ``` ------ #### [ OpenAPI 2.0 ] ``` GET /restapis//stages//exports/swagger?extensions=postman Host: apigateway..amazonaws.com Accept: application/json ``` ------ ## Descarga de la definición de OpenAPI de la API REST con la integración de API Gateway en YAML Para exportar y descargar una API REST en definiciones de OpenAPI con la integración de API Gateway en formato YAML: ------ #### [ OpenAPI 3.0 ] ``` GET /restapis//stages//exports/oas30?extensions=integrations Host: apigateway..amazonaws.com Accept: application/yaml ``` ------ #### [ OpenAPI 2.0 ] ``` GET /restapis//stages//exports/swagger?extensions=integrations Host: apigateway..amazonaws.com Accept: application/yaml ``` ------ ## Exportar API REST con la consola de API Gateway Después de [implementar la API REST en una etapa](set-up-deployments.md#create-deployment), puede empezar a exportar la API en la etapa a un archivo de OpenAPI mediante la consola de API Gateway. En el panel **Etapas** de la consola de API Gateway, elija **Acciones de etapa**, **Exportar**. ![\[Exportar API REST con la consola de API Gateway\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/export-new-console.png) Especifique un **Tipo de especificación de API**, **Formato** y **Extensiones** para descargar la definición de OpenAPI de la API.