API Specification - v1

Ticktack has a RESTful API that any authorised user can use.

Below is the specification

Calling the API

You need to authenticate with a user. You can use the same user that you log in with, or you can use apiuser/apipassword for a slightly restricted result set (not implemented yet).

You can use any application to call the API, but I will assume command-line cURL requests:

$ curl --user apiuser:apipassword http://ticktack.pedanticantic.click/api/v1/<resource>

On the production system, the Project "TickTack" and all descendant records are completely read-only for all users. You will not even be able to add a comment to a ticket in that project.

Resources

/api/v1/referenceData

GET: /api/v1/referenceData to return the static reference data - various types, priorities, etc

/api/v1/user

GET: /api/v1/user to return all users that are visible to you. You can filter on:

/api/v1/project

GET: /api/v1/project/{id} to return the project with that id
GET: /api/v1/project to return all projects, with optional filters: POST: /api/v1/project to create a project: PUT: /api/v1/project/{id} to update the project with that id.
See POST above for valid fields.

DELETE: /api/v1/project/{id} to delete the project with that id.
GET: /api/v1/project/{id}/ticket to return all tickets, with optional filters
See "GET: /api/v1/ticket" below, with tickets filtered on the given project_id.

POST: /api/v1/project/{id}/ticket to create a ticket in the given project
See "POST: /api/v1/ticket" below, with the project_id deemed to be the one in the URL.

/api/v1/ticket

GET: /api/v1/ticket/{id} to return the ticket with that id
GET: /api/v1/ticket to return all tickets, with optional filters: Returned sets of tickets are sorted by id and include any assignments, comments and relationships to other tickets

POST: /api/v1/ticket to create a ticket: PUT: /api/v1/ticket/{id} to update the ticket with that id.
See POST above for valid fields.
Use "-" to clear optional fields (due_datetime and estimated_length_seconds) DELETE: /api/v1/ticket/{id} to delete the ticket with that id.

/api/v1/ticket/{id}/assignment/{user_id}

POST: ticket/{id}/assignment/{user id} to assign the given user to the given ticket. Fields:
Returns an error if the user is already assigned.
Returns the new assignment id on success.

/api/v1/assignment/{id}[/{direction}]

DELETE: /api/v1/assignment/{id} to remove the given assignment
Returns an error if assignment does not exist.

PUT: /api/v1/assignment/{id}/{direction} to move the assignment up or down within the ticket. Various error messages are returned. If successful, the new sort order is returned.

/api/v1/ticket/{id}/comment

GET: /api/v1/ticket/{id}/comment/{id} to retrieve a specific comment
GET: /api/v1/ticket/{id}/comment to retrieve all comments on the ticket, with optional filters
GET: /api/v1/comment to retrieve all comments in the system, with optional filters
Filters: POST: /api/v1/ticket/{id}/comment to create a comment against the given ticket
Currently, comments cannot be modifed nor deleted.

/api/v1/ticket/{id}/associated

Note: Relationships are always associated with 2 tickets. When accessing a relationship, you need to specify which ticket is the "source". It is important because, for example, if ticket A is a parent of ticket B, and you retrieve the relationship stating that B is the source, the relationship type will be "child". Also, if you change the sort order, it's the one as seen from the ticket that you say is the source.

GET: /api/v1/ticket/{id}/associated/{id} to retrieve a specific relationship
GET: /api/v1/ticket/{id}/associated to retrieve all relationship on the ticket, with optional filters
Filters: POST: /api/v1/ticket/{id}/associated to create a relationship against the given ticket
Fields as as per the filters above. is_pinned defaults to no.

DELETE: /api/v1/ticket/{id}/associated/{id} to delete the relationship. All sort orders will be updated as necessary.

PUT: /api/v1/ticket/{id}/associated/{relationship_id}/{action}: perform the action on the given relationship, where the ticket is the source ticket. action can be one of: