API Idioms

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());

}

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."

{

  "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.