Aurweb RPC interface (Español)
La interfaz RPC de Aurweb es una interfaz liviana de RPC para AUR. Las consultas se envían como solicitudes GET de HTTP y el servidor responde en formato JSON.
Utilización de la API
Tipos de consulta
Hay dos tipos de consulta:
- search
- info
search
Las búsquedas de paquetes se pueden realizar emitiendo solicitudes con el formulario:
/rpc/?v=5&type=search&by=field&arg=keywords
donde keywords es el argumento de búsqueda y field es uno de los siguientes valores:
-
name(busca solo por nombre de paquete) -
name-desc(busca por nombre y descripción del paquete) -
maintainer(busca por mantenedor de paquetes) -
depends(busca paquetes cuya "depends" dependen de palabras clave) -
makedepends(busca paquetes cuya "makedepends" dependa de palabras clave) -
optdepends(busca paquetes cuya "optdepends" dependa de palabras clave) -
checkdepends(busca paquetes cuya "checkdepends" dependa de palabras clave)
El parámetro by se puede omitir y el valor predeterminado es name-desc.
Los posibles tipos de retorno son search y error.
Si se realiza una búsqueda por mantenedor y el argumento de búsqueda se deja vacío, se devuelve una lista de paquetes huérfanos.
Ejemplos:
Buscar por paquete:
https://aur.archlinux.org/rpc/?v=5&type=search&arg=paquete
Buscar por paquetes mantenidos por usuario:
https://aur.archlinux.org/rpc/?v=5&type=search&by=maintainer&arg=usuario
Buscar por paquetes que tengan paquete como `makedepends`:
https://aur.archlinux.org/rpc/?v=5&type=search&by=makedepends&arg=paquete
Buscar con callback (devolución de llamada):
https://aur.archlinux.org/rpc/?v=5&type=search&arg=paquete&callback=jsonp1192244621103
info
La información del paquete se puede obtener emitiendo solicitudes con el formulario:
/rpc/?v=5&type=info&arg[]=pkg1&arg[]=pkg2&…
donde pkg1, pkg2, … son las coincidencias exactas de los nombres de los paquetes, de los cuales se quieren recuperar los detalles del paquete.
Los posibles tipos de retorno son multiinfo y error.
Ejemplos:
Información para un único paquete:
https://aur.archlinux.org/rpc/?v=5&type=info&arg[]=paquete
Información para varios paquetes:
https://aur.archlinux.org/rpc/?v=5&type=info&arg[]paquete1=&arg[]=paquete2
Tipos de retorno
La carga para la devolución es de un formato único y dispone actualmente de tres tipos principales. La respuesta siempre devolverá un tipo para que el usuario pueda determinar si el resultado de una operación fue un error o no.
El formato para la carga de devolución es:
{"version":5,"type":ReturnType,"resultcount":0,"results":ReturnData}
ReturnType es una cadena y el valor es uno de los siguientes:
searchmultiinfoerror
return data
El tipo de ReturnData es una matriz de elementos de diccionario para search y multiinfo de ReturnType, y una matriz vacía para error de ReturnType.
Para ReturnType search, ReturnData puede contener los siguientes campos:
IDNamePackageBaseIDPackageBaseVersionDescriptionURLNumVotesPopularityOutOfDateMaintainerFirstSubmittedLastModifiedURLPath
Para ReturnType info y multiinfo, ReturnData también puede contener adicionalmente los siguientes campos:
DependsMakeDependsOptDependsCheckDependsConflictsProvidesReplacesGroupsLicenseKeywords
Los campos que no contienen un paquete se omitirán de la salida.
error
El tipo "error" tiene una cadena de respuesta de error como valor de retorno. Se puede devolver una respuesta de error desde un tipo de consulta search o info.
Ejemplo de ReturnType error:
{"version":5,"type":"error","resultcount":0,"results":[],"error":"Incorrect by field specified."}
search
El tipo "search" es el resultado devuelto por una operación de solicitud de búsqueda.
Ejemplo de ReturnType search:
{"version":5,"type":"search","resultcount":2,"results":[{"ID":206807,"Name":"cower-git", ...}]}
info
El tipo "info" es el resultado devuelto por una operación de solicitud de información.
Ejemplo de ReturnType multiinfo:
{
"version":5,
"type":"multiinfo",
"resultcount":1,
"results":[{
"ID":229417,
"Name":"cower",
"PackageBaseID":44921,
"PackageBase":"cower",
"Version":"14-2",
"Description":"A simple AUR agent with a pretentious name",
"URL":"http:\/\/github.com\/falconindy\/cower",
"NumVotes":590,
"Popularity":24.595536,
"OutOfDate":null,
"Maintainer":"falconindy",
"FirstSubmitted":1293676237,
"LastModified":1441804093,
"URLPath":"\/cgit\/aur.git\/snapshot\/cower.tar.gz",
"Depends":[
"curl",
"openssl",
"pacman",
"yajl"
],
"MakeDepends":[
"perl"
],
"License":[
"MIT"
],
"Keywords":[]
}]
}
jsonp
Si está trabajando con una página de JavaScript y necesita un mecanismo de devolución de llamada ("callback") en formato JSON, que puede hacerlo uno mismo. Solo necesitamos proporcionar una variable de "callback" adicional. Esta devolución de llamada generalmente se maneja a través de la biblioteca javascript, he aquí un ejemplo:
Ejemplo de consulta:
https://aur.archlinux.org/rpc/?v=5&type=search&arg=foobar&callback=jsonp1192244621103
Ejemplo de resultado:
/**/jsonp1192244621103({"version":5,"type":"search","resultcount":1,"results":[{"ID":250608,"Name":"foobar2000","PackageBaseID":37068,"PackageBase":"foobar2000","Version":"1.3.9-1","Description":"An advanced freeware audio player (uses Wine).","URL":"http:\/\/www.foobar2000.org\/","NumVotes":39,"Popularity":0.425966,"OutOfDate":null,"Maintainer":"supermario","FirstSubmitted":1273255356,"LastModified":1448326415,"URLPath":"\/cgit\/aur.git\/snapshot\/foobar2000.tar.gz"}]})
Esto llamaría automáticamente a la función de JavaScript jsonp1192244621103 con el parámetro establecido en los resultados de la llamada RPC.
Limitaciones
- Las solicitudes GET de HTTP están limitadas a un URI de 8190 bytes de longitud máxima. Sin embargo, la instancia oficial de AUR que se ejecuta en un servidor nginx con HTTP/2 utiliza el límite de 4443 bytes de longitud máxima de URI predeterminada. Las solicitudes de información con más de 200 paquetes aproximadamente como argumento deberán dividirse.
- Las consultas de búsqueda deben tener al menos dos caracteres de longitud.
- Las búsquedas fallarán si contienen 5000 o más resultados.
- La tasa de API está limitada a un máximo de 4000 solicitudes por IP al día.
Clientes de referencia
A veces las cosas son más fáciles de entender con ejemplos. Algunas implementaciones de referencia (jQuery, python, ruby) están disponibles en la siguiente URL: https://github.com/cactus/random/tree/2b72a1723bfc8ae64eed6a3c40cb154accae3974/aurjson_examples