Definir recursos, modelos y operaciones en una API REST

Utilice el Editor de API REST para definir gráficamente recursos, modelos y operaciones en una API REST.

Para definir recursos, modelos y operaciones en una API REST, realice los pasos siguientes:

1. Utilice la sección Cabecera del Editor de API REST para visualizar y modificar información general sobre la API REST.

   ElREST API base URLmuestra la vía de acceso base actual para la API REST. Todos los recursos de una API REST se definen en relación a su vía de acceso base. Puede editar este campo para modificar la vía de acceso base de la API REST. El valor de este campo debe ser un segmento de vía de acceso de URL válido y no debe contener ningún elemento variable.

   ElTitlemuestra el título actual de la API REST. El Título es distinto del nombre del proyecto de API REST, y se define como una propiedad en el documento Swagger. El título se utiliza al impulsar una API REST en IBM API Management.

   ElVersionmuestra la versión actual de la API REST. Se define como una propiedad en el documento Swagger. La versión se utiliza al impulsar una API REST en IBM API Management.

   La sección de cabecera también incluye un ejemplo de URL base de la API REST. Las partes <nombre de host> y <número de puerto> de este URL deben sustituirse por el nombre de host y el número de puerto del servidor de integración en el que se ha desplegado la API REST. Para poder invocar una operación definida en esta API REST utilizando un cliente HTTP, debe combinar el URL base de la API REST, la vía de acceso del recurso de operaciones y el método HTTP para la operación que se está invocando. En función de la operación que se esté invocando, también es posible que tenga que pasar parámetros adicionales o un cuerpo de solicitud.

2. Utilice la sección Recursos para manipular los recursos de la API REST:
   • Utilice este botón para crear un nuevo recurso en la API REST. Al pulsar este botón, se visualiza un diálogo en el que puede especificar la vía de acceso de recursos y seleccionar las operaciones que desea añadir al recurso:GET,POST,PUT,DELETE,OPTIONS,HEAD, yPATCH. Al pulsar OK, el nuevo recurso y las operaciones para ese recurso se añaden a la API REST.
   • También puede añadir y eliminar operaciones de un recurso después de que se haya creado. Utilice el botón del lado derecho del recurso para añadir operaciones adicionales a un recurso existente. Utilice el botón en la parte derecha de la operación para eliminar dicha operación de su recurso.
   • Utilice este botón para modificar la vía de acceso de recursos. Al pulsar este botón, se visualiza un diálogo en el que puede modificar la vía de acceso del recurso.
   • Utilice este botón para expandir todas las operaciones bajo cada recurso.
   • Utilice este botón para contraer todas las operaciones bajo cada recurso.
3. Cuando haya añadido una operación bajo un recurso, puede manipularla.
   Una operación puede tener varios tipos diferentes de parámetros, y 0 o más respuestas que se muestran en estas secciones:

   • Parámetro de Vía de acceso, Consulta, y Cabecera

     Utilice el botón Añadir y el botón Suprimir para añadir o suprimir parámetros de cabecera y consulta y, a continuación, establezca su Nombre, Tipo y Tipo de datos y, opcionalmente, los valores de Formato, Necesario y Descripción.

     ElNameyTypelos campos de un parámetro Path no se pueden cambiar y el nombre debe coincidir con la plantilla de vía de acceso del recurso. Los parámetros de vía de acceso sólo se pueden añadir o eliminar editando la plantilla de vía de acceso en el recurso.

     El Tipo de datos de un parámetro de Vía de acceso, Consulta o Cabecera sólo puede establecerse en un tipo de datos primitivo, como por ejemplo string, number, integer o boolean. Estos tipos de datos primitivos se corresponden con los de la especificación Swagger, y se correlacionan con los posibles tipos primitivos de un documento JSON. No se puede establecer el tipo de datos de un parámetro de Vía de acceso, Consulta o Cabecera al de un modelo definido en la API REST. El tipo de datos de un parámetro de vía de acceso, consulta o cabecera no lo utiliza actualmente el tiempo de ejecución de IBM Integration Bus y los parámetros se proporcionan a los nodos del subflujo como datos de caracteres. La correlación de datos gráficos los modela como series de caracteres. Sin embargo, es aconsejable establecer el parámetro correctamente para su uso con herramientas de Swagger.

     ElFormates una descripción opcional de formato libre del formato de los datos que se espera para los valores de este parámetro. Por ejemplo, puede utilizar formatos mencionados en la especificación Swagger como, por ejemplo,int32,double, odate-time. Como alternativa, puede incluir sus propios nombres de formato, comocustomer-id. El formato de un parámetro Path, Query o Header no lo utiliza actualmente el tiempo de ejecución de IBM Integration Bus ; sin embargo, es aconsejable establecerlo correctamente para utilizarlo con las herramientas Swagger.

     ElRequiredindica si los clientes HTTP que invocan esta operación deben especificar o no el parámetro. Un cliente HTTP debe especificar siempre los parámetros de vía de acceso en el URL de solicitud. Este campo no se puede cambiar para los parámetros de vía de acceso. Los parámetros de Consulta y de Cabecera pueden marcarse como opcionales deseleccionado este recuadro de selección. La presencia de un parámetro Consulta o Cabecera no está validada actualmente por el tiempo de ejecución de IBM Integration Bus . Sin embargo, es aconsejable establecerlos correctamente para su uso con herramientas de Swagger.

     El tipo de parámetro de formulario Swagger no está soportado en IBM Integration Bus.

   • Cuerpo de solicitud

     Utilice el botón Añadir solicitud y el botón Suprimir para añadir o suprimir un cuerpo de solicitud, si se permite un cuerpo de solicitud para el método HTTP de la operación seleccionada. Por ejemplo:GET,HEAD,DELETE, yOPTIONSlas solicitudes no permiten los cuerpos de solicitud.

     Un cuerpo de solicitud es generalmente un documento JSON, y la estructura de ese documento JSON puede definirse en un modelo. La estructura de un cuerpo de solicitud no está validada actualmente por el tiempo de ejecución de IBM Integration Bus . Sin embargo, puede utilizarse la definición de modelo con un nodo Mapping para implementar gráficamente la operación de la API REST. Es aconsejable definir modelos para todos los posibles cuerpos de solicitud JSON de la API, para su uso con herramientas de Swagger.

     ElSchema typefor Request incluye todos los tipos de datos primitivos, comostring,number,integer, oboolean, además de todos los modelos definidos en la API.

   • Cuerpo de respuesta

     Utilice el botón Añadir respuesta y el botón Suprimir para añadir o suprimir una respuesta, si se permite un cuerpo de respuesta para el método HTTP de la operación seleccionada. Por ejemplo:HEADlas solicitudes no devuelven un cuerpo de respuesta.

     Establecer laHTTP status code numberpara esta respuesta como el valor de laResponse Status. El código de estado HTTP debe ser un código de estado HTTP válido según se describe en RFC 7231 o en el registro de códigos de estado IANA. Puede tener varias respuestas definidas para una sola operación, pero el código de estado HTTP de una respuesta debe ser exclusivo dentro de dicha operación.

     Un cuerpo de respuesta es generalmente un documento JSON, y la estructura de ese documento JSON puede definirse en un modelo. La estructura de un cuerpo de respuesta no está validada actualmente por el tiempo de ejecución de IBM Integration Bus . Sin embargo, puede utilizarse la definición de modelo con un nodo Mapping para implementar gráficamente la operación de la API REST. Es aconsejable definir modelos para todos los posibles cuerpos de respuesta JSON de la API para su uso con herramientas de Swagger.

     ElSchema typefor Response incluye todos los tipos de datos primitivos, comostring,number,integer, oboolean, además de todos los modelos definidos en la API. Además, puede especificar si esta operación devuelve una matriz de valores, donde el tipo de cada elemento de dicha matriz está definido por el campo Tipo de esquema. Si especifica que la respuesta es una matriz y el tipo de esquema hace referencia a un modelo que es en sí mismo una matriz, se definirá que la respuesta devuelve una matriz de matrices

4. Utilice la sección Definiciones de modelo del editor para definir los datos JSON que puede utilizar para la solicitud y la respuestaSchema typeen sus operaciones.
   Para crear un nuevo tipo de datos de modelo, pulse el botón Añadir situado junto al campo Definiciones de modelo y especifique un nombre para el nuevo tipo de datos JSON:

   

   Puede definir modelos de tipoobject,string,integer,number,boolean, ynull.

   Nota: El tipo de datos de archivo no está soportado por IBM Integration Bus; no puede establecer un parámetro o un tipo de modelo comofile.

   Para crear un modelo de objeto cuando haya especificado su nombre, utilice el botón Añadir un hijo para la selección , situado en la parte superior derecha de la sección Definiciones de modelo , para añadir el primer hijo. A continuación, puede añadir más hijos para construir la estructura necesaria:

   

   Puede especificar si el tipo de datos debe ser una matriz, si es obligatorio, si permitirá valores nulos, y puede especificar un formato. Formato es un campo de texto de formato libre, que puede utilizar para describir el formato de los datos. Por ejemplo, puede tener una serie con un formato dedate. Para obtener más información, consulte http://swagger.io/specification/#dataTypeFormat.

   El ejemplo siguiente muestra la definición de un tipo de esquema Pet:

   

   Este tipo de esquema de Animales Modelo se puede utilizar en unGETpara producir un mensaje de datos JSON con el formato siguiente:

   {
   	"id": 1001,
   	"category": {
   		"id": 10,
   		"name": "Cat"
   	},
   	"name": "Moggy",
   	"photoUrls": ["http:\/\/something.com\/images?q=tbn:XmoggyJjB2XhAqq97VzJP"],
   	"tags": [{
   		"id": 11,
   		"name": "Moggy"
   	}],
   	"status": "pending"
   }

   También podría definir unGETpara devolver varias mascotas estableciendo el tipo de esquema de operación en Animales y comprobando laArrayopción: