API description example

api.md

REST API v1

It's definitely a work in progress.

Inspired by Github API v3 and Gitlab API.

Projects:

1. List your own projects
1. List projects owned by a user
1. Get a single project

Tickets:

1. List tickets for a project
1. Get a single ticket

Events:

1. List events or comments for a ticket
1. Get a single event or comment

PROJECTS

All projects live in user namespace, i.e., two users can have independent projects with same name. E.g., users Mary and Tom both can have a project called "Blog". Their tickets and properties won't be intermixed.

Projects have at its core:

- a owner
- name

List your own projects

GET /user/projects

List projects owned by a user

GET /users/:username/projects

Get a single project

GET /projects/:owner/:project

Example:

{
    "url": "http://api.example.com/projects/mary/blog",
    "html_url": "http://example.com/projects/mary/blog",
    "owner_url": "http://api.example.com/users/mary",
    "tickets_url": "http://api.example.com/projects/mary/blog/tickets",
    "name": "blog",
    "state": "opened",
    "created_at": "2018-06-01T15:31:39Z",
    "owner": {
        "username": "mary",
        "url": "http://api.example.com/users/mary"
    },
}

TICKETS

All tickets exist in a project. It's their context.

Core characteristics of a ticket:

- related to a project
- a number (not it's internal id)
- events (state change, commentaries, mentions and updates)

List tickets for a project

GET /projects/:owner/:project/tickets

Get a single ticket

GET /projects/:owner/:project/tickets/:number

Example:

{
    "url": "http://api.example.com/projects/mary/blog/tickets/1745",
    "html_url": "http://example.com/projects/mary/blog/tickets/1745",
    "comments_url": "http://api.example.com/projects/mary/blog/tickets/1745/comments",
    "events_url": "http://api.example.com/projects/mary/blog/tickets/1745/events"
    "number": 1745,
    "id": 194898977,
    "title": "Register a customer",
    "state": "opened",
    "body": "All content typed by user. Markdown, btw.",
    "created_at": "2018-06-01T15:31:39Z",
    "last_updated_at": "2018-06-01T15:31:39Z",
    "last_closed_at": null,
    "author": {
        "username": "mary",
        "url": "http://api.example.com/users/mary"
    },
    "last_updated_by": {
        "username": "mary",
        "url": "http://api.example.com/users/mary"
    },
    "last_closed_by": null,
}

EVENTS

List events or comments for a ticket

GET /projects/:owner/:project/tickets/:number/events
GET /projects/:owner/:project/tickets/:number/comments

Get a single event or comment

GET /projects/:owner/:project/tickets/:number/events/:id
GET /projects/:owner/:project/tickets/:number/comments/:id

An event type can be comment, mention, action or update.

For a comment:

{
    "url": "http://api.example.com/comments/345678908",
    "html_url": "http://example.com/projects/mary/blog/tickets/1745#345678908",
    "ticket_url": "http://api.example.com/projects/mary/blog/tickets/1745",
    "id": 345678908,
    "text": "I agree with you.",
    "type": "comment",
    "created_at": "2018-06-01T15:31:39Z",
    "last_updated_at": "2018-06-01T15:31:39Z",
    "author": {
        "username": "mary",
        "url": "http://api.example.com/users/mary"
    },
}

For an action:

{
    "url": "http://api.example.com/projects/mary/blog/tickets/1745/events/345678321",
    "html_url": "http://example.com/projects/mary/blog/tickets/1745#345678321",
    "ticket_url": "http://api.example.com/projects/mary/blog/tickets/1745",
    "id": 345678321,
    "text": "close",
    "type": "action",
    "created_at": "2018-06-01T15:31:39Z",
    "author": {
        "username": "mary",
        "url": "http://api.example.com/users/mary"
    },
}

For a mention:

{
    "url": "http://api.example.com/projects/mary/blog/tickets/1745/events/111678321",
    "html_url": "http://example.com/projects/mary/blog/tickets/1745#111678321",
    "ticket_url": "http://api.example.com/projects/mary/blog/tickets/1745",
    "id": 111678321,
    "text": "#14",
    "type": "mention",
    "created_at": "2018-06-01T15:31:39Z",
}

For an update:

{
    "url": "http://api.example.com/projects/mary/blog/tickets/1745/events/345678321",
    "html_url": "http://example.com/projects/mary/blog/tickets/1745#345678321",
    "ticket_url": "http://api.example.com/projects/mary/blog/tickets/1745",
    "id": 345678321,
    "text": "{'old': {'title': 'old title', 'body': 'old body'}, 'new': {'title': 'new title', 'body': 'new body'}}",
    "type": "update",
    "created_at": "2018-06-01T15:31:39Z",
    "author": {
        "username": "mary",
        "url": "http://api.example.com/users/mary"
    },
}