Documentación

Introducción
- Crear una aplicación
- Uso de la API
Autorización
- Obtener autorización
- Solicitar token de acceso
REST API

Introducción

En esta documentación se detalla la API y los pasos requeridos para tener acceso a ella. Lo primero es tener una aplicación registrada para poder generar la autorización hacia el usuario y así obtener el token de acceso a la API. Con esta documentación estás listo para integrar el servicio dentro de tu aplicación de una manera fácil y sencilla.

Crear una aplicación

Para crear una aplicación ve a la sección de mis aplicaciones de OAuth y registra una nueva aplicación.

Una vez creada se mostrarán unas propiedades únicas de la aplicación como client_id y client_secret que son necesarias para hacer las peticiones de autorización, dependiendo del flujo elegido. Para más información, revisa la sección de Autorización.

Uso de la API

Dentro de la API usamos Bearer Token para identificar al usuario autenticado en cada petición. Es necesario enviar el token de acceso a través de la cabecera Authorization siguiendo el formato estándar.

Bearer eyJhbGciOiJIUzI1NiIs...

Todas las rutas descritas en esta documentación están basadas en la siguiente URL.

http://spot.itmarck.com

Autorización

Para obtener acceso el usuario tiene que autenticarse siguiendo el flujo de OAuth: Authorization Code. El servicio expone dos puntos para conectarse, uno para que el usuario autorice la aplicación y otro donde la aplicación solicita el token de acceso.

El flujo descrito está basado en Authorization Code (With PKCE), donde se envia un código de verificación en el endpoint de autorización, pero el servidor también soporta el flujo de Authorization Code. La diferencia está en que será requerido enviar el client_secret al momento de solicitar el token de acceso y el código de verificación queda de manera opcional.

Obtener autorización

La aplicación que solicita el acceso envía al usuario a esta URL para que otorgue los permisos necesarios. El servidor de autorización redirigirá a redirect_uri agregando el código de autorización en la URL como parámetro (code). Luego ese código será usado para solicitar el token de acceso.

GET/oauth/authorize

Parámetros

client_id

string

(query)

Identificador del cliente.

redirect_uri

string

(query)

Opcional. Aquí se enviará el código de autorización.

code_challenge

string

(query)

Código generado por el cliente para asegurar la autenticidad de la autorización.

Respuesta

"https://example.com/?code=1234"

Solicitar token de acceso

Una vez se reciba el código de autorización, es necesario solicitar el token de acceso para poder user la API.

POST/oauth/token

Parámetros

code

string

(body)

Nombre del registro.

client_id

string

(body)

Identificador del cliente.

code_verifier

string

(body)

Código recibido al momento de hacer la autorización. Se espera el mismo valor enviado en code_challenge.

Respuesta

{
  "token_type": "Bearer",
  "access_token": "token"
}

REST API

En esta sección se describe cómo usar la API de REST de Spot.

Obtener usuario autenticado

Enumera la información pública del usuario si la cabecera de autorización es correcta.

GET/api/v1/user

Respuesta

{
  "email": "user@example.com",
  "name": "John Due",
  "avatar": "https://avatar.com"
}

Obtener el registro de un usuario

Muestra el valor de un registro para el usuario autenticado en esa aplicación.

GET/api/v1/user/records/{name}

Respuesta

{
  "name": "theme",
  "value": "light"
}

Establecer el registro de un usuario

Guarda un registro dentro de los registros del usuario autenticado en esa aplicación.

POST/api/v1/user/records/{name}

Parámetros

name

string

(query)

Nombre del registro.

value

any

(body)

Valor del registro.

Respuesta

{
  "name": "theme",
  "value": "dark"
}

Elimina un registro de un usuario

Elimina el registro de la lista de registros del usuario autenticado en esa aplicación.

DELETE/api/v1/user/records/{name}

Parámetros

name

string

(query)

Nombre del registro a eliminar.

Respuesta

{
  "name": "theme"
}