Difference between revisions of "AurJson"

From ArchWiki
Jump to: navigation, search
Line 3: Line 3:
 
The AurJson interface is a lightweight remote interface for the AUR. It utilizes [http://www.json.org/ json] as the data exchange format.
 
The AurJson interface is a lightweight remote interface for the AUR. It utilizes [http://www.json.org/ json] as the data exchange format.
  
== General ==
+
== API Usage ==
  
 
The interface has two major query types:
 
The interface has two major query types:
Line 18: Line 18:
 
Data is returned in json encapsulated format.
 
Data is returned in json encapsulated format.
  
== Query Types ==
+
=== Query Types ===
  
 
As noted above, there are two query types:  
 
As noted above, there are two query types:  
Line 24: Line 24:
 
* info
 
* info
  
=== 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'''''.
 
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'''''.
Line 33: Line 33:
 
The above is a query of type '''''search''''' and the search argument is "foobar".
 
The above is a query of type '''''search''''' and the search argument is "foobar".
  
=== Info ===
+
==== Info ====
  
 
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.
 
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.
Line 43: Line 43:
 
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.
 
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.
  
== Return Values ==
+
=== Return Values ===
  
 
The return payload is of one format, and currently has three main types.
 
The return payload is of one format, and currently has three main types.
Line 57: Line 57:
 
* If ReturnType is '''''info''''' then ReturnData is a single dictionary object.
 
* 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.
  
Line 63: Line 63:
 
  {"type":"error","results":"No results found"}
 
  {"type":"error","results":"No results found"}
  
=== 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. Returning the type as search is useful for detecting whether the response to a search operation is search data or an error.
  
Line 69: Line 69:
 
  {"type":"search","results":[{"Name":"pam_abl","ID":"1995"}]}
 
  {"type":"search","results":[{"Name":"pam_abl","ID":"1995"}]}
  
=== 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. Returning the type as search is useful for detecting whether the response to a search operation is search data or an error.
  
Line 75: Line 75:
 
  {"type":"info","results":{"ID":"1995","Name":"pam_abl","Version":"0.2.3-1","Description":"Provides auto blacklisting of hosts and users responsible for repeated failed authentication attempts","URL":"http:\/\/www.hexten.net\/pam_abl","URLPath":"\/packages\/pam_abl\/pam_abl.tar.gz","License":"","NumVotes":"4","OutOfDate":"0"}}
 
  {"type":"info","results":{"ID":"1995","Name":"pam_abl","Version":"0.2.3-1","Description":"Provides auto blacklisting of hosts and users responsible for repeated failed authentication attempts","URL":"http:\/\/www.hexten.net\/pam_abl","URLPath":"\/packages\/pam_abl\/pam_abl.tar.gz","License":"","NumVotes":"4","OutOfDate":"0"}}
  
== jsonp ==
+
=== jsonp ===
  
 
If you are working with a javascript page, and need a jsonp callback mechanism, you can do it.
 
If you are working with a javascript page, and need a jsonp callback mechanism, you can do it.

Revision as of 03:24, 5 April 2008

Overview

The AurJson interface is a lightweight remote interface for the AUR. It utilizes json as the data exchange format.

API Usage

The interface has two major query types:

  • search
  • info

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.

Query Types

As noted above, there are two query types:

  • search
  • info

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.

Example:

http://aur-url/rpc.php?type=search&arg=foobar

The above is a query of type search and the search argument is "foobar".

Info

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.

Examples:

http://aur-url/rpc.php?type=info&arg=1123
http://aur-url/rpc.php?type=info&arg=foobar

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.

Return Values

The return payload is of one format, and currently has three main types.

The main format of the return payload is:

"type": ReturnType
"data": ReturnData

ReturnType is one of: Error, Search, Info. The return type of ReturnData is dependent on the query type:

  • 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

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 return of ReturnType error:

{"type":"error","results":"No results found"}

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.

Example return of ReturnType search:

{"type":"search","results":[{"Name":"pam_abl","ID":"1995"}]}

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.

Example return of ReturnType info:

{"type":"info","results":{"ID":"1995","Name":"pam_abl","Version":"0.2.3-1","Description":"Provides auto blacklisting of hosts and users responsible for repeated failed authentication attempts","URL":"http:\/\/www.hexten.net\/pam_abl","URLPath":"\/packages\/pam_abl\/pam_abl.tar.gz","License":"","NumVotes":"4","OutOfDate":"0"}}

jsonp

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

Example Query:

http://aur-url/rpc.php?type=search&arg=foobar&callback=jsonp1192244621103

Example Return:

jsonp1192244621103({"type":"error","results":"No results found"})

More Examples

Example Query and Result:

http://aur-url/rpc.php?type=search&arg=foobar
{"type":"error","results":"No results found"}

Example Query and Result:

 http://aur-url/rpc.php?type=search&arg=pam_abl
 {"type":"search","results":[{"Name":"pam_abl","ID":"1995"}]}

Example Query and Result:

 http://aur-url/rpc.php?type=info&arg=pam_abl
 {"type":"info","results":{"ID":"1995","Name":"pam_abl","Version":"0.2.3-1","Description":"Provides auto blacklisting of hosts and users responsible for repeated failed authentication attempts","URL":"http:\/\/www.hexten.net\/pam_abl","URLPath":"\/packages\/pam_abl\/pam_abl.tar.gz","License":"","NumVotes":"4","OutOfDate":"0"}}