5.7.84. Bugzilla::WebService¶
5.7.84.1. NAME¶
Bugzilla::WebService - The Web Service interface to Bugzilla
5.7.84.2. 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, JSON-RPC or REST.
5.7.84.3. CALLING METHODS¶
Methods are grouped into "packages", like Bug
for
Bugzilla::WebService::Bug. So, for example,
Bugzilla::WebService::Bug/get, is called as Bug.get
.
For REST, the "package" is more determined by the path used to access the resource. See each relevant method for specific details on how to access via REST.
5.7.84.4. 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.
email
A string representing an email address. This value, when returned, may be filtered based on if the user is logged in or not. May be null.
dateTime
A date/time. Represented differently in different interfaces to this API. May be null.
boolean
True or false.
base64
A base64-encoded string. This is the only way to transfer binary data via the WebService.
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.
5.7.84.5. LOGGING IN¶
Some methods do not require you to log in. An example of this is Bug.get. However, authenticating yourself allows you to see non public information. For example, a bug that is not publicly visible.
There are two ways to authenticate yourself:
Bugzilla_api_key
Added in Bugzilla 5.0
You can specify
Bugzilla_api_key
as an argument to any WebService method, and you will be logged in as that user if the key is correct, and has not been revoked. You can set up an API key by using the 'API Key' tab in the Preferences pages.
Bugzilla_login
and Bugzilla_password
Added in Bugzilla 3.6
You can specify
Bugzilla_login
andBugzilla_password
as arguments to any WebService method, and you will be logged in as that user if your credentials are correct. Here are the arguments you can specify to any WebService method to perform a login:
Bugzilla_login
(string) - A user's login name.
Bugzilla_password
(string) - That user's password.
Bugzilla_restrictlogin
(boolean) - Optional. If true, then your login will only be valid for your IP address.The
Bugzilla_restrictlogin
option is only used when you have also specifiedBugzilla_login
andBugzilla_password
. This value will be deprecated in the release after Bugzilla 5.0 and you will be required to pass the Bugzilla_login and Bugzilla_password for every call.For REST, you may also use the
login
andpassword
variable names instead ofBugzilla_login
andBugzilla_password
as a convenience. You may also usetoken
instead ofBugzilla_token
.
There are also two deprecreated methods of authentications. This will be removed in the version after Bugzilla 5.0.
User.login
You can use Bugzilla::WebService::User/login to log in as a Bugzilla user. This issues a token that you must then use in future calls.
Bugzilla_token
Added in Bugzilla 4.4.3
You can specify
Bugzilla_token
as argument to any WebService method, and you will be logged in as that user if the token is correct. This is the token returned when callingUser.login
mentioned above.An error is thrown if you pass an invalid token and you will need to log in again to get a new token.
Token support was added in Bugzilla 5.0 and support for login cookies has been dropped for security reasons.
5.7.84.6. 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.
5.7.84.7. 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.
5.7.84.8. 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, Bugzilla::WebService::Bug/get
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 in the return value. 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' }] }Note for REST,
include_fields
may instead be a comma delimited string for GET type requests.
exclude_fields
array
An array of strings, representing the (case-sensitive) names of fields in the return value. The fields specified will not be included in the returned hashes.If you specify all the fields, then this function will return empty hashes.
Some RPC calls support specifying sub fields. If an RPC call states that it support sub field restrictions, you can restrict what information is returned within the first field. For example, if you call Product.get with an include_fields of components.name, then only the component name would be returned (and nothing else). You can include the main field, and exclude a sub field.
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' }] }Note for REST,
exclude_fields
may instead be a comma delimited string for GET type requests.
There are several shortcut identifiers to ask for only certain groups of fields to be returned or excluded.
_all
All possible fields are returned if_all
is specified ininclude_fields
.
_default
These fields are returned ifinclude_fields
is empty or_default
is specified. All fields described in the documentation are returned by default unless specified otherwise.
_extra
These fields are not returned by default and need to be manually specified ininclude_fields
either by field name, or using_extra
.
_custom
Only custom fields are returned if_custom
is specified ininclude_fields
. This is normally specific to bug objects and not relevant for other returned objects.