Implantar una API personalizada para un servicio REST adecuado

Al desarrollar una aplicación móvil, normalmente se empieza por la capa de la interfaz de usuario en primer lugar y, a continuación, se 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 backend, puede presentar problemas de rendimiento y seguridad involuntariamente.

Le recomendamos empezar a crear una capa API ficticia entre los servicios backend externos y la interfaz de usuario para reducir el número de llamadas a los servicios backend siempre que sea posible. Por ejemplo, la aplicación móvil puede ejecutar una única llamada a la capa API predeterminada que maneja las llamadas a otros servicios de REST y consolida todos los datos entrantes en una única respuesta a la 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

Cree recursos para definir los puntos finales de la API. Un recurso es la cruz 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 en él. Un recurso puede ser casi cualquier: una imagen, un archivo de texto, una recopilación de otros recursos, una transacción lógica, un procedimiento, etcétera.

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, creará 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 ver 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 métodos abreviados 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 la URI (relativa a la 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 la identificación en la documentación de la 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 Descripción.
(Opcional) Proporcione un tipo de recurso RAML, que es el tipo de recurso (resourcesType:). No necesita 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.

Cuando crea un método para un recurso, aparece un símbolo para ese método debajo del enlace Métodos. Puede ver de inmediato los métodos definidos para un recurso si necesita examinar una definición de recurso. Haga clic en un icono para ir directamente a la definición de ese método.

Puede borrar la confusión para localizar un recurso de forma más rápida cambiando al modo compacto (se encuentra a la derecha de Nuevo recurso ). La visualización compacta oculta la descripción del recurso, el tipo de recurso y la ruta.

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 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.

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

Si el recurso que está definiendo métodos para tiene parámetros de ruta de acceso, se muestran sobre 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 se muestra 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 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 rasgo 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 Traits para definir uno. Le permite definir una recopilación de operaciones similares.

Después de definir los 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 los parámetros y un cuerpo de la solicitud, que contiene 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 un nombre al parámetro 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 puede 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 varios 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 Add Media Type (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 para que no sea necesario especificar un tipo de medio.
1. Seleccione el tipo de medio para el cuerpo del método, es decir, el formato del mensaje que está enviando, por ejemplo, texto, imágenes o formularios web.
  En función del tipo (por ejemplo, no se puede introducir 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 sólo 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 de 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 utilizará la implantación de ficticio como respuesta ficticia para el método. El uso de datos de ficticio puede ayudarle a verificar el comportamiento de los métodos. En el ejemplo se muestran valores de ficticio 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 Agregar Tipo de Medio Físico para agregar tipos de medio adicionales. Si decide que no desea 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 verifique que se han devuelto los datos solicitados o puede que desee una respuesta que confirme si se ha recibido o no la solicitud. La definición de una respuesta es similar a la definición de una solicitud. La principal diferencia es que necesitará seleccionar un código de estado para que sepa 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 que se devuelva.
Por defecto, se proporciona un código de estado de 200, pero si ese no es el código que desea, seleccione uno de la lista desplegable.
- 2 xx indica que la conexión se ha realizado correctamente.
- 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 la API utilice la API para conocer el motivo de un error potencial 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 las designaciones de código.
Haga clic en Agregar Cabecera, seleccione una cabecera de respuesta o Consulta, 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 Add Media Type (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. 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.
  Al igual que 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 los datos de mock 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 Add Parameter (Agregar parámetro) y seleccione Required (Necesario) si el parámetro es obligatorio. A continuación, proporcione un nombre y seleccione un tipo de valor. Puede asignar a su parámetro un nombre.
4. Para el tipo de medio basado en imagen (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 correctamente una respuesta para el método POST del recurso audits con el código de estado 201 que indica que se ha creado un nuevo recurso. El ejemplo también muestra un formato de respuesta de retorno application/json, una cabecera Location agregada y el cuerpo del mensaje que contiene los datos de 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 allí, 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 no desea que el método, haga clic en X en el banner para suprimirlo.

Crear una API de conector de 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 tan solo un nombre para la API de conector y una URL al servicio externo.

Desde allí puede:

Defina reglas para formar solicitudes o respuestas específicas de los datos a los que desea acceder.
Configure 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 e implantación para permitir que las aplicaciones llamen a las API del 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

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

Haga clic en y seleccione Desarrollo y, a continuación, API en el menú lateral.
Haga clic en REST (si ésta es 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 que aparecerá en la lista de API del conector.
2. Nombre de API: nombre único de la API de conector.
  
  Por defecto, este nombre se agrega al URI base relativo como el nombre de recurso para la API del 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 Crear.
En la página General del cuadro de diálogo API de conector de REST, defina los valores de timeout:
- Timeout de Lectura 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 HTTP: tiempo (en milisegundos) empleado en conectarse a la URL remota. Un valor 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 Mobile Cloud 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 a su administrador de Mobile Cloud que indique los valores.
Haga clic en Descriptor e introduzca la información de conexión del servicio.

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

Nota:
Sólo se admiten los puertos de acceso estándar de Internet 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 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.
Defina reglas.
Defina políticas de seguridad.

Para asegurarse de que la configuración de la API del conector es válida, debe probarla en profundidad (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 implantación) que utiliza esta API de conector. En esencia, si está listo para publicar la API de conector, también debería estar listo para publicar la API personalizada que la llama.

Definir Reglas

Puede definir reglas 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 del servicio, llamadas a una ruta de acceso de proxy específica y llamadas a determinados tipos de operaciones (verbos). Esto ayuda a aplicar una sintaxis coherente de la cadena de URL, guardar al desarrollador de código personalizado de tener que insertar estos valores y hacer que sea posible realizar un seguimiento de las diferentes llamadas a través de análisis.

Puede crear una o más 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 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 consulta o cabecera y su valor.

Nota:

Aunque puede definir reglas para definir determinadas cabeceras por defecto, las reglas no se aplican si el cliente que llama 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 una regla de conector REST. Del mismo modo, definir el formato del cuerpo de la respuesta también se realiza en el código personalizado con la cabecera Accept, no como una regla de conector REST.

Puede agregar tantos parámetros a la 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 problemas.
Amplíe Recursos y edite la URL remota para proporcionar un recurso para la regla que se va a aplicar. El valor de URL base es lo que ha introducido 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 sólo 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 se ignora la regla en conflicto.

Cuando haya terminado, haga clic en Guardar y, a continuación, haga clic en Siguiente ( > ) para ir al siguiente paso de la configuración de la API del 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 proporcionaron 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 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 crearon reglas, la descripción se leería:

Para que ALL METHODS https://maps.googleapis.com/maps/api/directions esté disponible en myMapAPI, no se aplicará ningún parámetro por defecto.

Ahora tiene un URI base que se asigna al servicio existente. Con 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 gestionar 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, llamadas 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 distintas, 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 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 su API de conector. Aparece una descripción de la 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 reemplazar 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 de conector de REST.
Haga clic en Siguiente ( > ) para ir al siguiente paso.