Difference between revisions of "Aurweb RPC interface"

From ArchWiki
Jump to navigation Jump to search
m (Added move/rename template)
m (add ES interlanguage link)
 
(21 intermediate revisions by 8 users not shown)
Line 1: Line 1:
 
[[Category:Package management]]
 
[[Category:Package management]]
 
[[Category:Arch projects]]
 
[[Category:Arch projects]]
 +
[[es:Aurweb RPC interface]]
 
[[ja:AurJson]]
 
[[ja:AurJson]]
[[pt:AurJson]]
+
[[pt:Aurweb RPC interface]]
 
{{Related articles start}}
 
{{Related articles start}}
 
{{Related|Official repositories web interface}}
 
{{Related|Official repositories web interface}}
 
{{Related articles end}}
 
{{Related articles end}}
{{Move|Aurweb RPC Interface|Use the [https://aur.archlinux.org/rpc.php official name] or an alternative shorter version (f.e. 'AUR RPC')}}
+
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].
The [https://aur.archlinux.org/rpc.php AurJson] interface is a lightweight [[w:Remote procedure call|RPC]] interface for the [[AUR]]. It utilizes HTTP GET queries as the request format, and [http://www.json.org/ JSON] as the response data exchange format.
+
{{Note|This article describes v5 of the RPC Interface API, as updated with AUR v4.7.0 on July 7, 2018.}}
{{Note|This article describes v5 of the RPC Interface API, as released with AUR v4.2.0 on February 15, 2016.}}
 
  
 
== API usage ==
 
== API usage ==
Line 30: Line 30:
 
* {{ic|name-desc}} (search by package name and description)
 
* {{ic|name-desc}} (search by package name and description)
 
* {{ic|maintainer}} (search by package maintainer)
 
* {{ic|maintainer}} (search by package maintainer)
 +
* {{ic|depends}} (search for packages that depend on keywords)
 +
* {{ic|makedepends}} (search for packages that makedepend on keywords)
 +
* {{ic|optdepends}} (search for packages that optdepend on keywords)
 +
* {{ic|checkdepends}} (search for packages that checkdepend on keywords)
  
 
The {{ic|by}} parameter can be skipped and defaults to {{ic|name-desc}}.
 
The {{ic|by}} parameter can be skipped and defaults to {{ic|name-desc}}.
Line 43: Line 47:
 
Search for packages maintained by {{ic|john}}:
 
Search for packages maintained by {{ic|john}}:
 
  <nowiki>https://aur.archlinux.org/rpc/?v=5&type=search&by=maintainer&arg=john</nowiki>
 
  <nowiki>https://aur.archlinux.org/rpc/?v=5&type=search&by=maintainer&arg=john</nowiki>
 +
 +
Search for packages that have {{ic|foobar}} as `makedepends`:
 +
<nowiki>https://aur.archlinux.org/rpc/?v=5&type=search&by=makedepends&arg=foobar</nowiki>
  
 
Search with callback:
 
Search with callback:
Line 63: Line 70:
  
 
Info for multiple {{ic|foobar}} and {{ic|bar}} packages:
 
Info for multiple {{ic|foobar}} and {{ic|bar}} packages:
  <nowiki>https://aur.archlinux.org/rpc/?v=5&type=info&arg[]=foo&arg[]=bar</nowiki>
+
  <nowiki>https://aur.archlinux.org/rpc/?v=5&type=info&arg[]=foobar&arg[]=bar</nowiki>
  
 
=== Return types ===
 
=== Return types ===
  
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.
+
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.
  
 
The format of the return payload is:
 
The format of the return payload is:
Line 77: Line 84:
 
* {{ic|multiinfo}}
 
* {{ic|multiinfo}}
 
* {{ic|error}}
 
* {{ic|error}}
 +
 +
==== return data ====
  
 
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''}}.
 
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''}}.
 +
 +
For the {{ic|''ReturnType''}} {{ic|''search''}}, {{ic|''ReturnData''}} may contain the following fields:
 +
 +
* {{ic|ID}}
 +
* {{ic|Name}}
 +
* {{ic|PackageBaseID}}
 +
* {{ic|PackageBase}}
 +
* {{ic|Version}}
 +
* {{ic|Description}}
 +
* {{ic|URL}}
 +
* {{ic|NumVotes}}
 +
* {{ic|Popularity}}
 +
* {{ic|OutOfDate}}
 +
* {{ic|Maintainer}}
 +
* {{ic|FirstSubmitted}}
 +
* {{ic|LastModified}}
 +
* {{ic|URLPath}}
 +
 +
For the {{ic|''ReturnType''}} {{ic|''info''}} and {{ic|''multiinfo''}}, {{ic|''ReturnData''}} may additionally contain the following fields:
 +
 +
* {{ic|Depends}}
 +
* {{ic|MakeDepends}}
 +
* {{ic|OptDepends}}
 +
* {{ic|CheckDepends}}
 +
* {{ic|Conflicts}}
 +
* {{ic|Provides}}
 +
* {{ic|Replaces}}
 +
* {{ic|Groups}}
 +
* {{ic|License}}
 +
* {{ic|Keywords}}
 +
 +
Fields that a package does not contain will be omitted from the output.
  
 
==== error ====
 
==== error ====
Line 87: Line 128:
  
 
==== search ====
 
==== search ====
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.'''
+
The search type is the result returned from a search request operation.
  
 
Example of {{ic|''ReturnType''}} {{ic|search}}:
 
Example of {{ic|''ReturnType''}} {{ic|search}}:
Line 135: Line 176:
 
=== jsonp ===
 
=== jsonp ===
  
If you are working with a javascript page, and need a json callback mechanism, you can do it.
+
If you are working with a javascript page, and need a JSON callback mechanism, you can do it.
 
You just need to provide an additional callback variable. This callback is usually handled via the javascript library, but here is an example.
 
You just need to provide an additional callback variable. This callback is usually handled via the javascript library, but here is an example.
  
Line 146: Line 187:
 
This would automatically call the JavaScript function {{Ic|jsonp1192244621103}} with the parameter set to the results of the RPC call.
 
This would automatically call the JavaScript function {{Ic|jsonp1192244621103}} with the parameter set to the results of the RPC call.
  
== Reference clients ==
+
== Limitations ==
  
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
+
* 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.
 +
* Search queries must be at least two characters long.
 +
* Searches will fail if they contain 5000 or more results.
 +
* The API rate is limited to a maximum of 4000 requests per day per IP.
  
== Associated code ==
+
== Reference clients ==
  
* The {{AUR|python3-aur}} package provides [[python]] modules for interacting with the remote AUR JSON interface, among other AUR services. See [http://xyne.archlinux.ca/projects/python3-aur/ python3-aur] for details.
+
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

Latest revision as of 09:26, 22 November 2019

The Aurweb RPC interface is a lightweight RPC interface for the AUR. Queries are sent as HTTP GET requests and the server responds with JSON.

Note: This article describes v5 of the RPC Interface API, as updated with AUR v4.7.0 on July 7, 2018.

API usage

Query types

There are two query types:

  • search
  • info

search

Package searches can be performed by issuing requests of the form:

/rpc/?v=5&type=search&by=field&arg=keywords

where keywords is the search argument and field is one of the following values:

  • name (search by package name only)
  • name-desc (search by package name and description)
  • maintainer (search by package maintainer)
  • depends (search for packages that depend on keywords)
  • makedepends (search for packages that makedepend on keywords)
  • optdepends (search for packages that optdepend on keywords)
  • checkdepends (search for packages that checkdepend on keywords)

The by parameter can be skipped and defaults to name-desc. Possible return types are search and error.

If a maintainer search is performed and the search argument is left empty, a list of orphan packages is returned.

Examples:

Search for foobar:

https://aur.archlinux.org/rpc/?v=5&type=search&arg=foobar

Search for packages maintained by john:

https://aur.archlinux.org/rpc/?v=5&type=search&by=maintainer&arg=john

Search for packages that have foobar as `makedepends`:

https://aur.archlinux.org/rpc/?v=5&type=search&by=makedepends&arg=foobar

Search with callback:

https://aur.archlinux.org/rpc/?v=5&type=search&arg=foobar&callback=jsonp1192244621103

info

Package information can be performed by issuing requests of the form:

/rpc/?v=5&type=info&arg[]=pkg1&arg[]=pkg2&…

where pkg1, pkg2, … are the exact matches of names of packages to retrieve package details for.

Possible return types are multiinfo and error.

Examples:

Info for single foobar package:

https://aur.archlinux.org/rpc/?v=5&type=info&arg[]=foobar

Info for multiple foobar and bar packages:

https://aur.archlinux.org/rpc/?v=5&type=info&arg[]=foobar&arg[]=bar

Return types

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.

The format of the return payload is:

{"version":5,"type":ReturnType,"resultcount":0,"results":ReturnData}

ReturnType is a string, and the value is one of:

  • search
  • multiinfo
  • error

return data

The type of ReturnData is an array of dictionary objects for the search and multiinfo ReturnType, and an empty array for error ReturnType.

For the ReturnType search, ReturnData may contain the following fields:

  • ID
  • Name
  • PackageBaseID
  • PackageBase
  • Version
  • Description
  • URL
  • NumVotes
  • Popularity
  • OutOfDate
  • Maintainer
  • FirstSubmitted
  • LastModified
  • URLPath

For the ReturnType info and multiinfo, ReturnData may additionally contain the following fields:

  • Depends
  • MakeDepends
  • OptDepends
  • CheckDepends
  • Conflicts
  • Provides
  • Replaces
  • Groups
  • License
  • Keywords

Fields that a package does not contain will be omitted from the output.

error

The error type has an error response string as the return value. An error response can be returned from either a search or an info query type.

Example of ReturnType error:

{"version":5,"type":"error","resultcount":0,"results":[],"error":"Incorrect by field specified."}

search

The search type is the result returned from a search request operation.

Example of ReturnType search:

{"version":5,"type":"search","resultcount":2,"results":[{"ID":206807,"Name":"cower-git", ...}]}

info

The info type is the result returned from an info request operation.

Example of 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

If you are working with a javascript page, and need a JSON callback mechanism, you can do it. You just need to provide an additional callback variable. This callback is usually handled via the javascript library, but here is an example.

Example Query:

https://aur.archlinux.org/rpc/?v=5&type=search&arg=foobar&callback=jsonp1192244621103

Example Result:

/**/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"}]})

This would automatically call the JavaScript function jsonp1192244621103 with the parameter set to the results of the RPC call.

Limitations

  • 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 default URI maximum length limit of 4443 bytes. Info requests with more than about 200 packages as an argument will need to be split.
  • Search queries must be at least two characters long.
  • Searches will fail if they contain 5000 or more results.
  • The API rate is limited to a maximum of 4000 requests per day per IP.

Reference clients

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