<<

# Bugzilla::WebService::Server::REST

- NAME
- DESCRIPTION
- CONNECTING
- BROWSING
- DATA FORMAT
- AUTHENTICATION
- ERRORS
- UTILITY FUNCTIONS
- SEE ALSO

# NAME

Bugzilla::WebService::Server::REST - The REST Interface to Bugzilla

# 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.

# 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>

# 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.

# 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.

# 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 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.

# ERRORS

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.

# 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 Bugzilla::WebService::Server::handle_login 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 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.

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 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.

# SEE ALSO

Bugzilla::WebService

<<