5.7.100. Bugzilla::WebService::Server::REST¶
5.7.100.1. NAME¶
Bugzilla::WebService::Server::REST - The REST Interface to Bugzilla
5.7.100.2. DESCRIPTION¶
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.
5.7.100.3. CONNECTING¶
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>
5.7.100.4. BROWSING¶
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.
5.7.100.5. DATA FORMAT¶
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.
5.7.100.6. AUTHENTICATION¶
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.
- Login name and password
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.
- Login token
By calling GET /login?login=fred@example.com&password=ilovecheese, you get back atokenvalue 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.
5.7.100.7. ERRORS¶
When an error occurs over REST, a hash structure is returned with the key errorset 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.
5.7.100.8. UTILITY FUNCTIONS¶
- handle
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.
- response
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.
- handle_login
This method determines the proper WebService all to make based on class and method name determined earlier. Then calls “handle_login” in Bugzilla::WebService::Server which will attempt to authenticate the client.
- bz_method_name
The WebService method name that matches the path used by the client.
- bz_class_name
The WebService class containing the method that matches the path used by the client.
- bz_rest_params
Each REST resource contains a hash key calledparamsthat 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.
- bz_rest_options
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.
- bz_success_code
Each resource can specify a specific SUCCESS CODE if the operation completes successfully. OTherwise STATUS OK (200) is the default returned.
- rest_include_exclude
Normally the WebService methods requiredinclude_fieldsandexclude_fieldsto 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.
