1.- ¿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.

2.- ¿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.

3.- ¿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 que 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 utilizara 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.

4.- ¿Cómo usarla?

A pesar de haber indicado en la segunda sección de esta expliación, sobre que la información de la API se procesa desde Core/App/AppAPI.php, su punto de entrada es api.php.

En este caso concreto, el ejemplo de URL de acceso será el de mi entorno de desarrollo:
http://localhost/~shawe/FS2018/api.php


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 Postman 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 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 és el punto de inicio en el que la API empieza a ofrecer datos a utilizar.
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 la base.
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.
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 parametros &limit=50&offset=0.
Hay que tener esto en cuenta, porqué 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 que elemento queremos seguir recibiendo datos, en ese ejemplo, seguiremos a partir del 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
image

Paginar 3 elementos desde offset 3
image

4.4.- Realizar una busqueda

4.4.1.- Filtrado por descripcion
Obtener todos los registros que en descripcion contengan PESOS:
image

4.4.2.- Filtrado por descripcion y codiso
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:
image

4.6.- Obtener un recurso concreto
Mediante el parametro code, obtenemos el elemento concreto. Hay que recorder que este parametro está asociado a la clave primaria de cada modelo, y por tanto, es diferente para cada recurso.
image

4.7.- 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.


¿No encuentra lo que busca?




Soporte:

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

  Soporte

¿Desea ser distribuidor?

Si desa ser distribuidor oficial de FacturaScripts, comience hoy mismo el proceso.

  hágase partner

Redes sociales:

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





© 2013-2017 FacturaScripts