Implantar una API personalizada para un servicio de REST de fachado

Al desarrollar una aplicación móvil, normalmente comienza con la capa de interfaz de usuario primero y, a continuación, conecta la aplicación con otra aplicación mediante los servicios web de REST. Este enfoque funciona bien para aplicaciones pequeñas o simples. Cuando las aplicaciones son más grandes y desea conectarse con varios servicios de backend, puede introducir sin darse cuenta el rendimiento y los problemas de seguridad.

Le recomendamos empezar a crear una capa de API fato entre los servicios externos de backend y la interfaz de usuario para reducir el número de llamadas a los servicios de backend siempre que sea posible. Por ejemplo, su aplicación móvil puede ejecutar una única llamada a la capa de API faU1ade que maneja las llamadas a otros servicios de REST y consolida todos los datos entrantes en una única respuesta a su aplicación móvil.

Creación de una API personalizada completa

Para crear una API personalizada completa mediante Oracle Mobile Hub.

Haga clic en y seleccione Desarrollo y, a continuación, API en el menú lateral. Si una API ya se ha creado (ya se encuentra en estado Provisional o Publicado), verá una lista de API. Si no existe ninguna API personalizada, verá una página con el botón Nueva API. Haga clic en la API que ya ha creado o en Nueva API para comenzar.

Definir Puntos Finales

Puede crear recursos para definir los puntos finales de la API. Un recurso es la crux de una API. Tiene un tipo, algunos datos asociados a él, una relación con otros recursos y contiene uno o más métodos que actúan sobre ellos. Un recurso puede ser casi cualquier cosa: una imagen, un archivo de texto, una recopilación de otros recursos, una transacción lógica, un procedimiento, etc.

Haga clic en el enlace de navegación Puntos Finales para empezar.
Haga clic en Nuevo recurso y agregue alguna información básica.

Cada vez que haga clic en Nuevo Recurso , cree un recurso de nivel superior (raíz). Si desea agregar un recurso secundario (anidado), haga clic en Agregar ( + ) junto al recurso de nivel superior. Haga clic en X para suprimir un recurso.

Nota:
¿ Desea consultar los iconos en los enlaces Métodos ? Cada vez que define un método para un recurso, aparece un icono para él en el enlace Métodos. Utilícelos como accesos directos para ver qué métodos ya se han definido para un recurso. Haga clic en un icono para ir directamente a su definición en la página Métodos.
Proporcione la ruta de acceso del recurso, que es el URI (relativo al URI base). Por ejemplo, si el URI base es /mobile/custom/audits/, puede agregar el recurso, findings, es /mobile/custom/audits/findings.
Proporcione el nombre mostrado, que es un nombre para el recurso que facilita la identificación en la documentación de API.
Los recursos se muestran por sus nombres mostrados en la parte izquierda de la página Prueba de API.
Proporcione una breve descripción del recurso.

Después de introducir una descripción, el URI se muestra debajo del campo de descripción.
(Opcional) Proporcione un tipo de recurso RAML, que es el tipo de recurso (resourcesType:). No es necesario especificar un tipo de recurso. Si desea utilizar un tipo de recurso pero no tiene uno definido, haga clic en el enlace Tipos y defina uno.

Al crear un método para un recurso, aparece un símbolo para ese método debajo del enlace Métodos. Puede ver de inmediato qué métodos se definen para un recurso si necesita examinar una definición de recurso. Haga clic en un icono para ir directamente a esa definición de método.

Puede borrar la orden para localizar un recurso más rápidamente cambiando al modo Compacta (está a la derecha del nuevo recurso ). El despliegue compacto oculta la descripción, el tipo de recurso y la ruta del recurso.

Agregar métodos a los recursos

Los métodos son acciones que se pueden realizar en un recurso. La página Métodos muestra un método cada vez. Después de definir al menos dos métodos, puede hacer clic en el icono de un método en la parte superior de la página para ver los detalles.

Agregue algunos métodos al recurso haciendo clic en Métodos .

Si el recurso para el que está definiendo métodos tiene parámetros de ruta de acceso, se muestran arriba de Agregar Método .
1. (Opcional) Haga clic en Necesario si desea que los parámetros de la ruta se transfieran con cada método.
  Se muestra el nombre del parámetro.
2. Proporcione un nombre mostrado para el parámetro y el código de ejemplo.
3. En la lista desplegable, seleccione el tipo de valor válido para el parámetro.
Haga clic en Agregar Método y seleccione el método que desee.

Después de seleccionar un método, ya no aparece en la lista de métodos porque utiliza un método sólo una vez por recurso (por ejemplo, no puede definir dos métodos DELETE para un solo recurso). Se muestra un icono para cada método definido en la parte superior de la página. Haga clic en un icono de método para ir directamente a su definición.
(Opcional) Introduzca una breve descripción del método en el campo Descripción.
(Opcional) Introduzca un nombre mostrado para el método.
(Opcional) Proporcione cualquier formación que aplicar al método.

Si no tiene ninguna formación de recursos definida, haga clic en Puntos Finales para volver a la página principal Recursos y haga clic en el enlace Formas para definir una. Las formaciones le permiten definir una recopilación de operaciones similares.

Después de definir métodos para el recurso, puede definir las solicitudes y respuestas para esos métodos.

Definir una solicitud para el método

Ahora que ha seleccionado un método, defina la solicitud a la que está realizando el servicio al que desea conectarse. Por ejemplo, si ha seleccionado un método POST, ahora puede definir lo que desea crear. Para ello, agregue parámetros y un cuerpo de solicitud, que contenga la descripción de los datos que desea enviar al servicio.

Haga clic en Solicitud para definir una solicitud.
Haga clic en Agregar parámetro y seleccione un tipo de parámetro: Consulta o Cabecera . Seleccione Necesario si el parámetro es necesario para el método.
1. Asigne al parámetro un nombre y un nombre mostrado.
2. Seleccione un tipo de valor válido: Cadena , Número , Entero , Fecha o Booleano .
3. (Opcional) Proporcione una descripción del parámetro y un ejemplo que pueda utilizar al probar la validez del punto final. Por ejemplo, podría tener un recurso, audits, y agregar un parámetro de consulta, auditorID, que toma un valor numérico y otro parámetro, auditName, que toma un valor de cadena:
```
/audits: 
  get: 
    description: | 
      Gets list of audits, organizations etc.     
    queryParameters: 
      auditorID:  
        id: Auditor ID
        description: | 
          display auditor identifier 
        type: integer 
        example: |
          1234
        required: false      
      auditName:
        displayName: auditName
        description: |
          Audit name
        example: "Payroll Process Audit"
```
  En este ejemplo, se define un método GET con los parámetros de consulta, auditorID y auditName.
4. (Opcional) Haga clic en Más Propiedades para agregar propiedades anidadas al parámetro. Haga clic en Repetir para agregar varios elementos del parámetro actual.
5. Haga clic en Agregar Parámetro para agregar otro parámetro de nivel superior para el método.
Según el método seleccionado, haga clic en Agregar Tipo de Medio Físico y defina el cuerpo del método. El cuerpo contiene los datos que envía al servidor. Por ejemplo, si está definiendo un método POST, deberá definir el elemento que está creando, como una nueva lista de clientes o solicitud de servicio. Si está definiendo un método GET, no necesita enviar un cuerpo del método para que no tenga que especificar un tipo de medio.
1. Seleccione el tipo de medio para el cuerpo del método, que es el formato del mensaje que está enviando, como texto, imágenes o formularios web.
  En función del tipo (por ejemplo, no se introduce un esquema para un tipo de imagen), tiene la opción de agregar un esquema, un ejemplo o ambos.
  Al definir un esquema, agregue sólo los datos necesarios para el recurso. Es decir, no agregue datos innecesarios que sólo ralentizarán la transmisión y aumentarán la posibilidad de que se produzcan errores.
2. (Opcional) Haga clic en Esquema e introduzca un esquema (en formato JSON) en el panel del editor. Un esquema es como una plantilla para el cuerpo. Es lo que se utiliza para definir el contenido del mensaje.
3. (Opcional) Haga clic en Ejemplo e introduzca un ejemplo (en formato JSON) en el panel del editor, que utiliza la implantación ficticia como respuesta ficticia del método. El uso de datos ficticios puede ayudarle a verificar el comportamiento de los métodos. El ejemplo muestra valores ficticios para los datos que se envían en el cuerpo del mensaje según se define en el método POST del recurso audits:
```
body: 
  application/json: 
    example: | 
      { 
        "Title": "Leaking Water Heater",
        "Username": "joh1017",  
        "imageLink": "storage/collections/2e029813-d1a9-4957-a69a-fbd0d7431d77/objects/6cdaa3a8-097e-49f7-9bd2-88966c45668f?user=lynn1014", 
        "Notes": "my water heater is broken"
      }                               
```
Haga clic en Add Media Type (Agregar tipo de medio) para agregar tipos de medios adicionales. Si decide que no desea utilizar el método, haga clic en X en el banner para suprimirlo.

Definir una respuesta para el método

En función de la solicitud, puede que necesite o no una respuesta. Una respuesta describe el proceso para devolver resultados del servicio. Puede que desee definir una respuesta que compruebe que se han devuelto los datos solicitados o que desee una respuesta que confirme si se ha recibido la solicitud. La definición de una respuesta es similar a la definición de una solicitud. La principal diferencia es que tendrá que seleccionar un código de estado para poder saber el resultado de la conexión.

Haga clic en Respuesta para definir una o más respuestas.
Haga clic en Agregar respuesta y seleccione el código de estado que desea devolver.
El código de estado 200 se proporciona por defecto, pero si no es el código que desea, seleccione uno de la lista desplegable.
- 2 xx indica que la conexión es correcta.
- 3 xx indica que se ha producido un redireccionamiento.
- 4 xx indica que se ha producido un error de usuario.
- 5 xx indica que se ha producido un error del servidor.
Para ayudar a que el usuario pueda utilizar la API para conocer el motivo de un posible error en la API que está configurando, utilice un código de estado HTTP para devolver el código que mejor coincida con la situación del error.
Proporcione una descripción de lo que designa el código.
Haga clic en Agregar Cabecera , seleccione una cabecera o consulta de respuesta, proporcione el nombre de la cabecera o consulta y un nombre mostrado para la cabecera, así como el tipo de valor válido para la cabecera.
Haga clic en Agregar Tipo de Medio Físico y seleccione el formato de la respuesta. Según el tipo de medio que seleccione, puede agregar parámetros, esquemas o ejemplos de la misma forma que para el cuerpo de la solicitud.
1. Para el tipo de medio basado en texto (por ejemplo, application/json o text/xml), haga clic en Esquema para introducir un esquema (en formato JSON) para el cuerpo.
  Como con el cuerpo de la solicitud, agregue sólo los datos pertinentes al cuerpo de la respuesta. No incluya más datos de los que realmente necesita para la operación.
2. Haga clic en Ejemplo para agregar datos ficticios (en formato JSON) para el cuerpo de la respuesta. Utilice datos ficticios para verificar el comportamiento de los métodos antes de realizar pruebas con datos reales.
3. Para el tipo de medio basado en pantalla (por ejemplo, multipart/form-data), haga clic en Agregar Parámetro y seleccione Necesario si el parámetro es obligatorio. A continuación, proporcione un nombre y un tipo de valor. Opcionalmente, puede asignar un nombre al parámetro.
4. Para el tipo de medio basado en imágenes (por ejemplo, image/png), no tiene que realizar ninguna acción porque no hay esquemas ni atributos que proporcionar.

El siguiente ejemplo muestra que se ha creado una respuesta para el método POST del recurso audits con un código de estado de 201 que indica que un nuevo recurso se ha creado correctamente. El ejemplo también muestra un formato de respuesta de retorno application/json, una cabecera Location que se ha agregado y el cuerpo del mensaje que contiene datos ficticios:

responses: 
  201: 
    description: | 
      The request has been fulfilled and resulted in a new resource 
      being created. The newly created resource can be referenced  
      by the URI(s)returned in the entity of the response, with the 
      most specific URI for the resource given by a Location header
      field.  

    headers:
      Location:
        displayName: Location
        description: |
          Identifies the location of the newly created resource.

        type: string
        example: |
          /20934

        required: true

    body: 
      application/json: 
        example: | 
          {
            "id": 20934,
            "title": "Lynn's Leaking Water Heater",
            "contact": {
               "name": "Lynn Adams",                 
               "street": "45 O'Connor Street",
               "city": "Ottawa", 
               "postalcode": "a1a1a1",
               "username": "johnbeta"
              },
           "status": "New",
           "driveTime": 30,
           "priority": "high",
           "notes": "My notes",
           "createdon": "2014-01-20 23:15:03 EDT",
           "imageLink": "storage/collections/2e029813-d1a9-4957-a69a-fbd0d74331d77/objects/6cdaa3a8-097e-49f7--9bd2-88966c45668f?user=lynn1014"
          }

Al definir su respuesta, puede decidir probar los puntos finales o hacer clic en Puntos Finales en la barra de navegación para volver a la página principal Recursos. Desde ahí, puede continuar con otra página del diseñador de API para crear una raíz, tipos de recursos o rasgos, o bien agregar documentación de API.

Si decide que no desea utilizar el método, haga clic en X en el banner para suprimirlo.

Crear una API de conector de REST

Utilice el asistente de la API de conector de REST para crear, configurar y probar la API de conector.

Para obtener una API de conector de trabajo básica, puede proporcionar el nombre de la API de conector y una URL al servicio externo.

Desde ahí, puede:

Defina reglas para formar solicitudes o respuestas específicas para los datos a los que desea acceder.
Configure las políticas de seguridad del cliente para el servicio al que accede.
Pruebe la conexión y pruebe los resultados de las llamadas realizadas a la conexión.

Debe crear una API personalizada y una implantación para permitir que sus aplicaciones llamen a las API del conector y generar la API y la implantación automáticamente. Si desea hacerlo manualmente, debe crear una API personalizada con los recursos adecuados y, a continuación, implementar el código personalizado.

Configuración de un conector básico

Puede crear un conector en funcionamiento. Para ello, complete las dos primeras páginas del asistente de la API de REST Connector.

Haga clic en y seleccione Desarrollo y, a continuación, API en el menú lateral.
Haga clic en REST (si se trata de la primera API de conector que se va a crear) o en Nuevo conector y en la lista desplegable, seleccione REST .
Identifique la nueva API de conector de REST proporcionando lo siguiente:
1. Nombre mostrado de API: el nombre tal y como aparecerá en la lista de API de conector.
2. Nombre de API: nombre único de la API de conector.
  
  Por defecto, este nombre se agrega al URI base relativo como nombre de recurso para la API de conector. Puede ver el URI base bajo el campo Nombre de API .
  
  Además de una nueva versión de esta API de conector, ninguna otra API de conector puede tener el mismo nombre de recurso.
3. Descripción Breve: Esta descripción se mostrará en la página Conectores cuando se seleccione esta API.
Haga clic en Crear .
En la página General del recuadro de diálogo API de REST Connector, defina los valores de timeout:
- Timeout de Lectura de HTTP: tiempo máximo (en milisegundos) que se puede tardar en esperar para leer los datos. Si no proporciona un valor, se aplica el valor por defecto de 20 segundos.
- Timeout de Conexión de HTTP: tiempo (en milisegundos) empleado en la conexión a la dirección URL remota. Un valor de 0mms significa que se permite un timeout infinito.
  
  Los valores de timeout de HTTP deben ser inferiores a la política Network_HttpRequestTimeout, que tiene un valor por defecto de 40,000 ms.
  
  Nota:
  Si tiene un rol de administrador de nube móvil además del rol de desarrollador de servicio, puede abrir el archivo policies.properties para ver el valor de las políticas de red para el entorno actual desde la vista de administrador. De lo contrario, pida al administrador de dispositivos móviles en la nube los valores.
Haga clic en Descriptor e introduzca la información de conexión para el servicio.

Si proporciona una URL de descriptor Swagger, se identifican y se muestran los recursos disponibles, y puede seleccionar los que desee.

Nota:
Solo se admiten los puertos de acceso a Internet estándar 80 y 443. No se puede establecer la conexión con un servicio mediante un puerto personalizado.
Haga clic en Guardar.
(Opcional) Haga clic en Probar , seleccione las credenciales de autenticación y realice llamadas de prueba al servicio.

Desde allí, puede configurar el conector de las siguientes formas:

(Si ha proporcionado un descriptor en la página Descriptor) vaya a la página Recursos y seleccione los métodos para los recursos expuestos.
Defina reglas.
Defina políticas de seguridad.

Para asegurarse de que la configuración de la API de conector es válida, debe probarla detenidamente (no sólo desde la página de prueba de la API del conector) antes de publicarla. Es decir, también debe probar la API personalizada (con su implementación) que utiliza esta API de conector. Básicamente, si está listo para publicar la API del conector, también debe estar listo para publicar la API personalizada que lo llama.

Definir Reglas

Las reglas se definen para definir las interacciones entre la aplicación móvil y un servicio. Las reglas proporcionan una forma de agregar valores de parámetros por defecto para todas las llamadas a recursos en el servicio, llamadas a una ruta de acceso de proxy específica y llamadas para determinados tipos de operaciones (verbos). Esto ayuda a aplicar una sintaxis consistente de la cadena de dirección URL, a ahorrar al desarrollador de código personalizado la necesidad de insertar estos valores y permite realizar un seguimiento de las diferentes llamadas mediante análisis.

Puede crear una o más reglas. Cada regla puede tener uno o más parámetros del tipo Query y Header.

Si no se aplica ninguna regla, todas las llamadas se transfieren mediante el proxy al servicio existente.

Si el conector no está abierto, haga clic en y seleccione Desarrollo y, a continuación, API en el menú lateral.
Seleccione la API de conector que desea editar y haga clic en Abrir .
Seleccione Roles .
Haga clic en Nueva Regla.
Haga clic en Agregar Parámetro y seleccione un tipo de parámetro Consulta o Cabecera e introduzca el nombre de la cabecera o consulta y su valor.

Nota:

Aunque puede definir reglas para definir determinadas cabeceras por defecto, las reglas no se aplican si el cliente que llamó al conector directamente mediante código personalizado o indirectamente, como desde un explorador web o una aplicación móvil, ya ha definido las mismas cabeceras.

En concreto, la definición del formato del cuerpo de la solicitud se suele realizar en el código personalizado con la cabecera Content-Type, no como regla de REST Connector. Del mismo modo, la definición del formato del cuerpo de la respuesta también se realiza en el código personalizado con la cabecera Accept, no como regla de REST Connector.

Puede agregar tantos parámetros a una regla como desee, pero es mejor no sobrecargar una regla con demasiadas operaciones. Una construcción de reglas más sencilla resulta más fácil de solucionar problemas.
Amplíe Recursos y edite la URL remota para proporcionar un recurso para la regla a la que se va a aplicar. El valor de la URL básica es lo que introdujo en el paso de configuración de información básica y no se puede editar.
Seleccione No aplicar a recursos de nivel inferior si desea que las reglas sólo se aplican al nivel de recurso especificado en la URL remota.
(Opcional) Anule la selección de los métodos HTTP que no desea aplicar a las reglas que acaba de definir. De forma predeterminada, todos los métodos están seleccionados.
(Opcional) Haga clic en Nueva regla para crear otra regla.

Nota:

Si define una regla que entra en conflicto con otra regla, la primera regla aplicada tiene prioridad y la regla en conflicto se ignora.

Cuando haya terminado, haga clic en Guardar y, a continuación, en Siguiente ( > ) para ir al siguiente paso en la configuración de la API de conector.

La descripción de la regla que acaba de definir se muestra en el banner Regla justo encima de la sección Parámetros por Defecto . Por ejemplo, supongamos que se han proporcionado los siguientes valores:

URL Remota = https://maps.googleapis.com/maps/api/directions/json?origin=los+angeles&destination=seattle
URI local = myMapAPI
Regla con el siguiente parámetro: Query:key:A3FAEAJ903022
GET y PUT métodos HTTP

La descripción de la regla se leería de la siguiente manera:

Para que GET https://maps.googleapis.com/maps/api/directions/json?origin=los+angeles&destination=seattle esté disponible en myMapAPI/directions, incluya Query:key=A3FAEAJ903022.

Si no se han creado reglas, la descripción sería:

Para TODOS METHODS a https://maps.googleapis.com/maps/api/directions disponible en myMapAPI, No se aplicará ningún parámetro por defecto.

Ahora tiene un URI base que se asigna al servicio existente. Al utilizar nuestro ejemplo:

mobile/connector/myMapAPI/directions/json?origin=los+angeles&destination=seattle se asigna a https://maps.googleapis.com/maps/api/directions/json?origin=los+angeles&destination=seattle

Configurar Políticas de Seguridad y Propiedades de Sustitución

Antes de finalizar la API de conector, debe considerar cómo manejar su seguridad. Puede utilizar políticas de seguridad o cabeceras de autorización. Seleccionar una política de seguridad que describa el esquema de autenticación del servicio al que se está conectando es el enfoque recomendado.

Cada política de seguridad tiene propiedades, denominadas sustituciones, que puede configurar. Un motivo para sustituir una propiedad de configuración de política es limitar el número de políticas que tiene que mantener: en lugar de crear varias políticas con configuraciones ligeramente variadas, puede utilizar la misma política genérica y sustituir valores específicos para satisfacer sus requisitos.

Para seleccionar una política de seguridad y definir las sustituciones de política:

Si el conector no está abierto, haga clic en y seleccione Desarrollo y, a continuación, API en el menú lateral.
Seleccione la API de conector que desea editar y haga clic en Abrir .
Seleccione Seguridad.
Seleccione la política de seguridad de la lista de políticas disponibles y haga clic en la flecha derecha para moverla a la lista Políticas Seleccionadas .
Seleccione solo una política para la API de conector. Se muestra una descripción de una política seleccionada debajo de la lista.
Especifique sustituciones, si es aplicable, para la política seleccionada si no desea utilizar los valores por defecto.
Para reemplazar una propiedad, introduzca o seleccione un valor distinto del predeterminado.
Haga clic en Guardar para guardar su trabajo o en Guardar y cerrar para guardar su trabajo y salir del asistente de REST Connector API.
Haga clic en Siguiente ( > ) para ir al siguiente paso.