Fisheye and Crucible Development : Fisheye Legacy Remote API

For developers who are interested in accessing the Fisheye functionality remotely, this page describes the methods, data types and structures for accessing the Fisheye Remote API.

Additional documentation is available as part of your Fisheye installation, under FISHEYE_HOST/api/, such as in this example:

1
2
http://localhost:8060/api/ 

This loads a local HTML page, where you will be able to see whether API Access is currently enabled or disabled on your Fisheye instance. You will also be able to link to local code examples for REST and XML-RPC from the Fisheye folders.

API mechanisms are REST-ful and XML-RPC.

NOTE: Before you begin using the remote API, you will need to enable it through the Fisheye Admin interface. For instructions, see Configuring the Fisheye web server.

XML-RPC API

The XML-RPC API can be accessed from FISHEYE_HOST/api/xmlrpc, such as in this example:

1
2
http://localhost:8060/api/xmlrpc 

REST API

The REST API can be accessed from FISHEYE_HOST/api/rest/.

NOTE: More information on the data types and services can be seen on the specific Fisheye REST API pages.

REST Example:

1
2
 
http://localhost:8060/api/rest/changeset?rep=cvs&csid=BRANCH_2_2%3Amatt%3A20050517064053 

This returns the details of a single changeset. Note that parameter values must be URL encoded.

REST return values are always enclosed in a <response> root element.

Dates are IS0-8601, in the general form

1
2
 
YYYY-MM-DDTHH:MM:SS(Z|[+-]HH:MM) 

The timezone is optional (GMT is used if omitted). The time component is also optional. The seconds component can contain a fractional part.

For XMLRPC, Fisheye returns all dates in GMT using

1
2
 
YYYYMMDDTHH:MM:SS 

Note that no timezone is used.

Authentication

Fisheye may be configured to require authentication before accessing a repository. Most methods accept an authentication token parameter. To call a method anonymously, use the empty-string for this parameter.

An authentication token can be acquired (and released) using the login() and logout() methods.

Examples

The following code example files can be found in the API folder under your Fisheye instance:

1
2
 
FISHEYE_HOME\content\api\ 

Browse to that folder and you will be able to access the files below:

• Python XML-RPC example: xmlrpc_example.py

• Python REST example: rest_example.py

• Java REST example: RestClient.java

• The open source Fisheye Plugin for JIRA provides an example of querying using the API.

Methods

#### Log in

1
2
 
String login(String username, String password) 

Description Log in and create an authentication token. Returns the token if log in was successful, or returns an error otherwise. REST

1
2
 
api/rest/login 

XML-RPC

1
2
 
String login(String username, String password) 

Log out

1
2
 
boolean logout(String auth) 

Description Disables the given auth token. Returns true in all cases. REST

1
2
 
api/rest/logout 

XML-RPC

1
2
 
boolean logout(String auth) 

Fisheye Version

1
2
 
String fisheyeVersion() 

Description Returns the version number of this Fisheye instance. REST

1
2
 
/api/rest/fisheyeVersion 

XML-RPC

1
2
 
String fisheyeVersion() 

Example Return Values "1.3.8", "1.4" Since Fisheye 1.4 / Crucible 1.2

Crucible Version

1
2
 
String crucibleVersion() 

Description Returns the Crucible version number if Crucible is installed. This API method will return an empty String if this isn't a Crucible instance. REST

1
2
 
/api/rest/crucibleVersion 

XML-RPC

1
2
 
String crucibleVersion() 

Example Return Values "1.2", "1.2.1", "" (if not a Crucible instance) Since Fisheye 1.4 / Crucible 1.2

List Repositories

1
2
 
String[] listRepositories(String auth) 

Description Returns a list of repository names in this Fisheye instance. REST

1
2
 
api/rest/repositories 

XML-RPC

1
2
 
String[] listRepositories(String auth) 

List Paths

1
2
 
PathInfo[] listPaths(String auth, String rep, String path) 

Description Returns a list of paths immediately under the given path. A path represents either a file or a directory. REST

1
2
 
api/rest/paths 

XML-RPC

1
2
 
PathInfo[] getPaths(String auth, String rep, String path) 

Get Revision

1
2
 
Revision getRevision(String auth, String rep, String path, String rev) 

Description Returns the details of a particular revision. REST

1
2
 
api/rest/revision 

XML-RPC

1
2
 
Revision getRevision(String auth, String rep, String path, String rev) 

List Tags for Revision

1
2
 
String[] listTagsForRevision(String auth, String rep, String path, String rev) 

Description Returns the tags associated with particular revision as an array of strings. REST

1
2
 
api/rest/tags 

XML-RPC

1
2
 
RevisionTags listTagsForRevision(String auth, String rep, String path, String rev) 

Path History

1
2
 
PathHistory listPathHistory(String auth, String rep, String path) 

Description Returns history of a particular path. REST

1
2
 
api/rest/pathHistory 

XML-RPC

1
2
 
PathHistory listPathHistory(String auth, String rep, String path) 

Get Changeset

1
2
 
Changeset getChangeset(String auth, String rep, String csid) 

Description Gets the details of a particular changeset. REST

1
2
 
api/rest/changeset 

XML-RPC

1
2
 
Changeset getChangeset(String auth, String csid) 

List Changesets

1
2
 
Changesets listChangesets(String auth, String rep, String path, Date start=null, Date end=null, Integer maxReturn=null) 

Description Lists changes under a given path, optionally between two dates. Returned structure contains a list of changeset ids, from most-recent to least-recent. REST

1
2
 
api/rest/changesets 

XML-RPC

1
2
 
Changesets listChangesets(String auth, String rep, String path) 
Changesets listChangesets(String auth, String rep, String path, Date start) 
Changesets listChangesets(String auth, String rep, String path, Date start, Date end) 
Changesets listChangesets(String auth, String rep, String path, Date start, Date end, Integer maxReturn) 

To get changes for the whole repository, use a path of "/" If the start date is not specified, there is no lower bound. If the end date is not specified, "now" is used.

The maxReturn clause limits the number of changesets returned by this method. If no limit is specified, Fisheye will use its own internal limit (a few thousand). If this limit is exceeded, the return value will be truncated so that it contains the most-recent changesets. The value of this limit is contained in the returned data structure.

EyeQL Query

1
2
 
query(String auth, String rep, String query) 

Description Execute an EyeQL query. For a "normal" query, returns a list of revision keys that matched to query. If the query contains a "return" clause, then returns a custom Row for each match. The contents of the Row will depend upon the "return" clause. REST

1
2
 
api/rest/query 

XML-RPC

1
2
 
RevisionKey[] query(String auth, String rep, String query) 

or

1
2
 
Row[] query(String auth, String rep, String query) 

Changeset Bounds

1
2
 
ChangesetBounds getChangesetBounds(String auth, String rep, String path=null, Date start=null, Date end=null) 

Description NOT IMPLEMENTED YET. Gets the details of a particular changeset. REST

1
2
 
api/rest/changesetBounds 

XML-RPC

1
2
 
ChangesetBounds getChangesetBounds(String auth, String rep) 
ChangesetBounds getChangesetBounds(String auth, String rep, Date start) 
ChangesetBounds getChangesetBounds(String auth, String rep, Date start, Date end) 
ChangesetBounds getChangesetBounds(String auth, String rep, String path) 
ChangesetBounds getChangesetBounds(String auth, String rep, String path, Date start) 
ChangesetBounds getChangesetBounds(String auth, String rep, String path, Date start, Date end) 

Data Types and Structures

Data types used are the same as defined in XML-RPC.

Some methods return data structures. These map into XML-RPC as expected.

For REST calls, structs are encoded as XML elements of the same name (but all lowercase). Members are encoded as sub-elements, or as attributes as indicated below.

RevisionKey

1
2
 
struct RevisionKey { 
String path; // (REST: attribute) 
String rev; // (REST: attribute) 
} 

PathInfo

1
2
 
struct PathInfo { 
String name; // (REST: attribute) 
boolean isFile; // (REST: attribute) 
boolean isDir; // (REST: attribute) 
boolean isHeadDeleted; // (REST: attribute) 
} 

Revision

1
2
 
struct Revision { 
String path; // (REST: attribute) 
String rev; // (REST: attribute) 
String author; // (REST: attribute) 
Date date; // (REST: attribute) 
String state; // one of "changed" "added" or "deleted" (REST: attribute) 
int totalLines; // (REST: attribute) 
int linesAdded; // (REST: attribute) 
int linesRemoved; // (REST: attribute) 
String log; 
String csid; // optional (REST: attribute) 
String ancestor; // optional (REST: attribute) 
} 

Changeset

1
2
 
struct Changeset { 
String csid; // (REST: attribute) 
Date date; // (REST: attribute) 
String author; // (REST: attribute) 
String branch; // (REST: attribute) 
boolean sealed; // (REST: attribute) 
String log; 
RevisionKey[] revisions; 
} 

Changesets

1
2
 
struct Changesets { 
int maxReturn; // (REST: attribute) 
String[] csids; 
} 

Description

A list of Changeset ids, most-recent changeset first. maxReturn indicates the maximum number of changesets Fisheye is configured to return from this method.

ChangesetBounds

1
2
 
struct ChangesetBounds { 
Changeset first; 
Changeset last; 
} 

Row

1
2
 
struct Row { 
... 
} 

Description A custom structure, depending on the given EyeQL statement. Each member of Row is typed.