## ¡Bienvenido a nuestra API! _Spyro API_ es un API REST que se apoya totalmente en el estándar HTTP. Esto significa que _Spyro API_ está basada en _recursos_ sobre los que pueden efectuarse _operaciones_ para obtener unos _resultados_. Aceptamos [JSON](https://www.json.org) en el cuerpo de sus peticiones y devolvemos respuestas [JSON](https://www.json.org). Utilizamos [verbos](https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html) y [códigos de estado](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) HTTP estándares. En este documento podrás encontrar la descripción de las diferentes operaciones disponibles para cada recurso que _Spyro API_ ofrece.

## Autenticación Algunas operaciones requiren que el usuario esté autenticado. En esos casos, debes proporcionar el token de acceso como cabecera de la petición. ``` -H "Authorization: Bearer TOKEN" ``` Cuando necesites autenticarte, podrás hacerlo [aquí]({urlApiAutenticacion}).

## Listados Cuando las peticiones puedan proporcionar listas de elementos, permitirán indicar criterios de filtrado y ordenación, y además, éstas estarán paginadas:

### Filtrado Para filtrar los resultados, especifique un criterio en el parámetro de consulta `filtros`. Se pueden incluir tantos `Criterios` como sean necesarios, que se concatenarán en el proceso de filtrado mediante la expresión lógica OR: #### Filtros = ``` Criterio ``` o ``` Criterio,Criterio,...,Criterio ``` Cada `Criterios` se compone por uno o más pares de un `Atributo` y una `Comparación`. Todos los pares de un mismo `Criterio` se se concatenarán en el proceso de filtrado mediante la expresión lógica AND : #### Criterio = ``` (Atributo:Comparacion) ``` o ``` (Atributo:Comparacion,Atributo:Comparacion,...,Atributo:Comparacion) ``` El `Atributo` corresponde con el nombre del detalle sobre los que queremos aplicar el filtro. La `Comparación` es el valor por el que queremos filtrar, pudiendo ser este un valor exacto o una condición. #### Comparación = ``` Valor ``` o ``` (Búsqueda,TipoComparación) ``` o ``` (Búsqueda,TipoComparación,Sensibilidad) ``` En el caso de que el valor a comparar sea exacto basta con incluir simplemente el valor. El valor lo incluiremos entre comillas simples si éste es una cadena de texto. Ejemplos de criterio de comparación de valor exacto: ``` (detalle1:'Ad') ``` ``` (detalle1:('Ad',exacto)) ``` Si la comparación no es exacta la estructura de la comparación es la siguiente: El valor de `Búsqueda` permite incluir operadores lógicos directamente junto con el valor, según cómo lo queramos aplicar. Además de permitir incluir una Lista de Valores (x,y,z), intervalos (x..y), excepciones (<>x) o (--x). Los operadores puede ser: * Para detalles de texto: * `%` Este símbolo permite sustituir todos los caracteres (planificación: '%Juan%'). * `_ ` Este símbolo permite sustituir un solo carácter (planificación: 'F_22'). * Para detalles numéricos: * `..` Este símbolo permite indicar un intervalo de valores (planificación: '15..28'). * `>` | `<` Para indicar mayor a o menor a (planificación: '>3'). El `TipoComparación` podrá ser el valor `condicion` (para busquedas de valores no exactos) o el valor `exacto` (para busquedas de valores exactos) Ejemplos de criterio con comparación de valor no exacto: ``` (detalle2:('1..8',condicion)) ``` ``` (detalle3:('23,58,64',condicion)) ``` Los Valores son sensibles a mayúsculas si el contenido es una cadena de texto. Si quisiéramos que lo tuviera en cuenta tendríamos que añadir el texto `sensible`, sino el texto `no_sensible`. Ejemplos de criterio con comparación sensible y no sensible: ``` (detalle1:('Ad',exacto,no_sensible)) ``` ``` (detalle1:('%AN',condicion,sensible)) ```

### Ordenación Para ordenar los resultados, especifique un criterio en el parámetro de consulta `orden`. Se pueden incluir tantos `Criterios` como sean necesarios. #### Orden = ``` Criterio ``` o ``` Criterio,Criterio,...,Criterio ``` Cada `Criterio` es un par de un `Atributo` y una `Dirección`. #### Criterio = ``` Atributo:Direccion ``` El `Atributo` corresponde con el nombre del detalle sobre los que queremos aplicar la ordenación. La `Dirección` puede ser el valor `asc` (para orden ascendente) o `desc` (para orden descendente).

### Paginación Cuando las respuestas sean listas de elementos, éstas vienen paginadas y si no lo indicas, siempre obtendrás la primera página. Además, cada página tendrá tantos elementos como los indicados en el parámetro `elementos`. En caso de no obtener el número de elementos indicado será debido a que has llegado a la última página o que la has superado o que has pedido un número excesivo de elementos.

## Modificación de recursos Cuando quieras modificar un recurso, puedes hacerlo mediante las peticiones `PATCH`. Éstas esperan recibir un documento [JSON Patch](https://tools.ietf.org/html/rfc6902) en su cuerpo, pero unicamente se soportan las operaciones `test` y `replace`.

## Idiomas Aunque el idioma materno de _Spyro API_ es el español, éste soporta otros idiomas. Puedes indicar el idioma en el que quiere obtener una respuesta mediante la cabecera de petición `Accept-Language`.