¿Qué es la API?

La Interfaz de Programación de Aplicaciones, de sus siglas abreviadas en inglés, es un conjunto de subrutinas, funciones y métodos que ofrece cierta biblioteca para ser utilizado por otro software como una capa de abstracción.

¿Qué ofrece?

La API nos ofrece una forma sencilla de comunicar con los recursos disponibles, mediante unos métodos concretos y simples a los que podemos denominar en su conjunto como CRUD por su acrónimo en inglés:

- POST: Crear (Create) un elemento nuevo.
- GET: Leer (Read) una lista de elementos o un elemento, en listados con paginación, filtros y/o ordenación, o elementos concretos. Este es el método que se utiliza por defecto.
- PUT: Actualizar (Update) un elemento concreto.
- DELETE: Eliminar (Delete) un elemento concreto.

En función del tipo de acción a realizar, se deberá usar el tipo acorde a estos métodos.

Es posible que con el tiempo se añadan más tipos y que esta documentación quede temporalmente desactualizada (no se documenta al mismo ritmo que se añade funcionalidad), para asegurarse puede revisarse en Core/App/AppAPI.php los métodos processResource y processResourceParam.

¿Qué parámetros acepta?

A continuación se listan los parámetros disponibles, y en el punto siguiente se entrará en más detalle como utilizarlo adecuadamente.

- v: Versión de la API de FacturaScripts a utilizar. Desde la versión 2018, solo se soporta la versión 3.
- resource: Se utiliza para indicar que recurso (modelo) se quiere utilizar.
- operation: Se utiliza para indicar qué operación se quiere utilizar a la hora de aplicar un filtro (AND/OR) en una búsqueda. Por defecto es AND.
- filter: Se utiliza para indicar que filtro se quieren aplicar en una búsqueda.
- sort: Se utilizará para indicar que ordenación se quiere aplicar en una búsqueda.
- offset: Se utiliza para indicar a partir de que elemento se quiere recibir el resultado en una búsqueda. Por defecto es 0.
- limit: Se utiliza para indicar la cantidad máxima de elementos a devolver en una búsqueda. Por defecto es 50.
- code: Se utiliza para indicar que registro concreto se quiere obtener. Para cada recurso, el code queda asociado a su clave primaria.

¿Cómo usarla?

En este caso de ejemplo, la URL de acceso será el de mi entorno de desarrollo:
http://localhost:8000/api

Esta URL será un parámetro dentro de tu aplicación, ya que cada cliente tendrá su instalación de FacturaScripts en lugares diferentes.

Para simplificar los ejemplos a continuación, se va a utilizar Insomnia para realizar las consultas contra la API y recibir una respuesta formateada que sea más legible.

4.1.- Autenticación con la API
Todavía en desarrollo

4.2.- Recursos disponibles

4.2.1- Primer contacto con la API
Como se ha indicado en la tercera sección, la versión de la API es uno de los parámetros a indicar, y este en particular es obligatorio. Así que si intentamos acceder a http://localhost:8000/api sin indicar la versión, nos devolverá un error:
image

4.2.2.- Listado de recursos (modelos)
Mientras que si indicamos la versión, nos devolverá un listado de los recursos disponibles. Este es el punto de inicio en el que la API empieza a ofrecer datos a utilizar, y la dirección de consulta sería http://localhost:8000/api/3.
image

Este listado crecerá con el tiempo, a medida que se añaden nuevas funcionalidades a FacturaScripts, ya sea mediante plugins o porqué se ha incluido en el núcleo.
Para que una aplicación que utilice la API sea interesante para cualquier usuario, como mínimo debería tener soporte completo para toda la funcionalidad considera esencial.

4.3.- Obtener un listado de elementos de un recurso
Para tener un ejemplo corto, utilizaremos divisas que tiene pocos atributos, accediendo a localhost:8000/api/3/divisas.
image
Este listado, por defecto viene limitado a 50 elementos y utilizando offset a 0, como se ha indicado en el punto 3. Por tanto, sería equivalente a añadir como parámetros ?limit=50&offset=0.
Hay que tener esto en cuenta, porque puede que para la aplicación sea conveniente leer más o menos registros de golpe, o incluso que sea un valor personalizable por el usuario.

4.3.1.- Obtener un listado de elementos a partir de X posición (paginación)
En el caso de estar paginando resultados, será necesario indicar a partir de qué elemento queremos seguir recibiendo datos, en ese ejemplo, seguiremos a partir del 1 (http://localhost:8000/api/3/divisas?offset=1):
image

4.3.2.- Ejemplo genérico para la paginación:
NOTA: Como el valor de limit indicado por defecto en el código con el tiempo puede cambiar, es más recomendable indicar siempre que cantidad de elementos esperamos recibir.

Partiendo de los parámetros offset y limit, podemos montar la paginación de la forma que sea más conveniente partiendo del siguiente ejemplo:
- Para un limit de 3 (3 elementos por página)
- Página 1: "?offset=0&limit=3": devolverá los elementos 0, 1, 2
Pagina 1 offset=limit*0 (3*0=0)
- Página 2: "?offset=3&limit=3": devolverá los elementos 3, 4, 5
Pagina 2 offset=limit*1 (3*1=3)
- Página 3: "?offset=6&limit=3": devolverá los elementos 6, 7, 8
Pagina 3 offset=limit*2 (3*2=6)

Paginar 3 elementos desde offset 0 (http://localhost:8000/api/3/divisas?offset=0&limit=3)
image

Paginar 3 elementos desde offset 3 (http://localhost:8000/api/3/divisas?offset=3&limit=3)
image

4.4.- Realizar una búsqueda

4.4.1.- Filtrado por descripción
Obtener todos los registros que en descripcion contengan PESOS (http://localhost:8000/api/3/divisas?filter[descripcion]=PESOS):
image

4.4.2.- Filtrado por descripción y codiso (http://localhost:8000/api/3/divisas?filter[descripcion]=PESOS&filter[codiso]=2)
Obtener todos los registros que en descripcion contengan PESOS y en codiso contengan 2:
image

4.5.- Ordenación
Obtener todos los registros que en descripcion contengan PESOS y ordenados por coddivisa de forma descendiente (http://localhost:8000/api/3/divisas?filter[descripcion]=PESOS&sort[coddivisa]=DESC):
image

4.6.- Obtener un recurso concreto
Mediante el parámetro code, obtenemos el elemento concreto. Hay que recordar que este parametro está asociado a la clave primaria de cada modelo, y por tanto, es diferente para cada recurso (http://localhost:8000/api/3/divisas/EUR).
image

4.7.- Añadir un nuevo recurso
Para añadir un nuevo elemento, utilizaremos el método POST sobre la ruta del recurso del modelo, donde para los atributos del modelo en concreto, como mínimo, serán obligatorios todos aquellos que no puedan ser nulos (http://localhost:8000/api/3/divisas).

image

En determinadas situaciones, puede que haya ciertas restricciones adicionales, como que un campo deba tener una longitud mínima/máxima, que sea de tipo booleano o numérico, ... Estas restricciones se añaden desde el método test dentro del modelo concreto, de modo que se obliga a cumplir dichas condiciones para hacer el guardado o inserción del registro. En caso de error, se recibirán los detalles del problema, es el mismo error que puede recibir el usuario, con la diferencia de que

4.8.- Actualizar un recurso existente
Para actualizar un elemento, realizaremos un PUT a la ruta sobre el recurso concreto del modelo, indicando los atributos a actualizar, el resto se utilizarán los originales (http://localhost:8000/api/3/divisas/NEW).

image

Hay que tener en cuenta que las restricciones son las mismas que al añadir un nuevo recurso.

4.9.- Eliminar un recurso concreto:
Tal y como se ha indicado en la segunda sección, se aceptan diferentes métodos. En el caso de querer eliminar un elemento, los parámetros son los mismos que para el punto anterior (obtenerlo), pero cambia el método por DELETE se procederá a eliminarlo (http://localhost:8000/api/3/divisas/NEW).

image


¿No encuentra lo que busca?

Otros idiomas:

Del mismo tema:




Soporte:

FacturaScripts es software libre y gratuito, pero si lo que busca es asesoramiento y soporte profesional, use la sección soporte.

  Soporte

Redes sociales:

Puede encontrarnos en las principales redes sociales. Y también en google+.





© 2013-2017 FacturaScripts