Bugzilla::WebService::Server::REST - The REST Interface to Bugzilla
This documentation describes things about the Bugzilla WebService that are specific to REST. For a general overview of the Bugzilla WebServices, see Bugzilla::WebService. The Bugzilla::WebService::Server::REST module is a sub-class of Bugzilla::WebService::Server::JSONRPC so any method documentation not found here can be viewed in it's POD.
Please note that everything about this REST interface is EXPERIMENTAL.
If you want a fully stable API,
please use the Bugzilla::WebService::Server::XMLRPC|XML-RPC interface.
The endpoint for the REST interface is the rest.cgi script in your Bugzilla installation.
For example,
if your Bugzilla is at bugzilla.yourdomain.com,
to access the API and load a bug,
you would use http://bugzilla.yourdomain.com/rest.cgi/bug/35.
If using Apache and mod_rewrite is installed and enabled,
you can simplify the endpoint by changing /rest.cgi/ to something like /rest/ or something similar.
So the same example from above would be: http://bugzilla.yourdomain.com/rest/bug/35 which is simpler to remember.
Add this to your .htaccess file:
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteRule ^rest/(.*)$ rest.cgi/$1 [NE]
</IfModule>
If the Accept: header of a request is set to text/html (as it is by an ordinary web browser) then the API will return the JSON data as a HTML page which the browser can display. In other words, you can play with the API using just your browser and see results in a human-readable form. This is a good way to try out the various GET calls, even if you can't use it for POST or PUT.
The REST API only supports JSON input, and either JSON and JSONP output. So objects sent and received must be in JSON format. Basically since the REST API is a sub class of the JSONRPC API, you can refer to JSONRPC for more information on data types that are valid for REST.
On every request, you must set both the "Accept" and "Content-Type" HTTP headers to the MIME type of the data format you are using to communicate with the API. Content-Type tells the API how to interpret your request, and Accept tells it how you want your data back. "Content-Type" must be "application/json". "Accept" can be either that, or "application/javascript" for JSONP - add a "callback" parameter to name your callback.
Parameters may also be passed in as part of the query string for non-GET requests and will override any matching parameters in the request body.
Along with viewing data as an anonymous user, you may also see private information if you have a Bugzilla account by providing your login credentials.
Pass in as query parameters of any request:
login=fred@example.com&password=ilovecheese
Remember to URL encode any special characters, which are often seen in passwords and to also enable SSL support.
By calling GET /login?login=fred@example.com&password=ilovecheese, you get back a token value which can then be passed to each subsequent call as authentication. This is useful for third party clients that cannot use cookies and do not want to store a user's login and password in the client. You can also pass in "token" as a convenience.
When an error occurs over REST, a hash structure is returned with the key error set to true.
The error contents look similar to:
{ "error": true, "message": "Some message here", "code": 123 }
Every error has a "code", as described in "ERRORS" in Bugzilla::WebService. Errors with a numeric code higher than 100000 are errors thrown by the JSON-RPC library that Bugzilla uses, not by Bugzilla.
This method overrides the handle method provided by JSONRPC so that certain actions related to REST such as determining the proper resource to use, loading query parameters, etc. can be done before the proper WebService method is executed.
This method overrides the response method provided by JSONRPC so that the response content can be altered for REST before being returned to the client.
This method determines the proper WebService all to make based on class and method name determined earlier. Then calls Bugzilla::WebService::Server::handle_login which will attempt to authenticate the client.
The WebService method name that matches the path used by the client.
The WebService class containing the method that matches the path used by the client.
Each REST resource contains a hash key called params that is a subroutine reference. This subroutine will return a hash structure based on matched values from the path information that is formatted properly for the WebService method that will be called.
When a client uses the OPTIONS request method along with a specific path, they are requesting the list of request methods that are valid for the path. Such as for the path /bug, the valid request methods are GET (search) and POST (create). So the client would receive in the response header, Access-Control-Allow-Methods: GET, POST.
Each resource can specify a specific SUCCESS CODE if the operation completes successfully. OTherwise STATUS OK (200) is the default returned.
Normally the WebService methods required include_fields and exclude_fields to be an array of field names. REST allows for the values for these to be instead comma delimited string of field names. This method converts the latter into the former so the WebService methods will not complain.