xcontracts

1.0.x
(0 reviews)
Esta API permite tanto obtener información de todos los contratos asociados a un usuario, como acceder a la información concreta de uno de ellos, y la opción de poder revocarlos.

xcontracts

Gestión eXtendida de contratos de APIS

Descripción general del API

Esta API permite tanto obtener información de todos los contratos asociados a un usuario, como acceder a la información concreta de uno de ellos, y la posibilidad de poder revocar todos los contratos asociados a un usuario.

Detalles del API:

Uso general del API

Los distintos endpoints del API se basan en que necesitan le uso de códigos para manipular la información. Esos códigos pueden ser gestionados por el usuario del API (los almacena como parte de algún tipo de perfil asociado al usuario) o los obtiene mediante la llamada de búsqueda de información.

Nota: Los ejemplos no incluyen cabeceras mostrando la validación. Esto es así ya que el API puede llevar diferentes sistemas de validación de acceso que pueden variar entre versiones.

El primer paso es identificar el usuario sobre el que realizar el resto de operaciones.

Actualmente existen varios usuarios que comparten ID de usuario en Anypoint y se proporciona endpoint que informará los usuarios asociados a un mismo identificador.

curl "https://api1.correos.es/support/xcontracts/api/v1/user?username=E099999"

[
  {
    "id": "7a22db45-675c-1033-8b62-94723df09e30",
    "firstName": "Pedro",
    "lastName": "Martin Sanz",
    "email": "prueba@gmail.com",
    "enable": "true",
    "createdAt": "2024-01-11T12:26:15.906Z",
    "updatedAt": "2024-02-12T16:20:22.907Z",
    "identityProvider": "CorreosOkta"
  }
]

A continuación ya podremos buscar los contratos asociados a un usuario concreto utilizando el id obtenido en esta llamada, que se corresponde con el Identificador único del usuario.

Hay que tener en cuenta que se pueden obtener diversos usuarios, deberá identificar la entrada que le interese (p.e. en función del valor del atributoidentityProvider) para quedarse con el id que utilizará en las siguientes llamadas.

Las búsquedas se limitarán a una unidad organizativa (por nombre), a un entorno (por nombre) y solo a aquellas APIs públicas cuya instancia tenga una etiqueta (tag) concreta. El tag será un valor de configuración en el ConfigMap de este API aunque tiene el valor predefinido de xcontracts.

En el siguiente ejemplo, se buscan los contratos asociados a un usuario:

curl "https://api1.correos.es/support/xcontracts/api/v1/contracts?userId=7a22db45-675c-1033-8b62-94723df09e30&organization=Support&environment=Desarrollo"

[
  {
    "id": 5447538,
    "organization": {
      "id": "cd214526-1edc-461f-be1d-4efafb8444ca",
      "name": "Support"
    },
    "environment": {
      "id": "d109cc53-7241-46b8-aeb4-8a0b5bcda5f4",
      "name": "Desarrollo"
    },
    "apiInstance": {
      "id": 19261729,
      "intanceLabel": "int"
    },
    "status": "APPROVED",
    "application": {
      "id": "2070931",
      "name": "helloworld"
    },
    "tier": {
      "id": "2070120",
      "name": "default"
    }
  }
]

Con el identificador de usuario (id) y con los valores obtenidos en esta llamada se dispondrán de todos los identificadores necesarios para realizar el resto de llamadas de este API.

Por ejemplo revocarlo:

curl "https://api1.correos.es/support/xcontracts/api/v1/contract/revoke?organizationId=cd214526-1edc-461f-be1d-4efafb8444ca&environmentId=d109cc53-7241-46b8-aeb4-8a0b5bcda5f4&apiInstanceId=19253372&contractId=5447538" \
  -X PATCH

Operaciones en lote

Para revocar contratos existen dos formas:

  1. Obtener la información de usuario como se ha expuesto anteriormente o,
  2. Revocar todos los contratos de un usuario en una única llamada (operación en lote)

Revocar todos los contratos en una única llamada se puede hacer mediante la operación:

curl "https://api1.correos.es/support/xcontracts/api/v1/contracts/revoke?userId=53e8d4c4-e490-4f11-8fc5-ff06d542c40e&organization=Support&environment=Desarrollo" \
  -X PATCH

Contempla la posibilidad que al revocar los contratos algunos puedan fallar, devolviendo así un mensaje en el que el usuario verá cuales no han conseguido revocarse. En ese caso el valor de retorno devuelto es 207.

Descripción de implementación

EL API invoca a servicios REST de Anypoint para gestionar los elementos que expone (contratos).

  ┌──────────────────────┐         ┌──────────────────────┐       ┌──────────────────────┐
  │                      │         │                      │       │                      │
  │                      │         │                      │       │                      │
  │   User application   ├────────►│     xcontracts       ├──────►│   Anypoint System    │
  │                      │         │                      │       │       APIS           │
  │                      │◄────────┤                      │◄──────┤                      │
  └──────────────────────┘         └──────────────────────┘       └──────────────────────┘

Nota: Gráfico realizado con https://asciiflow.com

Para acceder a las APIS de sistema de MuleSoft/Anypoint se necesitan credenciales de acceso que se configuran en el servicio xcontracts (configuración k8).

No se recomienda hacer llamadas masivas a este servicio (por ejemplo pruebas de rendimiento) ni escalar múltiple PODs para no generar excesivas llamadas a los servicios públicos de AnyPoint.

El código fuente se puede localizar en Git

La identificación frente a las APIs de Anypoint se realiza mediante una Connected App llamada xcontracts. Las credenciales de esta Connected APP se configuran el el ConfigMap del API.

https://anypoint.mulesoft.com/accounts/connectedApps

Aspectos generales de las APIs de Correos

Nota: Se incluyen ejemplos ilustrativos usando curl. Esto no significa que esté obligado a usar curl, cualquier cliente que pueda realizar peticiones HTTP serviría.

Solicitud de acceso al API

Desde el propio Exchange, o el portal de acceso a las APIs que se esté usando, existirá una opción de Solicitar acceso. Si no ve esa opción quiere decir que esa API no admite solicitudes de acceso.

Antes de que a una aplicación cliente se le permita consumir una API se debe solicitar acceso a la API. Una vez solicitado el acceso, la petición pasa por un flujo de aprobación. Una vez finalizado ese flujo, y aprobado por el propietario del API, recibirá un email con las credenciales de acceso (si estuviesen definidas).

Niveles de uso

Los APIS pueden tener definidos diferentes niveles de uso. Al solicitar acceso a un API verá indicaciones del nivel de uso (SLA) que ofrece el API. Tenga en cuenta que algunos niveles de uso pueden tener un coste asociado.

Para conocer los niveles de uso que aplican a su API puede revisar la Descripción general del API

Políticas de seguridad

Existen varias políticas de seguridad que puede aplicarse a las APIS. Un API ofrecido por Correos puede llevar ninguna, una o varias de estas políticas.

Para conocer las políticas de seguridad que aplican a su API puede revisar la Descripción general del API

Sin política de seguridad

Un API puede haber sido definido para que no requiera autorización (APIs de uso interno o de uso abierto) por lo que no hay necesidade de incluir ningún aspecto adicional en las llamadas al API.

curl "http://example.restapi.es/myResource"

Client ID Enforcement

Política de aplicación de ID de cliente: El API espera unas cabeceras con pareja clave / valor en sus peticiones.

Antes de que a una aplicación cliente se le permita consumir una API protegida esta política, se debe solicitar acceso a la API. Después de que exista un contrato aprobado entre la aplicación cliente y la API, cada solicitud debe incluir las credenciales de la aplicación cliente de conformidad con la configuración de la política.

Las credenciales irán como cabeceras de la petición tal como muestra el siguiente ejemplo de petición usando curl:

curl "http://example.restapi.es/myResource" -H "client_id:1234" -H "client_secret:abcd"

¿Es posible consultar client_id y client_secret si se me han olvidado o los he perdido?: Desde Exchange, o el portal de acceso a las APIs que se esté usando, puede consultar Mis Aplicaciones y ahí puede encontrar las credenciales de acceso.

Validación JWT

Política de seguridad capaz da validar tanto tokens JWT generados por ISAM como tokens generados por CorreosID (producto de seguridad de Correos).

Todas las llamadas al API deberán incluir el token JWT (Json Web Token) para poder usar el API.

Para realizar la llamada se deberá introducir la cabecera Authorization con el valor Bearer seguido del token.

curl "http://example.restapi.es/myResource" -H "Authorization: Bearer {token}"

¿Cómo obtener el token JWT?: La obtención del token JWT será específico del sistema que lo proporciona (por ejemplo CorreosID) y deberá haber proporcionado documentación al respecto para hacer las llamadas a sus APIs para obtener un token válido. Por favor consulte con su contacto en Correos para obtener documentación relativa a CorreosID.

Introducción uso de API REST

REST APIs utilizan Uniform Resource Identifiers (URI) para direccionar los recursos. Los diseños de URIs bien hechos comunicarían claramente el recurso de la API, como por ejemplo:

http://example.restapi.es/france/paris/louvre/leonardo-da-vinci/mona-lisa

Un diseño incorrecto de los URIs daría un recurso mucho más difícil de entender como:

http://example.restapi.es/68dd0-a9d3-11e0-9f1c-0800200c9a66

Formato de URI

La sintaxis del URI genérico se define como sigue:

URI = scheme "://" authority "/" path [ "?" query ] [ "#" fragment ]

  • scheme: El esquema identifica el protocolo de acceso a los recursos (http, https)
  • authority: Es el elemento jerárquico que identifica la autoridad de nomenclatura, está formado por el nombre de host y el puerto.
  • path: La ruta es la parte más específica del URI que indica la ruta o ubicación del recurso dentro del servidor. El camino puede incluir jerarquías profundas y a menudo refleja la estructura organizativa de los recursos..
  • query: Es un componente opcional que se incluye después de la ruta de acceso y tiene una estructura no jerárquica, y proporciona una cadena de información que el recurso puede utilizar para algún propósito, por ejemplo, para buscar parámetros o datos a procesar. La consulta suele ser una cadena de pares de parámetros y valores ("argumento=valor"). Los argumentos junto con los valores se separan entre sí con un ampersand ("&").
  • fragment: El fragmento es un componente opcional que permite identificar una parte del recurso principal, o la vista de una representación del mismo. El comienzo de este componente se indica con el carácter de libra ("#").

Reviews