Ejemplo - Gestión de una API

URL base

Puede crear la base URL de una API mediante las asignaciones de dominio, puerto y contexto de la API. Por ejemplo, si el nombre del servidor es www.phonestore.com, el puerto es 8080 y el contexto de la API es api. La base completa URL es la siguiente.

http://www.phonestore.com:8080/api

Parámetros API de nivel superior

Todos los recursos y métodos incluidos en los recursos individuales heredan los parámetros definidos en el nivel superior de la API.

Recursos de la API

Los recursos son los componentes básicos de una API. Algunos ejemplos de recursos de una API en línea phonestore son un teléfono, un pedido de una tienda y una colección de clientes. Después de identificar un servicio para exponerlo como API, defina los recursos para la API.

Por ejemplo, para la API en línea phonestore , puede representar los datos de la base de datos de la tienda de teléfonos como una API de varias maneras. Los verbos de la solicitud HTTP corresponden a las operaciones que admite la base de datos, como seleccionar, crear, actualizar o eliminar.

Cada recurso debe tener una dirección URI única. Con el URI, que va a exponer para cada recurso también debe decidir lo que se puede hacer a cada recurso. Los métodos HTTP pasados como parte de una cabecera de solicitud HTTP dirigen la API sobre lo que hay que hacer con el recurso direccionado.

URL de recursos

Un URL identifica la ubicación de un recurso específico.

Por ejemplo, para la API de la tienda telefónica en línea, los recursos tienen las siguientes URL:

webMethods API Gateway admite los siguientes patrones de recursos URL : una colección de recursos o un recurso concreto.

Por ejemplo, en la API en línea phonestore , los patrones son los siguientes:

Patrón para una colección URL. http://phonestore.com/api/phones

Patrón para un URL único. http://phonestore.com/api/phones/412456/features para recuperar un recurso de colección que describe las características principales del teléfono cuyo código de producto es 412456

Parámetros de recursos

Todos los métodos del recurso en cuestión heredan todos los parámetros definidos en el nivel superior del recurso. Esta herencia no afecta a la API.

Métodos de recursos

Los recursos individuales pueden definir sus capacidades utilizando los métodos compatibles de HTTP. Para invocar una API, el cliente puede llamar a una operación HTTP en la dirección URL asociada al recurso de la API. Por ejemplo, para recuperar la información sobre las características principales de un teléfono cuyo código de producto es 412456, el cliente podría realizar una llamada de servicio HTTP GET en el siguiente URL.

http://www.phonestore.com/phones/412456/features

Métodos admitidos HTTP

webMethods API Gateway admite los métodos estándar de HTTP para el modelado de API: GET, POST, PUT, DELETE y PATCH.

La siguiente tabla describe la semántica de los métodos de HTTP para el ejemplo de Phone Store API:

Parámetros del método

Los parámetros que se definen a nivel de submétodo sólo se aplican a ese método concreto; no afectan ni a la API ni al recurso.

Parámetros de API

Los parámetros especifican información adicional a una solicitud. Los parámetros se utilizan como parte de URL o en las cabeceras o como componentes del cuerpo de un mensaje.

Niveles de parámetros

Un parámetro puede establecerse en diferentes niveles de una API. Cuando se documenta una API REST en API Gateway, se definen parámetros a nivel de API, a nivel de recurso o a nivel de método para abordar los siguientes escenarios:

• Si el parámetro es aplicable a todos los recursos de la API, deberá definirlo a nivel de API. El parámetro a nivel de API implica que el parámetro se propaga a todos los recursos y métodos bajo la API en particular.
• Si el parámetro es aplicable a todos los métodos de la API, deberá definirlo a nivel de recurso. El parámetro a nivel de recurso implica que el parámetro se propaga a todos los métodos bajo el recurso en particular.
• Si el parámetro sólo es aplicable a un método de la API, deberá definirlo a nivel de método.

Parámetros a nivel de API

La parametrización a nivel de API permite la asignación automática de los parámetros a todos los recursos y métodos incluidos en la API. Cualquier valor de parámetro que se especifique en el nivel superior de la API anula el valor de parámetro que se haya establecido en el nivel del subrecurso o del submétodo si los nombres de los parámetros son idénticos.

Por ejemplo, si usted tiene un parámetro de cabecera que se llama API Key que se utiliza para consumir una API.

x-Gateway-APIKey:a4b5d569-2450-11e3-b3fc-b5a70ab4288a

Este parámetro es específico para toda la API y para los componentes individuales que son recursos y métodos, directamente dentro de la API. Un parámetro de este tipo puede definirse como parámetro a nivel de API.

A nivel de API, puede definir los siguientes tipos de parámetros.

• Parámetro Query-String
• Parámetro de cabecera

Parámetros a nivel de recursos

El establecimiento de parámetros a nivel de recurso permite la asignación automática de los parámetros a todos los métodos dentro del recurso. Cualquier valor de parámetro que especifiques en el nivel de recurso superior anula el valor de parámetro que establezcas en el nivel de submétodo si los nombres de los parámetros son los mismos. En cambio, los parámetros del nivel de subrecursos no afectan a los parámetros del nivel superior de la API.

Considere el ejemplo de la API phonestore que mantiene una base de datos de reseñas sobre diferentes teléfonos. Una solicitud para mostrar información sobre una revisión de usuario en particular, 78 del teléfono cuyo código de producto es 412456 es la siguiente.

GET /phones/412456/user_reviews/78

En el ejemplo, el parámetro /user_reviews/78 restringe el enfoque de una solicitud GET a la revisión de /78 dentro de un recurso concreto /412456.

Este parámetro es específico del recurso teléfono concreto cuyo código de producto es 412456 y de cualquier método individual que se encuentre directamente dentro del recurso concreto. Dicho parámetro puede definirse como un parámetro a nivel de recurso.

A nivel de recurso, puede definir los siguientes tipos de parámetros:

• Parámetro Query-String
• Parámetro de cabecera
• Parámetro de ruta

Parámetros a nivel de método

Si no establece parámetros a nivel de API o a nivel de recurso, puede establecerlos a nivel de método. Los parámetros que se establecen a nivel de método se utilizan para la ejecución del método HTTP. Son útiles para restringir los datos de respuesta devueltos para una solicitud HTTP. Cualquier valor de parámetro que se especifique en el nivel de submétodo queda anulado por el valor establecido en el parámetro de nivel de API superior o el parámetro de nivel de recurso superior si los nombres son idénticos. En cambio, los parámetros a nivel de submétodo no afectan a los parámetros superiores a nivel de API o de recurso.

Por ejemplo, la API phonestore descrita podría tener una solicitud para mostrar información que el usuario Allen en 2013 sobre un teléfono cuyo código de producto es 412456 contribuye.

GET /phones/412456/user_reviews/78?year=2013&name=Allen

En este ejemplo, year=2013 y name=Allen limitan el foco de la solicitud GET a las entradas que el usuario Allen añadió a la revisión del usuario 78 en 2013.

A nivel de método, puede definir los siguientes tipos de parámetros.

• Parámetro Query-String
• Parámetro de cabecera

Tipos de parámetro

webMethods API Gateway admite tres tipos de parámetros en la API REST: Query-String, Header y Path.

Puede utilizar diferentes tipos de parámetros para parametrizar los recursos, como se indica a continuación.

Parámetros de cadena de consulta

Los parámetros Query-String se añaden al URI después de un ? con pares nombre-valor. La secuencia de pares nombre-valor se separa con punto y coma o con un signo ampersand.

Por ejemplo, si el URL es http://phonestore.com/api/phones?itemID=itemIDValue, el nombre del parámetro de consulta es itemID, y el valor es el itemIDValue. Los parámetros de consulta se utilizan a menudo cuando se filtra o se busca a través de HTTP peticiones GET.

Consideremos ahora la API de la tienda telefónica en línea. Un cliente, cuando se trata de buscar una colección de teléfonos, es posible que desee añadir opciones, tales como, android v4.3 OS y 8MP cámara. El URI de este recurso tiene el siguiente aspecto.

/phones?features=androidosv4.3&cameraresolution=8MP

Parámetros de cabecera

Los parámetros de cabecera son HTTP headers. Las cabeceras suelen contener información de metadatos para el cliente o el servidor.

x-Gateway-APIKey:a4b5d569-2450-11e3-b3fc-b5a70ab4288a

Puede crear cabeceras personalizadas, según sus necesidades. Como práctica recomendada, anteponga al nombre de la cabecera el prefijo x-.

HTTP/1.1 define las cabeceras que pueden aparecer en una respuesta HTTP en tres secciones del RFC 2616: 4.5, 6.2 y 7.1. Examine estos códigos para determinar cuáles son apropiados para la API.

Parámetros de vía de acceso

Los parámetros de ruta se definen como parte de la URI del recurso. Por ejemplo, el URI puede incluir phones/item, donde /item es un parámetro de ruta que identifica el elemento de la colección del recurso /phones. Dado que los parámetros de ruta forman parte de la URI, son esenciales para identificar la solicitud.

Consideremos ahora la API de la tienda telefónica en línea. Un cliente desea obtener información sobre un teléfono {phone-id} cuyo código de producto es 412456. El URI de este recurso podría tener el siguiente aspecto:/phones/412456

Nota: Como práctica recomendada, adopte las siguientes convenciones cuando especifique un parámetro de ruta en el URI del recurso.

• Añada una variable de parámetro de ruta entre corchetes rizados {} .
• Especifique una variable de parámetro de ruta tal que coincida exactamente con el parámetro de ruta definido a nivel de recurso.

Tipos de datos de parámetros

Cuando se añade un parámetro a la API, se especifica el tipo de datos del parámetro. El tipo de datos determina qué tipo de información puede contener el parámetro.

webMethods API Gateway admite los siguientes tipos de datos para los parámetros:

Códigos de estado compatibles HTTP

Una respuesta de la API devuelve un código de estado HTTP que indica el éxito o el fracaso de la operación solicitada.

Puede especificar códigos HTTP para cada método para ayudar a los clientes a entender la respuesta. Mientras que las respuestas pueden contener un código de error en XML u otro formato, los clientes pueden entender rápidamente y con mayor facilidad un código de estado de respuesta HTTP. Los clientes suelen entender los códigos de estado que define la especificación HTTP.

webMethods API Gateway incluye un conjunto de tipos de contenido predefinidos que se clasifican en las siguientes categorías taxonómicas.

HTTP/1.1 define todos los códigos de estado legales. Examine estos códigos para determinar cuáles son apropiados para su API.

Consideremos ahora la API de la tienda telefónica en línea. En la tabla siguiente se describen los códigos de estado HTTP a los que responde cada una de las combinaciones de URI y métodos HTTP.

Solicitudes y respuestas de ejemplo

Para ilustrar el uso de una API, se proporciona un ejemplo de mensajes de solicitud y respuesta. Considere el ejemplo de la API phonestore que mantiene una base de datos de teléfonos de diferentes marcas. La API phonestore puede ofrecer los siguientes ejemplos para ilustrar su uso:

Ejemplo 1 - Recuperar una lista de teléfonos

Solicitud de cliente

GET /phones HTTP/1.1
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
Host: www.api.phonestore.com
Accept-Language: en-us
Accept-Encoding: text/xml
Connection: Keep-Alive

Respuesta del servidor

HTTP/1.1 200 OK
Date: Mon, 29 August 11:53:27 GMT
Server: Apache/2.2.14 (Win32)
Last-Modified: Mon, 18 July 2016 09:18:16 GMT
Content-Length: 356
Content-Type: text/xml
<phones>
	<phone>
		<name>Asha</name>
		<brand>Nokia</brand>
		<price currency="irs">11499</price>
		<features>
			<camera>
				<back>3</back>
			</camera>
			<memory>
				<storage scale="gb">8</storage>
				<ram scale="gb">1</ram>
			</memory>
			<network>
				<gsm>850/900/1800/1900 MHz</gsm>
			</network>
		</features>
	</phone>
	<phone>
		<name>Nexus7</name>
		<brand>Google</brand>
		<price currency="irs">16499</price>
		<features>
			<camera>
				<front>1.3</front>
				<back>5</back>
			</camera>
			<memory>
				<storage scale="gb">16</storage>
				<ram scale="gb">2</ram>
			</memory>
			<network>
				<gsm>850/900/1800/1900 MHz</gsm>
				<HSPA>850/900/1900 MHz</HSPA>
			</network>
		</features>
	</phone>
</phones>

Solicitud de cliente

GET /phones/phone-4156 HTTP/1.1
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
Host: www.api.phonestore.com
Accept-Language: en-us
Accept-Encoding: text/xml
Connection: Keep-Alive

Respuesta del servidor

POST /phones/phone HTTP/1.1
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
Host: www.api.phonestore.com
Accept-Language: en-us
Accept-Encoding: text/xml
Content-Length: 156
Connection: Keep-Alive
<phones>
	<phone>
		<name>iPhone5</name>
		<brand>Apple</brand>
		<price currency="irs">24500</price>
		<features>
			<camera>
				<front>1.2</front>
				<back>8</back>
			</camera>
			<memory>
				<storage scale="gb">32</storage>
				<ram scale="gb">2</ram>
			</memory>
			<network>
				<gsm>850/900/1800/1900 MHz</gsm>
				<HSPA>850/900/1900 MHz</HSPA>
			</network>
		</features>
	<phone>
</phones>

Ejemplo 3 - Crear un teléfono

POST /phones/phone HTTP/1.1
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
Host: www.api.phonestore.com
Accept-Language: en-us
Accept-Encoding: text/xml
Content-Length: 156
Connection: Keep-Alive
<phones>
	<phone>
		<name>iPhone5</name>
		<brand>Apple</brand>
		<price currency="irs">24500</price>
		<features>
			<camera>
				<front>1.2</front>
				<back>8</back>
			</camera>
			<memory>
				<storage scale="gb">32</storage>
				<ram scale="gb">2</ram>
			</memory>
			<network>
				<gsm>850/900/1800/1900 MHz</gsm>
				<HSPA>850/900/1900 MHz</HSPA>
			</network>
		</features>
	<phone>
</phones>

Respuesta del servidor

HTTP/1.1 200 OK
Date: Mon, 29 August 11:53:27 GMT
Server: Apache/2.2.14 (Win32)
Last-Modified: Wed, 18 June 2014 09:18:16 GMT
Content-Type: text/xml
Content-Length: 15
<id>2122</id>