https://wiki.archlinux.org/api.php?action=feedcontributions&user=Pikhyle&feedformat=atomArchWiki - User contributions [en]2024-03-29T00:13:05ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=Aurweb_RPC_interface&diff=551853Aurweb RPC interface2018-10-28T22:36:23Z<p>Pikhyle: Edited for spelling and grammar corrections.</p>
<hr />
<div>[[Category:Package management]]<br />
[[Category:Arch projects]]<br />
[[ja:AurJson]]<br />
[[pt:Aurweb RPC interface]]<br />
{{Related articles start}}<br />
{{Related|Official repositories web interface}}<br />
{{Related articles end}}<br />
The [https://aur.archlinux.org/rpc.php Aurweb RPC interface] is a lightweight [[Wikipedia:Remote procedure call|RPC]] interface for the [[AUR]]. Queries are sent as HTTP GET requests and the server responds with [http://www.json.org/ JSON].<br />
{{Note|This article describes v5 of the RPC Interface API, as updated with AUR v4.7.0 on July 7, 2018.}}<br />
<br />
== API usage ==<br />
<br />
=== Query types ===<br />
<br />
There are two query types: <br />
<br />
* search<br />
* info<br />
<br />
==== search ====<br />
<br />
Package searches can be performed by issuing requests of the form:<br />
<br />
/rpc/?v=5&type=search&by=''field''&arg=''keywords''<br />
<br />
where {{ic|''keywords''}} is the search argument and {{ic|''field''}} is one of the following values:<br />
<br />
* {{ic|name}} (search by package name only)<br />
* {{ic|name-desc}} (search by package name and description)<br />
* {{ic|maintainer}} (search by package maintainer)<br />
* {{ic|depends}} (search for packages that depend on keywords)<br />
* {{ic|makedepends}} (search for packages that makedepend on keywords)<br />
* {{ic|optdepends}} (search for packages that optdepend on keywords)<br />
* {{ic|checkdepends}} (search for packages that checkdepend on keywords)<br />
<br />
The {{ic|by}} parameter can be skipped and defaults to {{ic|name-desc}}.<br />
Possible return types are {{ic|search}} and {{ic|error}}.<br />
<br />
If a maintainer search is performed and the search argument is left empty, a list of orphan packages is returned.<br />
<br />
Examples:<br />
<br />
Search for {{ic|foobar}}:<br />
<nowiki>https://aur.archlinux.org/rpc/?v=5&type=search&arg=foobar</nowiki><br />
<br />
Search for packages maintained by {{ic|john}}:<br />
<nowiki>https://aur.archlinux.org/rpc/?v=5&type=search&by=maintainer&arg=john</nowiki><br />
<br />
Search for packages that have {{ic|foobar}} as `makedepends`:<br />
<nowiki>https://aur.archlinux.org/rpc/?v=5&type=search&by=makedepends&arg=foobar</nowiki><br />
<br />
Search with callback:<br />
<nowiki>https://aur.archlinux.org/rpc/?v=5&type=search&arg=foobar&callback=jsonp1192244621103</nowiki><br />
<br />
==== info ====<br />
<br />
Package information can be performed by issuing requests of the form:<br />
<br />
/rpc/?v=5&type=info&arg[]=''pkg1''&arg[]=''pkg2''&…<br />
<br />
where {{ic|''pkg1''}}, {{ic|''pkg2''}}, … are the exact matches of names of packages to retrieve package details for.<br />
<br />
Possible return types are {{ic|multiinfo}} and {{ic|error}}.<br />
<br />
Examples:<br />
<br />
Info for single {{ic|foobar}} package:<br />
<nowiki>https://aur.archlinux.org/rpc/?v=5&type=info&arg[]=foobar</nowiki><br />
<br />
Info for multiple {{ic|foobar}} and {{ic|bar}} packages:<br />
<nowiki>https://aur.archlinux.org/rpc/?v=5&type=info&arg[]=foo&arg[]=bar</nowiki><br />
<br />
=== Return types ===<br />
<br />
The return payload is of one format and currently has three main types. The response will always return a type so that the user can determine if the result of an operation was an error or not.<br />
<br />
The format of the return payload is:<br />
{"version":5,"type":''ReturnType'',"resultcount":0,"results":''ReturnData''}<br />
<br />
{{ic|''ReturnType''}} is a string, and the value is one of: <br />
<br />
* {{ic|search}}<br />
* {{ic|multiinfo}}<br />
* {{ic|error}}<br />
<br />
The type of {{ic|''ReturnData''}} is an array of dictionary objects for the {{ic|search}} and {{ic|multiinfo}} {{ic|''ReturnType''}}, and an empty array for {{ic|error}} {{ic|''ReturnType''}}.<br />
<br />
==== error ====<br />
The error type has an error response string as the return value. An error response can be returned from either a {{ic|search}} or an {{ic|info}} query type.<br />
<br />
Example of {{ic|''ReturnType''}} {{ic|error}}:<br />
{"version":5,"type":"error","resultcount":0,"results":[],"error":"Incorrect by field specified."}<br />
<br />
==== search ====<br />
The search type is the result returned from a search request operation. '''The actual results of a search operation will be the same as an info request for each result. See the info section.'''<br />
<br />
Example of {{ic|''ReturnType''}} {{ic|search}}:<br />
{"version":5,"type":"search","resultcount":2,"results":[{"ID":206807,"Name":"cower-git", ...}]}<br />
<br />
==== info ====<br />
The info type is the result returned from an info request operation.<br />
<br />
Example of {{ic|''ReturnType''}} {{ic|multiinfo}}:<br />
<nowiki><br />
{<br />
"version":5,<br />
"type":"multiinfo",<br />
"resultcount":1,<br />
"results":[{<br />
"ID":229417,<br />
"Name":"cower",<br />
"PackageBaseID":44921,<br />
"PackageBase":"cower",<br />
"Version":"14-2",<br />
"Description":"A simple AUR agent with a pretentious name",<br />
"URL":"http:\/\/github.com\/falconindy\/cower",<br />
"NumVotes":590,<br />
"Popularity":24.595536,<br />
"OutOfDate":null,<br />
"Maintainer":"falconindy",<br />
"FirstSubmitted":1293676237,<br />
"LastModified":1441804093,<br />
"URLPath":"\/cgit\/aur.git\/snapshot\/cower.tar.gz",<br />
"Depends":[<br />
"curl",<br />
"openssl",<br />
"pacman",<br />
"yajl"<br />
],<br />
"MakeDepends":[<br />
"perl"<br />
],<br />
"License":[<br />
"MIT"<br />
],<br />
"Keywords":[]<br />
}]<br />
}<br />
</nowiki><br />
<br />
=== jsonp ===<br />
<br />
If you are working with a javascript page, and need a JSON callback mechanism, you can do it.<br />
You just need to provide an additional callback variable. This callback is usually handled via the javascript library, but here is an example.<br />
<br />
Example Query:<br />
<nowiki>https://aur.archlinux.org/rpc/?v=5&type=search&arg=foobar&callback=jsonp1192244621103</nowiki><br />
<br />
Example Result:<br />
/**/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"}]})<br />
<br />
This would automatically call the JavaScript function {{Ic|jsonp1192244621103}} with the parameter set to the results of the RPC call.<br />
<br />
== Limitations ==<br />
<br />
* HTTP GET requests are limited to URI of 8190 bytes maximum length. However, the official AUR instance running on a nginx server with HTTP/2 uses the [https://nginx.org/en/docs/http/ngx_http_v2_module.html#http2_max_field_size default URI maximum length] limit of 4443 bytes. Info requests with more than about 200 packages as an argument will need to be split.<br />
* The API rate is limited to a maximum of 4000 requests per day per IP.<br />
<br />
== Reference clients ==<br />
<br />
Sometimes things are easier to understand with examples. A few reference implementations (jQuery, python, ruby) are available at the following URL: https://github.com/cactus/random/tree/2b72a1723bfc8ae64eed6a3c40cb154accae3974/aurjson_examples<br />
<br />
== Associated code ==<br />
<br />
* {{AUR|python3-aur}}: Python modules for interacting with the remote AUR RPC interface, among other AUR services. See [http://xyne.archlinux.ca/projects/python3-aur/ python3-aur] for details.<br />
* {{AUR|python-aur}}: Python modules for interacting with the remote AUR RPC interface (RPCv1).</div>Pikhyle