Structure of REST requests

The access url is of the form:

  {rest-prefix}/{action-name}/{path}?{parameters}

Where

rest-prefix is the start of the URL which identifies the organization to be accessed; find it by calling https://vimaly.com/rest/2/directory/{orgId} where {orgId} is the unique id assigned to your organization. This can be found on the Organization>General settings page.
action-name, path, and parameters are as described in this document

Basic authentication can used to access the resources by supplying the email (lower-case) and password. If using an API key instead append the query parameter key=yourAPIKey

When using an API key for put, post and delete you must also append the query parameter userId=recordUserId which will run the action under the user corresponding to the _id recordUserId.

Responses are in the form of http status codes and JSON data.

An example using wget with email and password:

  wget --http-user=geoff@vimaly.com --http-password=secret \
   https://h0123.vimaly.com/rest/2/trnkz/users

  => SUCCESS [200] (application/json)
     [{
       "_id":"aghg8HKi2rzMzygiW",
       "name":"Russell Healy",
       "email":"russell@vimaly.com",
       "initials":"RH"
     },{
       "_id":"juFEJpcvmbHiAZYuD",
       "name":"Geoff Jacobsen",
       "email":"geoff@vimaly.com",
       "initials":"GJ"
     }]

An example using curl API key:

  curl https://h0123.vimaly.com/rest/2/trnkz/users?key=ds62GDS4ds423DF24432D45s2324

  => SUCCESS [200] (application/json)
    [...]

Format of put request body

The put request body can updated parts of fields in a section call $partial. The format of the $partial sections is:

          {
            topLevelField1: [
              cmdOrSubField1, value,
              cmdOrSubField2, value,
              ...
            ],
            topLevelField2: [...],
            ...
          }

where topLevelFieldn is the name of a top-level field such as: name, checklists and cmdOrSubFieldn can be a sub-level field such as: checklistId123.items.itemId456.name, customFieldId123; or one of the commands:

$match {valueOrHash} - assert that current value matches {valueOrHash}. {valueOrHash} can be the full contents of the current value or either an md5 or sha256 hash or arbitary length up to the full sum length.

example

              name: ['$match', 'old name'] or
              name: ['$match', {md5: '58a5352c62'}] or
              name: ['$match', {sha256: '2b727fb85cff'}]

              estimatedDuration: ['$match', [5, 'days]]

$replace {newValue} - replace with {newValue}
$prepend {text} - prepend text to the start of a text field
$prepend {value} - prepend a value to a list field
$append {text} - append text to the end of a text field
$append {value} - append a value to a list field
$add {value} - add a value to a list if not already in list
$remove {value} - remove a value from a list if present
$patch [{instruction}, {instruction}, ...] - modify the contents of a sequence (string or list) using the following format for {instruction}:
{moveForward}, {deleteNext}, {insertSequence}
- {moveForward} - starting from previous posistion (0 if first instruction) add {moveForward} to posistion
- {deleteNext} - delete next {deleteNext}s sequence items
- {insertSequence} - insert the {insertSequence} at the current position and update position to end of {insertSequence}
example
```
{name: ['$match', 'Austin', '$patch', [0, 0, 'Jane ', 5, 1, 'e']]} => name: 'Jane Austen'
```

top-level field name follow

Actions

All action requests start after the {rest-prefix} (see above). Parameters can be passed in the URL and also in the body as JSON data; URL parameters take precendence for any duplicate values also in the body

/ids

When new records are created unique ids must be supplied by the caller. This is so that the POST commands can be resent multiple times without creating multiple records.

This command supplies the client with a list of suitable ids to use.

methods

GET /ids?amount={amount}

Return a list of ids

parameter	description
`amount` (optional - defaults to 4)	The number of ids to return; must be between 1 and 100

response

200 - application/json

example

  ["QQa28StuRkeSiBPBR","oHhqwoMCgJLa2SCam","ig22QAox8Q3MiuSEq"]

/users

Retrieve details about users.

Methods

GET /users/{_id or email}

Return details for specified user

parameter	description
_id	The user _id
email	The user email address

response

200 - application/json

example

  {
    "_id":"aghg8HKi2rzMzygiW",
    "name":"Russell Healy",
    "email":"russell@vimaly.com",
    "initials":"RH"
  }

404 - "Not found"

GET /users

Return list of users for the organization

response

200 - application/json

example

  [{
    "_id":"aghg8HKi2rzMzygiW",
    "name":"Russell Healy",
    "email":"russell@vimaly.com",
    "initials":"RH"
  },{
    "_id":"juFEJpcvmbHiAZYuD",
    "name":"Geoff Jacobsen",
    "email":"geoff@vimaly.com",
    "initials":"GJ"
  }]

/custom-fields

Retrieve details about custom fields.

Methods

GET /custom-fields/{_id}

Return details for specified custom field

parameter	description
_id	The custom field _id

response

200 - application/json

type is: 1: text, 2: decimal, 3: integer, 4: list

example

  {
    "_id":"PGNCrjE4oyjXvzi2h",
    "name":"Complexity",
    "type":3
  }

404 - "Not found"

GET /custom-fields

Return list of custom fields for the organization

response

200 - application/json

example

  [{
    "_id":"PGNCrjE4oyjXvzi2h",
    "name":"Complexity",
    "type":3
  }, {
    "_id":"rt2Rj66Y9fTT7xHZx",
    "name":"Close reason",
    "type":4,
    "options":[{
      "id":1,
      "name":"Fixed",
      "order":128
    }, {
      "id":2,
      "name":"Duplicate",
      "order":256,
      "disabled":true
    }, {
      "id":3,
      "name":"Wont Fix",
      "order":384
    }]}
  ]

/ticket-types

Retrieve details about ticket types.

Methods

GET /ticket-types/{_id}

Return details for specified ticket type

parameter	description
_id	The ticket type _id

response

200 - application/json

field	description
`color`	The background color for tickets of this type
`disabled` (optional)	This ticket type should not be used for new tickets
`{standard-field}` (optional)	A standard-field is any of the following: estimatedDuration: type: interval estimatedEffort: type: effort estimatedEffortRemaining: type: effort estimatedCost: type: currency actualCost: type: currency plannedStartDate: type: date actualStartDate: type: date dueDate: type: date completedDate: type: date and have a value of either "optional" or "alwaysShow" where "alwaysShow" indicates that the ticket should always present the field as opposed to "optional". The types effort and currency have additional fields effort has a "units" field like estimatedEffortUnits and estimatedEffortRemainingUnits and can be either "points" or "interval". currency has a "currency" field like estimatedCostCurrency and actualCostCurrency. Currencies are ISO 4217 three letter codes like USD and EUR
`customFields` (optional)	Map of the custom field available for this ticket type
`customFields.{_id}`	The _id of a custom field
`customFields.{_id}.order`	The order to present this custom field in a list
`customFields.{_id}.alwaysShow`	Custom field is shown on all tickets of this ticket type

example

  {
    "_id":"omCx7PZMAbZxFSf3a",
    "name":"Defect",
    "color":"#88ffff",
    "estimatedEffort": "optional",
    "estimatedEffortUnits": "interval",
    "actualCost":"alwaysShow",
    "actualCostCurrency":"NZD",
    "customFields":{
      "zAFA7t32HcyLYkzn8":{
        "order":-320
      },"EvSCsej8qJeQHLJo4":{
        "order":576,"alwaysShow":true
      },"nMGsF638LdArbKBiW":{
        "order":704
      }
    }
  }

404 - "Not found"

GET /ticket-types

Return list of ticket types for the organization

response

200 - application/json

example

  [{
    "_id":"SaJKSZDwpHfTuKb93",
    "name":"Enhancement",
    "color":"#88ffff",
    "customFields":{
      "EMWS9CpZnJc4Ei256":{
        "order":128
      }
    }
  },{
    "_id":"omCx7PZMAbZxFSf3a",
    "name":"Defect",
    "color":"#ffff88",
    "customFields":{
      "zAFA7t32HcyLYkzn8":{
        "order":-320
      },"EvSCsej8qJeQHLJo4":{
        "order":576,"alwaysShow":true
      },"nMGsF638LdArbKBiW":{
        "order":704
      }
    }
  }]

/bins

Retrieve details about bins.

Methods

GET /bins/{_id}

Return details for specified bin

parameter	description
_id	The bin _id

response

200 - application/json

field	description
`color`	The background color of the bin
`wipLimit` (optional)	Maximum number of tickets in this bin until a warning shows

example

  {
    "_id":"wi8NwSQqEB3bYp9Jr",
    "name":"ops.exp.Expedite Issues Queue",
    "color":"#ffffff",
    "wipLimit":4
  }

404 - "Not found"

GET /bins

Return list of bins for the organization

response

200 - application/json

example

  [{
    "_id":"6eAwSbzp2EXjBk42b",
    "name":"ops.exp.Done",
    "color":"#b3b3b3"
  },{
    "_id":"wi8NwSQqEB3bYp9Jr",
    "name":"ops.exp.Expedite Issues Queue",
    "color":"#ffffff",
    "wipLimit":4
  }]

/tickets

Retrieve details about tickets.

Methods

GET /tickets/{_id}?rtformat=text|html

Return details for specified ticket

parameter	description
_id	The ticket _id
rtformat	If set to html returns the ticket description as html markup

response

200 - application/json

field description

bin_id The id for the bin the ticket is in

ticketType_id The id for the ticket-type of this ticket

order The position of the ticket within the bin

assigned_ids List of user ids assigned to this ticket

watch_ids List of user ids watching this ticket

{standard-field}

Any or all of the standard fields (see Ticket types for a definition). Depending on a field's type it has the following format:

type	format
"interval" (or "effort" with unit of "interval")	`[{number}, {unit}]` where {unit} is one of `"mins", "hrs", "days", "wks"`
"effort" (with unit of "points")	`[{number}, "pts"]`
"curency"	`[{decimal}, {currency}]` where {decimal} is a string of digits with an optional decimal point and {currency} corresponds to the standard-field's currency from the ticket's ticket-type
"date"	`"yyyy-mm-dd"`; a string of the date at UTC zero-hundred hours. This date may appear differently for different time-zomes; typically New Zealand will show a day earlier.

checklists (optional) A map of checklists

checklists.{cl_id} A checklist. cl_id should be unique

checklists.{cl_id}.items A map of items for the checklist

checklists.{cl_id}.items.{item_id} A map of items for the checklist

checklists.{cl_id}.items.{item_id}.checked Present and true if the item is complete

customFields (optional) A map of custom fields

customFields.{cf_id} The value of a custom field. The cf_id determines which custom-field. The value is determined using the custom field's type

example

  {
    "_id":"bnmhbDwPkagsKnisN",
    "name":"Select a group of bins",
    "bin_id":"9P3ubgAqygpr2kmKW",
    "ticketType_id":"XxcXo2NQq3sHcuMfW",
    "order":128,
    "estimatedDuration":[3, "days"],
    "estimatedEffort":[2.5, "pts"],
    "actualCost":["123.45", "EUR"],
    "plannedStartDate":"2015-12-31",
    "checklists":{
      "gget6HRPhy65gg95d":{
        "name":"Acceptance tests",
        "order":100,
        "items":{
          "QpqssantGFinDP4Y5":{
            "name":"Can use ctrl-click to add to selection",
            "order":100,
          },
          "g9dekhFwsZxiTcAwR":{
            "name":"Can move bins together",
            "order":200,
            "checked":true
          }
        }
      }
    },
    "customFields":{
      "QaGQsdXHZkiRBMfom": 2
      "HHzNciedfaRmaymng": "E123TWS"
    }
  }

404 - "Not found"

GET /tickets?bin_id={bin_id}

Return list of tickets for the specified bin_id

response

200 - application/json

example

  [{"_id":"LWWRDuSZrjzxqW7fL",
    "name":"Widgets are broken",
    "bin_id":"9P3ubgAqygpr2kmKW",
    "ticketType_id":"XxcXo2NQq3sHcuMfW",
    "order":64
   },{
     "_id":"bnmhbDwPkagsKnisN",
     "name":"Select a group of bins",
     "bin_id":"9P3ubgAqygpr2kmKW",
     "ticketType_id":"XxcXo2NQq3sHcuMfW",
     "order":128,
     "checklists":{
       "gget6HRPhy65gg95d":{
         "name":"Acceptance tests",
         "order":100,
         "items":{
           "QpqssantGFinDP4Y5":{
             "name":"Can use ctrl-click to add to selection",
             "order":100,
           },
           "g9dekhFwsZxiTcAwR":{
             "name":"Can move bins together",
             "order":200,
             "checked":true
           }
         }
       }
     },
     "customFields":{
       "QaGQsdXHZkiRBMfom": 2
       "HHzNciedfaRmaymng": "E123TWS"
     }
   }
  ]

400 - application/json {bin_id: [["is_required"], ["is_invalid"]]} - or access not allowed

PUT /tickets/{_id}?{fields}

Update details for specified ticket. Fields can be sent as parameters or a JSON body. Only specifiy the fields to be changed.

parameter	description
_id	The ticket _id

field	description	example
`name`	The name of the ticket
`rtformat`	The description is 'text' or in 'html' markup format
`description`	The description for the ticket
`bin_id`	The id for the bin the ticket is in
`ticketType_id`	The id for the ticket-type of this ticket
`order`	The position of the ticket within the bin
`assigned_ids.$+{count}`	(Deprecated) Assign a user to this ticket using the user's id. (`count` is number to make the key unique)
`assigned_ids.$-{count}`	(Deprecated) Unassign a user to this ticket using the user's id. (`count` is number to make the key unique)
`watch_ids.$+{count}`	(Deprecaetd) Set user as a watcher of this ticket using their id. (`count` is number to make the key unique)
`watch_ids.$-{count}`	(Deprecated) Unset user as a watcher of this ticket using their id. (`count` is number to make the key unique)
`{standard-field}`	See GET /tickets/{_id}
`checklists.{cl_id}`	(Deprecated) Add a new checklist. `cl_id` should be unique	{ "checklists.uBw3JKT76oFmL8guK": {"name": "Checklist name", "order": 100} }
`checklists.{cl_id}.items.{item_id}`	Add a new checklist item
`checklists.{cl_id}.items.{item_id}.checked`	check (true) / uncheck (false) an item
`customFields.{cf_id}`	Set the value of a custom field. The `cf_id` determines which custom-field. The value is determined using the custom field's type. For lists use the option's id

response

204 - No content - update was successful

400 - application/json {<field>: [<list-of-errors>], ...} A map of field errors found

404 - "Not found"

POST /tickets/{_id}?{fields}

Create a ticket with the specified fields. Fields can be sent as parameters or a JSON body.

parameter	description
_id	A unique id for the ticket

field	description
`name` (required)	The name of the ticket
`rtformat`	The description is 'text' or in 'html' markup format
`description`	The description for the ticket
`bin_id` (required)	The id for the bin the ticket is in
`ticketType_id` (required)	The id for the ticket-type of this ticket
`order`	The position of the ticket within the bin - defaults to end of list
`assigned_ids`	A list of user_ids to assign to this ticket
`watch_ids`	A list of user_ids that are watching this ticket
`{standard-field}`	See GET /tickets/{_id}
`checklists`	A map of checklists in the form: `{cl_id: { name: "name of checklist", order: position when listed, items: {it_id: { name: "name of item", order: position when listed, checked: true or false }, ...}}, ...}` where `cl_id` and `it_id` are unique ids.
`customFields`	A map of customFields in the form: `{cf_id: value, ...}` where `cf_id` is the id of a custom field and `value` is conforming the custom form's type. The `cf_id` should correspond to a custom-field set in the ticket-type but this is not enforced.

response

204 - No content - Creation was successful

400 - application/json {<field>: [<list-of-errors>], ...} A map of field errors found

400 - application/json {_id: [["is_invalid"], ["already_exists"], ["not_unique"]]} already_exists indicates a ticket already has this id

Vimaly REST version 1 API documentation

Tabel of contents

Structure of REST requests

Format of put request body

example

example

Actions

/ids

methods

GET /ids?amount={amount}

response

example

/users

Methods

GET /users/{_id or email}

response

example

GET /users

response

example

/custom-fields

Methods

GET /custom-fields/{_id}

response

example

GET /custom-fields

response

example

/ticket-types

Methods

GET /ticket-types/{_id}

response

example

GET /ticket-types

response

example

/bins

Methods

GET /bins/{_id}

response

example

GET /bins

response

example

/tickets

Methods

GET /tickets/{_id}?rtformat=text|html

response

example

GET /tickets?bin_id={bin_id}

response

example

PUT /tickets/{_id}?{fields}

response

POST /tickets/{_id}?{fields}

response