The FishEye API

FishEye API

This page describes the ways of accessing the FishEye API.

API mechanisms are REST-ful and XML-RPC.

XML-RPC

The XML-RPC API can be accessed from /fecru/api/xmlrpc

REST

The REST API can be accessed from /fecru/api/rest/

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

Dates are IS0-8601, in the general form 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 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

A Python XML-RPC example: xmlrpc_example.py

A Python REST example: rest_example.py

A Java REST example: RestClient.java

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

Methods

String login(String username, String password)
REST: api/rest/login
XML-RPC: String login(String username, String password)
Description: Login and create an authentication token. Returns the token if login was successful, or returns an error otherwise.

boolean logout(String auth)
REST: api/rest/logout
XML-RPC: boolean logout(String auth)
Description: Disables the given auth token. Returns true in all cases.

String fisheyeVersion()
REST: /api/rest/fisheyeVersion
XML-RPC: String fisheyeVersion()
Description: Returns the version number of this FishEye instance.
Example Return Values: "1.3.8", "1.4"
Since: FishEye 1.4 / Crucible 1.2

String crucibleVersion()
REST: /api/rest/crucibleVersion
XML-RPC: 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.
Example Return Values: "1.2", "1.2.1", "" (if not a Crucible instance)
Since: FishEye 1.4 / Crucible 1.2

String[] listRepositories(String auth)
REST: api/rest/repositories
XML-RPC: String[] getRepositories(String auth)
Description: Returns a list of repository names in this FishEye instance.

PathInfo[] listPaths(String auth, String rep, String path)
REST: api/rest/paths
XML-RPC: PathInfo[] getPaths(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.

Revision getRevision(String auth, String rep, String path, String rev)
REST: api/rest/revision
XML-RPC: Revision getRevision(String auth, String rep, String path, String rev)
Description: The details of a particular revision.

String[] listTagsForRevision(String auth, String rep, String path, String rev)
REST: api/rest/tags
XML-RPC: RevisionTags listTagsForRevision(String auth, String rep, String path, String rev)
Description: Returns the tags associated with particular revision as an array of strings.

PathHistory listPathHistory(String auth, String rep, String path)
REST: api/rest/pathHistory
XML-RPC: PathHistory listPathHistory(String auth, String rep, String path)
Description: returns history of a particular path.

Changeset getChangeset(String auth, String rep, String csid)
REST: api/rest/changeset
XML-RPC: Changeset getChangeset(String auth, String csid)
Description: Gets a the details of a particular changeset

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

REST

api/rest/changesets

XML-RPC

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)

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.

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.

query(String auth, String rep, String query)
REST: api/rest/query
XML-RPC: RevisionKey[] query(String auth, String rep, String query)
or
Row[] 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.

ChangesetBounds getChangesetBounds(String auth, String rep, String path=null, Date start=null, Date end=null)
REST: api/rest/changesetBounds
XML-RPC: 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)
Description: NOT IMPLEMENTED YET. Gets a the details of a particular changeset

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

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

PathInfo

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

Revision

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

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

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

struct ChangesetBounds {
  Changeset first;
  Changeset last;
}

Row

struct Row {
  ...
}

Description

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