Imprimir

Tutorial: La API De Usuarios

Sincronización de Bases de Datos de Usuarios y Single Sign-On

Si su web tiene su propio sistema de entrada y base de datos con información de usuarios puede utilizar esta API para sincronizarla con la base de datos de usuarios de SuperSaaS. Esto le permite proporcionar a sus usuarios una forma de registrar y entrar una sola vez.

Hay varias opciones para mantener la base de datos de SuperSaaS actualizada utilizando las siguientes llamadas de API. La implementación más sencilla consiste en un solo botón:

  1. Usted crea un solo botón "Reservar Ahora" en su sitio web que contiene toda la información pertinente para la persona que está actualmente entrado en su sitio web
  2. Cuando la persona pulsa el botón su información se envía a la API de SuperSaaS, junto con una suma de comprobación para evitar manipulación
  3. Si esta es la primera vez que se envía a la persona a SuperSaaS se crea una nueva cuenta de usuario con la información suministrada, de lo contrario su información existente se actualiza según sea necesario
  4. La persona quedará automáticamente registrada y redirigida a su horario

Esta forma de trabajar le permite sincronizar sólo el subconjunto de los usuarios que están utilizando SuperSaaS activamente y evita la necesidad de una sincronización completa inicial. En teoría, hay un pequeño riesgo de que las bases de datos se pongan fuera de sincronización si sólo implementa este botón. Esto puede ocurrir si la información del usuario se cambia en su web y el después vuelve a SuperSaaS sin pulsar el botón, por ejemplo porque ha marcado la página. Si esto es un problema, podría implementar las llamadas de API del lado del servidor que se detallan a continuación, para enviar la información actualizada desde su servidor directamente a SuperSaaS cada vez que información de usuarios cambia en su sitio web. Las llamadas de API tienen opciones de hacerlas fallar en silencio en usuarios no existentes para que siga pudiendo mantener sólo el subconjunto de usuarios activos en SuperSaaS.

Una alternativa al procedimiento anterior es hacer una sincronización inicial completa de su base de datos de usuarios (de forma manual o automática), y en cada actualización en su propia base de datos hacer una llamada a la API desde su servidor para mantener SuperSaaS en sincronía. Entonces puede crear un simple enlace para dejar entrar a usuarios automáticamente y redirigirlos a su horario.

También puede hacer que su propia base de datos siga los cambios en SuperSaaS pero en la siguiente discusión se asume que usted desea hacer su propia base de datos la principal y hacer que SuperSaaS la siga. Por lo tanto, quiere evitar que usuarios cambien su información en la base de datos de SuperSaaS. Usted tendrá que realizar los siguientes ajustes:

Crear y Entrar

La forma más fácil de realizar inicio de sesión único (single sign-on) es proporcionar toda la información necesaria cuando envía al usuario a través de su sitio web. SuperSaaS comprobará si el usuario ya existe y actualizará o creará el registro de base de datos, según proceda.

Este es un ilustrativo fragmento de HTML que se pondría en su sitio web para hacerlo funcionar:
<form method="post" action="http://www.supersaas.com/api/users">
	<input type="hidden" name="account" value="Su_nombre_de_cuenta"/>
	<input type="hidden" name="id" value="1234fk"/> <!-- clave única identifica usuario, véase abajo -->
	<input type="hidden" name="user[name]" value="jose@cliente.es"/>     <!-- cadena, debe ser única -->
	<input type="hidden" name="user[phone]" value="123-456-789"/>
	...
	<!-- valores de otros campos, vea la parte inferior de la página para obtener una lista -->
	<!-- puede añadir y borrar campos en la pantalla "Control de Acceso" -->
	...
	<input type="hidden" name="checksum" value="A4E67...DFEF"/>
		<!-- MD5 Hash de 32 dígitos hexadecimal, véase más abajo -->
	<input type="hidden" name="after" value="nombre_de_horario"/>
		<!-- donde enviar su usuario después de entrar -->
	<input type="submit" value="Reservar Ahora"/>
</form>

Para ver este fragmento llenado con valores adecuados para su cuenta véase este ejemplo. Si usted usa Joomla, Drupal o WordPress como CMS se puede descargar un módulo Joomla, módulo Drupal o WordPress plugin.

Tres Opciones para la Clave de la Base de Datos

Para poder hacer un seguimiento de cambios de ambas bases de datos deberán utilizar la misma clave única. Esta ID debe ser enviada con cada transacción para identificar el registro que debe ser modificado. Para facilitar la aplicación fácil tiene tres opciones para elegir:

  1. Puede proporcionar su propio número único de 32 bits. Por lo general la clave de índice de su propia base de datos de usuarios es un buen valor para usar. Usted indica que está proporcionando su propia clave con un sufijo de las letras 'fk' ("foreign key": clave externa) a la ID.
  2. Puede utilizar la ID de usuario interior de SuperSaaS, que es también un número de 32 bits. Cuando crea un nuevo registro tiene que recuperar y almacenar esa ID en su propia base de datos, y posteriormente enviarla al actualizar ese registro.
  3. Puede utilizar como la clave una cadena única de 50 bytes que no empiece por un número, por ejemplo el nombre de la persona. No es una buena idea utilizar como clave algo que el usuario puede cambiar, ya que sería desconectado de sus reservas cada vez que lo cambiara. Si la clave de su propia base de datos no es un número de 32 bits, puede utilizar este campo para almacenarla.

Autenticación con una Suma de Comprobación MD5 Hash

La API es compatible con varios tipos de autenticación. Para comunicación de servidor a servidor puede enviar su nombre de cuenta y contraseña como parámetros de URL, o en un encabezado de autenticación básica HTTP y, opcionalmente, proteger la conexión con SSL. Por supuesto no puede poner su contraseña en código HTML como el fragmento anterior, porque revelaría su contraseña a quien mirara el código fuente de la página. Para autenticar una solicitud de HTML sin necesidad de enviar una contraseña se puede calcular un hash MD5 de varios campos y añadirlo a la solicitud. El hash se calcula a partir de una cadena concatenada que incluye su nombre de cuenta, el nombre de usuario, y la contraseña de su cuenta (no la contraseña del usuario). Ya que incluye la contraseña de cuenta que es sólo conocida por usted y SuperSaaS, no se puede calcular por nadie más. Debido a que la suma de comprobación incluye el nombre del visitante es diferente para cada visitante y la puede poner con seguridad en una llamada AJAX ejecutada por el navegador. La mayoría de lenguajes proporcionan una manera fácil de calcular un hash MD5, por ejemplo:

PHP: $user = 'nombre_usuario@cliente.es';$checksum = md5("Su_nombre_de_cuentaSu_contraseña$user")
Ruby: checksum = Digest::MD5.hexdigest("Su_nombre_de_cuentaSu_contraseña#{'nombre_usuario@cliente.es'}")

Tenga en cuenta que no es necesario proporcionar la contraseña del usuario ya que el formulario ya está autenticado con la suma de comprobación. Puede enviar una contraseña de usuario, pero es mejor no hacerlo, ya que sería visible en el código fuente de la página. Si el registro se ha creado o actualizado con éxito el usuario es redirigido a la dirección que figura en el parametro "after". Puede proporcionar valores adicionales en esta dirección URL para asegurarse de que el usuario termine en una fecha y vista pre-determinada. También puede contener valores precargados para los campos de la reserva, como se explica en el tutorial de integración

Si sólo proporciona el botón de entrada y no más las dos bases de datos pueden acabar fuera de sincronización, lo que le puede parecer aceptable o no. Por ejemplo, una persona puede cambiar su información en su sitio web y volver a SuperSaaS sin pasar por el enlace, por ejemplo usando el historial de su navegador. Además, un usuario que usted borra de su propia base de datos no se borrará de la base de datos de SuperSaaS. Para evitar esto puede actualizar la base de datos de SuperSaaS desde su propio servidor mediante el envío de las llamadas de API detalladas abajo, cada vez que información de usuarios cambie en su servidor.

Sólo Entrar (sin Crear)

Si ya ha conseguido la sincronización de las bases de datos, ya sea manualmente o con la API de llamadas abajo, puede dejar al usuario entrar con el siguiente enlace (POST o GET), utilizando los mismos parámetros que con la llamada anterior:

http://www.supersaas.com/api/login?account=Su_cuenta&after=URL_horario&user[name]=usuario@cliente.es&checksum=A4E...FEF

Crear, Leer, Actualizar, y Borrar Usuarios

La API de la base de datos de Usuarios es RESTful. Puede ser consumida por bibliotecas correctamente escritas, como Active Resource de Ruby on Rails. Para cada llamada se necesita autenticar con el servidor, ya sea agregando su cuenta y contraseña como parámetros de URL o mediante el uso de la autenticación HTTP básica. Por ejemplo: "http://supersaas.com/api/users?account=SuCuenta&password=secreto". También puede utilizar el método de suma de comprobación MD5 descrito anteriormente. Para mayor seguridad se puede utilizar SSL.

Crear un Nuevo Usuario

POST /api/users   (SuperSaaS asignará una clave)
POST /api/users/{id}   (Usted proporciona su propia clave en el formato 9999fk)
La solicitud debe contener ya sea un documento XML que describe al nuevo usuario, o los campos como parámetros codificados para URI. Consulte el final del documento para el formato. Si el registro se crea correctamente la respuesta será un encabezado con código de estado 201 ("Created"). El campo Location del encabezado de la respuesta contendrá la URL que puede utilizar para recuperar el usuario más tarde, por ejemplo:
Location: http://www.supersaas.com/api/users/1234.xml.
Si quieres saber la ID del objeto creado en SuperSaaS (1234) la puede extraer de esta URL. Si el objeto no pasó la validación, tal vez debido a una dirección de correo.e no válida, se devolverá el estado 422 ("Unprocessable Entity"), con los mensajes de error en el cuerpo de la respuesta. Si usted ha proporcionado su propia clave y la clave ya existe en la base de datos, se supone que llamada es una actualización. Para evitar que la Creación se interprete automáticamente como una Actualización puede agregar el parámetro "duplicate=raise" y un código de estado 422 será devuelto.

Leer un Usuario

GET /api/users/{id}
Si la ID es totalmente numérica se supone que es nuestra clave, de lo contrario se considera que es su clave. Si la ID es alfanumérica se almacenará en el campo nombre. IDs alfanuméricas se pueden proporcionar como parámetros codificados para URI para evitar caracteres no válidos en la URL, así: /api/users?id=ab%25cd. La respuesta será un 404 ("Not Found ") o 200 ("OK") con el cuerpo de la respuesta siendo un documento XML que describe al usuario.
<user>
   ...
</user>

Leer Todos los Usuarios

GET /api/users
Esto devuelve un 200 ("OK") con un documento XML que describe todos los usuarios en su cuenta. La cantidad de registros está limitada a 100 a menos que agregue un parámetro "limit" como "/api/users?limit=500".
<users>
   <user>
      ...
   </user>
   <user>
      ...
   </user>
</users>

Actualizar un Usuario

PUT /api/users/{id}
El sistema busca el registro con la ID proporcionada y lo actualiza. Al igual que en la API de "Crear" puede proporcionar un documento XML o parámetros codificados para URI y el resultado será un 200 ("OK") o un 422 con un documento de error. En caso de que el registro no se puede encontrar el sistema asume que usted quiere hacer un Crear. Para evitar la creación automática de un nuevo registro puede agregar el parámetro "notfound=error" o "notfound=ignore" para devolver un 404 ("Not Found") o 200 ("OK"), respectivamente. Si está tratando de utilizar una clave interna de SuperSaaS que no existe siempre se devuelve un 404 ("Not Found"). Si el software que está utilizando no es compatible con el envío del verbo HTTP PUT simplemente puede hacer un POST regular en su lugar.

Borrar un Usuario

DELETE /api/users/{id}
El sistema buscará la ID en la base de datos y devolverá un 200 ("OK") si el registro se ha borrado con éxito, o un 404 ("Not found") si (ya) no existe. Si el software que está utilizando no es compatible con el envío del verbo HTTP DELETE, puede hacer un POST con el parámetro extra "_method=DELETE"

Formato de Datos

Los campos que puede proporcionar se determinan por la configuración en la pantalla Control de Acceso. Excepto por el nombre de usuario todos los valores son opcionales y se establecerán en un valor predeterminado (normalmente blanco) si no previstos.

CampoComentario
nameObligatorioEl nombre del usuario, max 50 bytes. Si ha optado por utilizar las direcciones de correo.e como nombres de usuario, esto tiene que ser una dirección de correo.e.
emailOpcionalLa dirección de correo.e del usuario. Ignorado utiliza la direccion de correo.e como nombre de usuario.
passwordOpcionalContraseña del usuario, so está utilizando entrada con contraseña
full-name, address, mobile, phoneOpcionalSi cualquiera de estos atributos están presentes, se almacenan sin cambios como cadenas codificadas en UTF-8
countryOpcionalO bien no presente o un código de país de dos caracteres ISO 3166-1
field-1, field-2,
super-field
OpcionalLos valores de los dos campos personalizados y el campo de supervisor, independientemente de las etiquetas que les haya dado en la interfaz de usuario.
creditOpcionalEstablece el nivel de crédito (por defecto es 0). El formato se selecciona en la pantalla Configuración de Pagos.
roleOpcionalLos valores permitidos son 3: Usuario normal (defecto), 4: Superusuario o -1: Usuario bloqueado

Al leer los datos el documento XML recuperado contendrá los siguientes campos además de los mencionados anteriormente:
CampoComentario
idLa ID interna asignada a este usuario por SuperSaaS
fkLa ID asignada a este usuario por usted si ha suministrado una clave externa
created-onLa hora que se ha creado este usuario en UTC

Uso Ilustrativo

Este ejemplo de llamada utilizando XML creará un registro de un nuevo usuario en la base de datos de usuarios de SuperSaaS. El registro tiene la clave de base de datos 567 en su propia base de datos:

POST /api/users/567fk.xml
¿Usted enviaría su nombre de cuenta y contraseña en el encabezado con autenticación básica HTTP y el siguiente cuerpo:
<?xml version="1.0" encoding="UTF-8"?>
<user>
  <password>SecretoDelUsuario</password>
  <full-name>Nombre Completo</full-name>
  <name>usuario@ejemplo.es</name>
</user>

Esto devolvería una respuesta 201 ("Created") con un cuerpo vacío. Si en cambio utiliza parámetros de consulta, sustituya guiones con rayitas de subrayado en los campos y escríbalos como user[campo]. Tiene que codificar para URI los valores.

Ejemplo de código para la misma llamada, esta vez con parámetros de consulta:

POST /api/users/567fk?account=demo&password=secreto&user[name]=usuario@ejemplo.es& user[password]=SecretoDelUsuario&user[full_name]=Nombre%20Completo

Sugerencias para Solucionar Problemas


Volver a Índice de tutoriales