REST API guide

The Fisheye/Crucible REST interface provides a simple way for external application to talk to Fisheye and Crucible by making HTTP requests.

Introduction to Fisheye/Crucible's REST APIs

Fisheye/Crucible's REST APIs provide access to resources (data entities) via URI paths. To use a REST API, your application will make an HTTP request and parse the response. By default, the response format is XML. If you wish, you can request JSON instead of XML.

Because the REST API is based on open standards, you can use any web development language to access the API.

An example use case would be a gadget that provides information about build recent changes to a source repository, or lists your open reviews.

Fisheye/Crucible's REST APIs provide the following capabilities:

• Browse changes to source repositories.
• Retrieve a list of Fisheye or Crucible projects.
• Retrieve user or committer information.
• Search reviews based on custom criteria.
• Create or manipulate code reviews.

Getting Started

If you would like to know more about REST in general, start with the Dare Obasanjo's blog post, Explaining REST to Damien Katz.

Read the tutorials for examples of using the Fisheye/Crucible REST interface.

How to Authenticate your REST Requests.

Fisheye/Crucible API References

API references are available at the following locations:

You may find the WADL (Web Application Description Language) files generated for our REST API useful when writing REST clients. These are not human readable, but can be used to generate REST client stubs. The WADL files include their respective XML Schema documents that describe the structure of all possible request and response documents.

Accessing Fisheye/Crucible REST Resources

URIs for a Fisheye/Crucible REST API resource have the following structure:

Example:

1
2
http://myhost.com:8085/crucible/rest-service/reviews-v1

Here is an explanation for each part of the URI:

• host and port define the host and port where the Fisheye/Crucible application lives.
• webcontext is the webcontext under which Fisheye/Crucible is hosted (as configured in the <web-server context=""/> element in the application's config.xml
• rest-service denotes the Crucible REST API (rest-service-fe for Fisheye resources).
• resource-name-v1 identifies the versioned resource such as /reviews-v1. In some cases, this may be a generic resource name such as /foo. In other cases, this may include a generic resource name and key. For example, /foo returns a list of the foo items and /foo/{key} returns the full content of the foo identified by the given key.

Legacy REST/XML-RPC API

Fisheye also provides a REST and XML-RPC API which is now deprecated. It is documented here to assist in the maintenance of existing applications, but it will not be developed further and should not be used for new applications.