<<

# Bugzilla::WebService

- NAME
- DESCRIPTION
- CALLING METHODS
- PARAMETERS
  - How Bugzilla WebService Methods Take Parameters
- LOGGING IN
- STABLE, EXPERIMENTAL, and UNSTABLE
- ERRORS
  - Transient vs. Fatal Errors
  - Unknown Errors
- COMMON PARAMETERS
  - Limiting What Fields Are Returned

# NAME

Bugzilla::WebService - The Web Service interface to Bugzilla

# DESCRIPTION

This is the standard API for external programs that want to interact with Bugzilla. It provides various methods in various modules.

You can interact with this API via XML-RPC or JSON-RPC.

# CALLING METHODS

Methods are grouped into "packages", like `Bug` for Bugzilla::WebService::Bug. So, for example, "get" in Bugzilla::WebService::Bug, is called as `Bug.get`.

# PARAMETERS

The Bugzilla API takes the following various types of parameters:

`int`

  Integer. May be null.

`double`

  A floating-point number. May be null.

`string`

  A string. May be null.

`dateTime`

  A date/time. Represented differently in different interfaces to this API. May be null.

`boolean`

  True or false.

`array`

  An array. There may be mixed types in an array.

  In example code, you will see the characters `[` and `]` used to represent the beginning and end of arrays.

  In our example code in these API docs, an array that contains the numbers 1, 2, and 3 would look like:

       [1, 2, 3]

`struct`

  A mapping of keys to values. Called a "hash", "dict", or "map" in some other programming languages. We sometimes call this a "hash" in the API documentation.

  The keys are strings, and the values can be any type.

  In example code, you will see the characters `{` and `}` used to represent the beginning and end of structs.

  For example, a struct with an "fruit" key whose value is "oranges", and a "vegetable" key whose value is "lettuce" would look like:

       { fruit => 'oranges', vegetable => 'lettuce' }

## How Bugzilla WebService Methods Take Parameters

All Bugzilla WebService functions use named parameters. The individual `Bugzilla::WebService::Server` modules explain how this is implemented for those frontends.

# LOGGING IN

You can use "login" in Bugzilla::WebService::User to log in as a Bugzilla user. This issues standard HTTP cookies that you must then use in future calls, so your client must be capable of receiving and transmitting cookies.

# STABLE, EXPERIMENTAL, and UNSTABLE

Methods are marked STABLE if you can expect their parameters and return values not to change between versions of Bugzilla. You are best off always using methods marked STABLE. We may add parameters and additional items to the return values, but your old code will always continue to work with any new changes we make. If we ever break a STABLE interface, we'll post a big notice in the Release Notes, and it will only happen during a major new release.

Methods (or parts of methods) are marked EXPERIMENTAL if we believe they will be stable, but there's a slight chance that small parts will change in the future.

Certain parts of a method's description may be marked as UNSTABLE, in which case those parts are not guaranteed to stay the same between Bugzilla versions.

# ERRORS

If a particular webservice call fails, it will throw an error in the appropriate format for the frontend that you are using. For all frontends, there is at least a numeric error code and descriptive text for the error.

The various errors that functions can throw are specified by the documentation of those functions.

Each error that Bugzilla can throw has a specific numeric code that will not change between versions of Bugzilla. If your code needs to know what error Bugzilla threw, use the numeric code. Don't try to parse the description, because that may change from version to version of Bugzilla.

Note that if you display the error to the user in an HTML program, make sure that you properly escape the error, as it will not be HTML-escaped.

## Transient vs. Fatal Errors

If the error code is a number greater than 0, the error is considered "transient," which means that it was an error made by the user, not some problem with Bugzilla itself.

If the error code is a number less than 0, the error is "fatal," which means that it's some error in Bugzilla itself that probably requires administrative attention.

Negative numbers and positive numbers don't overlap. That is, if there's an error 302, there won't be an error -302.

## Unknown Errors

Sometimes a function will throw an error that doesn't have a specific error code. In this case, the code will be `-32000` if it's a "fatal" error, and `32000` if it's a "transient" error.

# COMMON PARAMETERS

Many Webservice methods take similar arguments. Instead of re-writing the documentation for each method, we document the parameters here, once, and then refer back to this documentation from the individual methods where these parameters are used.

## Limiting What Fields Are Returned

Many WebService methods return an array of structs with various fields in the structs. (For example, "get" in Bugzilla::WebService::Bug returns a list of `bugs` that have fields like `id`, `summary`, `creation_time`, etc.)

These parameters allow you to limit what fields are present in the structs, to possibly improve performance or save some bandwidth.

`include_fields` (array)

  An array of strings, representing the (case-sensitive) names of fields. Only the fields specified in this hash will be returned, the rest will not be included.

  If you specify an empty array, then this function will return empty hashes.

  Invalid field names are ignored.

  Example:

        User.get( ids => [1], include_fields => ['id', 'name'] )

  would return something like:

        { users => [{ id => 1, name => 'user@domain.com' }] }

`exclude_fields` (array)

  An array of strings, representing the (case-sensitive) names of fields. The fields specified will not be included in the returned hashes.

  If you specify all the fields, then this function will return empty hashes.

  Invalid field names are ignored.

  Specifying fields here overrides `include_fields`, so if you specify a field in both, it will be excluded, not included.

  Example:

        User.get( ids => [1], exclude_fields => ['name'] )

  would return something like:

        { users => [{ id => 1, real_name => 'John Smith' }] }

<<