Implantación de una API personalizada para un servicio REST de fachada

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

Se recomienda empezar a crear una capa de API de fachada entre los servicios de backend externos y la interfaz de usuario para reducir el número de llamadas a los servicios de backend siempre que sea posible. Por ejemplo, la aplicación móvil puede ejecutar una sola llamada a la capa de API de fachada que gestiona las llamadas a otros servicios REST y consolida todos los datos entrantes en una sola respuesta a la aplicación móvil.

Crear una API personalizada completa

Para crear una API personalizada completa mediante Oracle Mobile Hub.

Haga clic en , seleccione Desarrollo y, a continuación, API en el menú lateral. Si ya se ha creado una API (ya sea en estado Borrador o Publicado), verá una lista de API. Si no existen API personalizadas, verá una página con el botón Nueva API. Haga clic en la API que ya ha creado o haga clic en Nueva API para empezar.

Definir puntos finales

Puede crear recursos para definir los puntos finales de la API. Un recurso es el quid de una API. Tiene un tipo, algunos datos asociados, una relación con otros recursos y contiene uno o más métodos que actúan sobre él. 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 información básica.

Cada vez que hace clic en Nuevo recurso, crea 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.

Note:
¿Consulte los iconos de los enlaces Métodos? Cada vez que define un método para un recurso, aparece un icono 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 recurso, que es el URI (relativo al URI base). Por ejemplo, si el URI base es /mobile/custom/audits/, puede agregar el recurso, findings, que es /mobile/custom/audits/findings.
Proporcione el nombre mostrado, que es un nombre para el recurso que facilita su identificación en la documentación de API.
Los recursos se muestran por sus nombres mostrados en la parte izquierda de la página API Test.
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 que especifique 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 inmediatamente 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 el desorden para localizar un recurso más rápidamente cambiando al modo compacto (está a la derecha de Nuevo recurso). La pantalla compacta oculta la descripción del recurso, el tipo de recurso y la ruta.

Adición de métodos a los recursos

Los métodos son acciones que se pueden realizar en un recurso. La página Methods muestra un método a la 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 sus detalles.

Para agregar algunos métodos al recurso, haga clic en Métodos.

Si el recurso para el que está definiendo métodos tiene parámetros de ruta, se muestran encima de Agregar método.
1. (Opcional) Haga clic en Necesario si desea que los parámetros de 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 solo una vez por recurso (por ejemplo, no puede definir dos métodos DELETE para un único recurso). En la parte superior de la página se muestra un icono para cada método definido. 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 los rasgos que desee aplicar al método.

Si no tiene ningún rasgo de recurso definido, haga clic en Puntos Finales para volver a la página principal Recursos y haga clic en el enlace Rasgos para definir uno. Los rasgos 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.

Definición de una Solicitud de Método

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

Haga clic en Solicitar 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, puede 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 múltiplos del parámetro actual.
5. Haga clic en Agregar Parámetro para agregar otro parámetro de nivel superior para el método.
En función del método seleccionado, haga clic en Agregar tipo de medio y defina el cuerpo del método. El cuerpo contiene los datos que está enviando al servidor. Por ejemplo, si está definiendo un método POST, deberá definir el artículo que está creando, como una nueva lista de clientes o una solicitud de servicio. Si está definiendo un método GET, no necesita enviar un cuerpo de método, por lo que no necesita 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.
  Según el tipo (por ejemplo, no introduciría un esquema para un tipo de imagen), tiene la opción de agregar un esquema, un ejemplo o ambos.
  Al definir un esquema, agregue solo los datos necesarios para el objetivo del recurso. Es decir, no agregue datos innecesarios que solo ralentizarán la transmisión y potencialmente aumentarán el potencial de 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 la implantación ficticia utiliza como respuesta ficticia para el método. El uso de datos ficticios puede ayudarle a verificar el comportamiento de sus métodos. En el ejemplo se muestran valores ficticios para los datos que se envían en el cuerpo del mensaje, como 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 Agregar tipo de medio para agregar tipos de medio adicional. Si decide que no desea el método, haga clic en la X en el banner para suprimirlo.

Definir una respuesta para el método

Dependiendo de la solicitud, es posible que necesite o no una respuesta. Una respuesta describe el proceso para devolver resultados del servicio. Es posible que desee definir una respuesta que verifique que se han devuelto los datos solicitados o que desee una respuesta que confirme si se ha recibido o no la solicitud. Definir una respuesta es similar a definir una solicitud. La principal diferencia es que tendrás que seleccionar un código de estado para hacerte 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.
Por defecto, se proporciona un código de estado 200, pero si ese no es el código que desea, seleccione uno de la lista desplegable.
- 2xx indica que la conexión se ha realizado correctamente.
- 3xx indica que se ha producido una redirección.
- 4xx indica que se ha producido un error de usuario.
- 5xx indica que se ha producido un error del servidor.
Para ayudar a quien utilice la API a comprender 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 de error.
Proporcione una descripción de lo que designa el código.
Haga clic en Agregar cabecera, seleccione una cabecera o una 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 y seleccione el formato de la respuesta. Según el tipo de medio que seleccione, puede agregar parámetros, esquemas o ejemplos como lo hizo para el cuerpo de la solicitud.
1. En 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.
  Al igual que con el cuerpo de la solicitud, agregue solo 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 probarlos 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 seleccione un tipo de valor. También puede asignar un nombre al parámetro.
4. Para el tipo de medio basado en imágenes (por ejemplo, image/png), no tiene que hacer nada 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 201 que indica que se ha creado correctamente un nuevo recurso. En el ejemplo también se muestra un formato de respuesta de devolución de 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 la 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 allí, puede ir a otra página del diseñador de API para crear una raíz, tipos de recursos o rasgos, o agregar documentación de API.

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

Creación de una API de conector REST

Utilice el asistente de 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 un nombre para la API de conector y una URL al servicio externo.

A partir de 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 está accediendo.
Pruebe la conexión y los resultados de las llamadas realizadas a la conexión.

Debe crear una API e implantación personalizadas para permitir que las aplicaciones llamen a las API de conector y generen 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, implantar el código personalizado.

Configuración de un conector básico

Puede crear un conector en funcionamiento completando las dos primeras páginas del asistente de API del conector REST.

Haga clic en , 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 REST proporcionando lo siguiente:
1. Nombre mostrado de API: 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 debajo del 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 Create.
En la página General del cuadro de diálogo API del conector REST, defina los valores de timeout:
- Timeout de lectura HTTP: tiempo máximo (en milisegundos) que se puede dedicar a esperar para leer los datos. Si no proporciona un valor, se aplica el valor por defecto de 20 segundos.
- Timeout de conexión HTTP: tiempo (en milisegundos) empleado en conectarse a la URL remota. Un valor de 0 ms significa que se permite un timeout infinito.
  
  Los valores de timeout de HTTP deben ser menores que la política Network_HttpRequestTimeout, que tiene un valor por defecto de 40 000 ms.
  
  Note:
  Si tiene un rol de administrador de nube móvil además del rol de desarrollador de servicios, 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, solicite los valores al administrador de la nube móvil.
Haga clic en Descriptor e introduzca la información de conexión para el servicio.

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

Note:
Solo se admiten los puertos de acceso a Internet estándar 80 y 443. No se puede realizar la conexión a 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 aún más el conector de las siguientes maneras:

(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.
Definición de reglas.
Definir Políticas de Seguridad.

Para asegurarse de que la configuración de la API de conector es válida, debe probarla a fondo (no solo desde la página Connector API Test) antes de publicarla. Es decir, también debe probar la API personalizada (con su implantación) que utiliza esta API de conector. Básicamente, si está listo para publicar la API de conector, también debe estar listo para publicar la API personalizada que la 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 los recursos del servicio, las llamadas a una ruta de proxy específica y las llamadas a determinados tipos de operaciones (verbos). Esto ayuda a aplicar una sintaxis coherente de la cadena de URL, evita que el desarrollador de código personalizado tenga que insertar estos valores y permite realizar un seguimiento de las diferentes llamadas mediante análisis.

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

Si no se aplica ninguna regla, todas las llamadas se transfieren a través del proxy al servicio existente.

Si el conector aún no está abierto, haga clic en , seleccione Desarrollo y, a continuación, API en el menú lateral.
Seleccione la API de conector que desea editar y haga clic en Open.
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 consulta o cabecera y su valor.

Note:

Aunque puede definir reglas para definir determinadas cabeceras por defecto, las reglas no se aplican si el cliente que llamó al conector directamente a través de 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 una regla del conector REST. 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 una regla del conector REST.

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 es más fácil de solucionar.
Amplíe Recursos y edite la URL remota para proporcionar un recurso a la regla que se va a aplicar. El valor de URL base 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 se apliquen solo 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.

Note:

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

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
Métodos HTTP GET y PUT

La descripción de la regla sería la siguiente:

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

Si no se crea ninguna regla, la descripción sería la siguiente:

Para ALL METHODS to 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. Usando 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

Configuración de 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. La selección de 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 debe 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 cumplir sus requisitos.

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

Si el conector aún no está abierto, haga clic en , seleccione Desarrollo y, a continuación, API en el menú lateral.
Seleccione la API de conector que desea editar y haga clic en Open.
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 procede, a la política seleccionada si no desea utilizar los valores por defecto.
Para sustituir una propiedad, introduzca o seleccione un valor que no sea el predeterminado.
Haga clic en Guardar para guardar su trabajo o en Guardar y cerrar para guardar su trabajo y salir del asistente de API del conector REST.
Haga clic en Siguiente (>) para ir al paso siguiente.