API Idioms

Table of Contents

URLs and Parameters
Kiln Harmony
Types and Apps Hungarian
Hex-coding
Errors
URL Slugs
Repository Tails and Related Repositories

The Kiln API operates over HTTP; it takes and receives JSON data. HTTP POST is used when the API mutates data on the server, and HTTP GET is used everywhere else.

URLs and Parameters

All API URLs have a {version} placeholder for you to specify the API version you're developing against. For example, if you see "Api/{version}/Auth/Login" and you're developing against API 1.0, you should query "Api/1.0/Auth/Login" instead. Many API calls also take parameters. If the call in question uses HTTP GET, you should pass the parameters using the question-mark-and-ampersands syntax:

Api/1.0/Auth/Login?sUser=Administrator&sPassword=fogcreek

for example. This format is an URI query string; as such you will need to employ your programming language's libraries to correctly URL encode the parameters.

If the call instead uses HTTP POST, you should not use that syntax but instead pass the arguments in the request body, except without the question mark. For example, sending an HTTP POST to "Api/1.0/RepoGroup/1" with a body of "sName=example&token=1234abcd".

Some calls will require you to pass a list of arguments. The way you do this in an URI query string is by repeating the parameter. For example, passing the list "ixPersons":

ixPersons=1&ixPersons=2&ixPersons=3

Kiln Harmony

Kiln Harmony allows you to retrieve either Mercurial or Git commit data. A "vcs" URL query-string parameter is always available to you, on any API request. Passing "vcs=hg" will set your per-user view of changeset data to Mercurial; passing "vcs=git" will set it to Git. This might be useful if you're writing code that depends on a particular version-control system. For example, changing the vcs changes the "rev", "revParent1", and "revParent2" changeset hashes on the changeset records.

If no vcs parameter is specified, Mercurial data will be returned.

Types and Apps Hungarian

In the API, whenever a variable is passed or returned, the variable name will be written in Apps Hungarian, which means the name begins with a prefix telling you what kind of object you're dealing with. These prefixes are:

Prefix	Description
s UTF-8 string	UTF-8 is the only encoding Kiln returns and takes. When other encodings are needed, byte paths or byte strings (see below) are used.
code machine code	An ASCII string representing a machine code error (see below).
ix index	An integer representing the index of another object in the database or in an array.
bs byte string	A text string in any encoding or even a binary string. Used in situations where Kiln is not aware of the encoding but the user is. For example, a changeset diff's contents.
bp byte path	This is the string hexadecimal representation of a file path that has been hex-encoded (see below). Certain file paths are hex-encoded because Kiln is unable to decode or encode them as UTF-8 or because they are a reserved name.
rev revision	The checksum Mercurial assigns to a revision (such as 9910837f279a01f2ca3d3a6cf4f11a7f742c9086) or a sufficiently long prefix of the checksum (such as 9910837f279a). You may also use "tip", which corresponds to the tip revision.
dt date	A string representing a date in ISO 8601 format. You should use your programming language's ISO 8601 date library to parse this string.
f boolean	A string representing a boolean value. Accepts two values: true or false.
permission	A string representing one of the valid permissions: "none", "read", "readbranch", "write", "inherit", or "admin". See Permissions. Note: read + branch was added in Kiln 2.5.96.
person	A person record.
project	A project record.
repoGroup	A repository group record.
repo	A repository record.
review	A review record.

If the variable is a list of objects, then its name is plural. We chose Apps Hungarian because the API traffics in a zoo of different objects that would be difficult to distinguish in the typeless JSON format.

Hex-coding

A bytestream is hex-encoded by mapping each byte to its hexadecimal character representation (0-9A-F) and then joining all the characters together into an ASCII string. For example, in Python:

def hexencode(bytestr):

return ''.join("%02X" % ord(x) for x in bytestr)

And in C#:

public static string HexEncode(string str)

{

var bytes = (new UTF8Encoding()).GetBytes(str);

return String.Join("", bytes.Select(b => String.Format("{0:X2}", b)).ToArray());

}

Note that you can only hex-encode byte strings, not Unicode strings. If your programming language represents Unicode strings in a format different from UTF-8, you'll need to first encode it into a UTF-8 byte string and then hex-encode it. Hex-decoding is then the reverse of this:

def hexdecode(hexstr):

return ''.join(chr(int(hexstr[i:i+2], 16)) for i in xrange(0, len(hexstr), 2))

The C# version is left as a fun exercise to the reader.

Errors

Many API calls can return errors, which are noted in the documentation. Errors are encapsulated in a record, whose only key is "errors", which corresponds to a list of error records. Each error record contains two keys:

codeError: a short machine code for the error, like "ProblemWithBackend"
sError: the descriptive error message string, like "An unknown problem with the backend occurred. We've been notified."

If you need to detect a specific error, "codeError" is the way to go. "sError" is provided to aid debugging. Note that multiple errors can occur, which is why errors are present in a list. An example of a returned errors record is

{

"errors":

    [{"codeError": "BranchRepoMustHaveParent",

      "sError": "Branch repositories must have parent repositories."},

     {"codeError": "CannotUseReservedFileName",

      "sError": "Reserved filenames [snip] cannot be used at the start of this field."},

     {"codeError": "RepoNameHasInvalidChars",

      "sError": "Repository names can only include: [snip]."}]

}

URL Slugs

Projects, repository groups, and repositories have URL slugs, which are short alphanumeric representations of their names used in Kiln URLs and are returned . For example, in the URL "http://username.kilnhg.com/Repo/Projects/Aardvark/Snout", which links to the History view for a repository named "Snout", you can see the project slug is "Projects", the repository group slug is "Aardvark", and the repository slug is "Snout". Slugs are read-only and can only be changed by the Kiln server when you modify the slug object's name. Slugs are usually returned in the standard GET calls for projects, repository groups, and repositories.

Repository Tails and Related Repositories

Mercurial has a concept of tails, which is where a repository's directed acyclic graph of nodes begins. A repository usually has only one tail, the changeset where the repository was branched, but it can have more due to edge cases such as Subversion imports. In the Kiln, we say that two repositories are related if the set of tails from the first repository has a non-empty intersection with the set of tails from the second repository; i.e. the two repositories share a tail changeset. Relatedness is one of the criteria used to determine whether one repository can be compared or pushed to another, which is in place to prevent the user from splicing together two repository histories in a way Kiln doesn't understand.

Wiki