Difference between revisions of "AurJson"

From ArchWiki
Jump to: navigation, search
m (search: changed 'search_by' field to shorter 'by')
 
(31 intermediate revisions by 11 users not shown)
Line 1: Line 1:
 
[[Category:Package management]]
 
[[Category:Package management]]
The '''AurJson''' interface is a lightweight remote 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.
+
[[ja:AurJson]]
 +
{{Related articles start}}
 +
{{Related|Official repositories web interface}}
 +
{{Related articles end}}
 +
The '''AurJson''' interface is a lightweight remote 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 released with AUR v4.2.0 on February 15, 2016.}}
  
== API Usage ==
+
== API usage ==
  
The [https://aur.archlinux.org/rpc.php RPC interface] has four major query types:
+
The [https://aur.archlinux.org/rpc.php RPC interface] has two major query types:
  
 
* search
 
* search
 
* info
 
* info
* multiinfo
 
* msearch
 
 
Each method requires the following HTTP GET syntax:
 
 
type=methodname&arg=data
 
 
Where '''''methodname''''' is the name of an allowed method, and '''''data''''' is the argument to the call.
 
  
 
Data is returned in json encapsulated format.
 
Data is returned in json encapsulated format.
  
=== Query Types ===
+
=== Query types ===
  
As noted above, there are four query types:  
+
As noted above, there are two query types:  
 
* search
 
* search
 
* info
 
* info
* msearch
 
* msearch
 
  
==== Search ====
+
==== search ====
  
A '''''search''''' type query takes an argument of a string, or partial string, with which to perform a package search. Possible return types are '''''error''''' and '''''search'''''.
+
Package searches can be performed by issuing requests of the form:
  
Example:
+
  /rpc/?v=5&type=search&by=field&arg=keywords
  <nowiki>http://aur-url/rpc.php?type=search&arg=foobar</nowiki>
+
  
The above is a query of type '''''search''''' and the search argument is "foobar".
+
where '''''keywords''''' is the search argument and '''''field''''' is one of the following values:
  
==== Info ====
+
* ''name'' (search by package name only)
 +
* ''name-desc'' (search by package name and description)
 +
* ''maintainer'' (search by package maintainer)
  
An '''''info''''' type query takes an argument of a string '''''or''''' an integer. If an integer, the integer must be an exact match to an existing packageID, or an '''''error''''' type is returned. If a string, the string must be an exact match to an existing packageName, or an '''''error''''' type is returned.
+
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:
 
Examples:
  <nowiki>http://aur-url/rpc.php?type=info&arg=1123</nowiki>
+
  <nowiki>https://aur.archlinux.org/rpc/?v=5&type=search&arg=foobar</nowiki>
<nowiki>http://aur-url/rpc.php?type=info&arg=foobar</nowiki>
+
  
The two examples above are both queries of type '''''info'''''. The first query is using an integer type argument, and the second is using a packageName argument. If packageID 1123 corresponded to packageName foobar, then both of the above queries would return the details of the foobar package.
+
Search for ''foobar''.
  
==== mutiinfo ====
+
<nowiki>https://aur.archlinux.org/rpc/?v=5&type=search&by=maintainer&arg=john</nowiki>
  
The majority of "real world" info requests come in hefty batches. AUR can handle these in one request rather than
+
Search for packages maintained by ''john''.
multiple by allowing AUR clients to send multiple arguments.
+
 
 +
<nowiki>https://aur.archlinux.org/rpc/?v=5&type=search&arg=foobar&callback=jsonp1192244621103</nowiki>
 +
 
 +
Search with callback.
 +
 
 +
==== 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:
 
Examples:
  <nowiki>http://aur.test/rpc.php?type=multiinfo&arg[]=cups-xerox&arg[]=cups-mc2430dl&arg[]=10673</nowiki>
+
  <nowiki>https://aur.archlinux.org/rpc/?v=5&type=info&arg[]=foobar</nowiki>
  
==== msearch ====
+
Info for single ''foobar'' package.
  
A '''''msearch''''' type query takes an argument of a string, or partial string, with which to perform a search by maintainer name. Possible return types are '''''error''''' and '''''msearch'''''.
+
<nowiki>https://aur.archlinux.org/rpc/?v=5&type=info&arg[]=foo&arg[]=bar</nowiki>
  
Example:
+
Info for multiple ''foobar'' and ''bar'' packages.
<nowiki>http://aur-url/rpc.php?type=msearch&arg=cactus</nowiki>
+
  
The above is a query of type '''''msearch''''' and the search argument is "cactus".
+
=== 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 format of the return payload is:
 
The format of the return payload is:
  {"type":ReturnType,"results":ReturnData}
+
  {"version":5,"type":"ReturnType","resultcount":0,"results":ReturnData}
  
 
ReturnType is a string, and the value is one of:  
 
ReturnType is a string, and the value is one of:  
 +
* search
 +
* multiinfo
 
  * error
 
  * error
* search
 
* info
 
  
The type of ReturnData is dependent on the query type:
+
The type of ReturnData is an array of dictionary objects for the '''''search''''' and '''''multiinfo''''' ReturnType, and an empty array for '''''error''''' ReturnType.
* If ReturnType is '''''error''''' then ReturnData is a string.
+
* If ReturnType is '''''search''''' then ReturnData is an array of dictionary objects.
+
* If ReturnType is '''''info''''' then ReturnData is a single dictionary object.
+
  
==== Error ====
+
==== 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.
+
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''''':
 
Example of ReturnType '''''error''''':
  {"type":"error","results":"No results found"}
+
  {"version":5,"type":"error","resultcount":0,"results":[],"error":"Incorrect by field specified."}
  
==== Search ====
+
==== search ====
The search type is the result returned from a search request operation. Returning the type as search is useful for detecting whether the response to a search operation is search data or an error.
+
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.'''
  
 
Example of ReturnType '''''search''''':
 
Example of ReturnType '''''search''''':
  {"type":"search","results":[{"Name":"pam_abl","ID":"1995"}]}
+
  {"version":5,"type":"search","resultcount":2,"results":[{"ID":206807,"Name":"cower-git", ...}]}
  
==== Info ====
+
==== info ====
The info type is the result returned from an info request operation. Returning the type as search is useful for detecting whether the response to a search operation is search data or an error.
+
The info type is the result returned from an info request operation.
  
Example of ReturnType '''''info''''':
+
Example of ReturnType '''''multiinfo''''':
 
  <nowiki>
 
  <nowiki>
 
  {
 
  {
     "type": "info",
+
    "version":5,
     "results": {
+
     "type":"multiinfo",
         "Description": "Provides auto blacklisting of hosts and users responsible for repeated failed authentication attempts",  
+
    "resultcount":1,
         "ID": "1995",  
+
     "results":[{
         "License": "",  
+
         "ID":229417,
         "Name": "pam_abl",  
+
         "Name":"cower",
         "NumVotes": "4",  
+
         "PackageBaseID":44921,
         "OutOfDate": "0",  
+
         "PackageBase":"cower",
         "URL": "http://www.hexten.net/pam_abl",
+
         "Version":"14-2",
         "URLPath": "/packages/pam_abl/pam_abl.tar.gz",  
+
         "Description":"A simple AUR agent with a pretentious name",
         "Version": "0.2.3-1"
+
         "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":[]
 +
     }]
 
  }
 
  }
 
  </nowiki>
 
  </nowiki>
Line 119: Line 144:
  
 
Example Query:
 
Example Query:
  <nowiki>http://aur-url/rpc.php?type=search&arg=foobar&callback=jsonp1192244621103</nowiki>
+
  <nowiki>https://aur.archlinux.org/rpc/?v=5&type=search&arg=foobar&callback=jsonp1192244621103</nowiki>
  
 
Example Result:
 
Example Result:
  jsonp1192244621103({"type":"error","results":"No results found"})
+
  /**/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 {{Ic|jsonp1192244621103}} with the parameter set to the results of the RPC call. (In this case, {{Ic|<nowiki>{"type":"error","results":"No results found"}</nowiki>}})
+
This would automatically call the JavaScript function {{Ic|jsonp1192244621103}} with the parameter set to the results of the RPC call.
  
== More Examples ==
+
== Reference clients ==
  
Example Query and Result:
+
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
<nowiki>
+
http://aur-url/rpc.php?type=search&arg=foobar
+
{"type":"error","results":"No results found"}
+
</nowiki>
+
 
+
Example Query and Result:
+
<nowiki>
+
http://aur-url/rpc.php?type=search&arg=pam_abl
+
{"type":"search","results":[{"Name":"pam_abl","ID":"1995"}]}
+
</nowiki>
+
 
+
Example Query and Result:
+
<nowiki>
+
http://aur-url/rpc.php?type=info&arg=pam_abl
+
{
+
    "type": "info",
+
    "results": {     
+
        "Description": "Provides auto blacklisting of hosts and users responsible for repeated failed authentication attempts",
+
        "ID": "1995",
+
        "License": "",
+
        "Name": "pam_abl",
+
        "NumVotes": "4",
+
        "OutOfDate": "0",
+
        "URL": "http://www.hexten.net/pam_abl",
+
        "URLPath": "/packages/pam_abl/pam_abl.tar.gz",
+
        "Version": "0.2.3-1"
+
    }
+
}
+
</nowiki>
+
  
== Reference Clients ==
+
== Associated code ==
  
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/master/aurjson_examples
+
* 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.
 +
* {{Pkg|jshon}} parses, reads and creates JSON from the command-line. See [http://kmkeen.com/jshon/ jshon] for details.

Latest revision as of 14:10, 15 March 2016

The AurJson interface is a lightweight remote interface for the AUR. It utilizes HTTP GET queries as the request format, and json as the response data exchange format.

Note: This article describes v5 of the RPC Interface API, as released with AUR v4.2.0 on February 15, 2016.

API usage

The RPC interface has two major query types:

  • search
  • info

Data is returned in json encapsulated format.

Query types

As noted above, 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)

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:

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

Search for foobar.

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

Search for packages maintained by john.

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

Search with callback.

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:

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

Info for single foobar package.

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

Info for multiple foobar and bar packages.

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

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

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. The actual results of a search operation will be the same as an info request for each result. See the info section.

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.

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

Associated code

  • The python3-aurAUR package provides python modules for interacting with the remote AUR JSON interface, among other AUR services. See python3-aur for details.
  • jshon parses, reads and creates JSON from the command-line. See jshon for details.