Issue Tracker API Docs

Welcome to the Issue Tracker API docs!

API base:

https://issuetracker-api.connectnow.org.uk

IMPORTANT

Make sure to familiarize yourself with the API philosophy before proceeding with this guide.

Authentication

Getting an API token

See User Guide - getting tokens

Authenticating requests

See: API Philosophy - authentication

Response Status Codes

See: API Philosophy - status codes

Issues

Get all public issues

GET /api/issues

Parameter	Type	Rules	Default	Description
with	array	Can be any combination of: categories, categories.company, events	-	What related objects to append to the JSON response
company_ids	array	Must be an existing ID	-	Filter by the company IDs
category_ids	array	Must be an existing ID	-	Filter by category IDs
after	string	Date formatted as YYYY-MM-DD	-	Only only issues after this date
before	string	Date formatted as YYYY-MM-DD	-	Only return issues before this date
severity	string	Must be one of: critical, important, info	-	Filter by the level of severity
status	string	open or closed	-	Return issues with only the passed status

Sample response:

{
	"current_page": 1,
	"data": [
		{
			"id": 66,
			"name": "Bad printers on floor 2",
			"severity": "info",
			"closed_at": null,
			"created_at": "2021-04-26T22:25:35.000000Z",
			"updated_at": "2021-04-26T22:25:35.000000Z"
		}
	],
	"first_page_url": "http://127.0.0.1:8000/api/issues?page=1",
	"from": 1,
	"next_page_url": "http://127.0.0.1:8000/api/issues?page=2",
	"path": "http://127.0.0.1:8000/api/issues",
	"per_page": 15,
	"prev_page_url": null,
	"to": 15
}

Create a issue

Authorization required

You must have access to each company from the submitted category ids.

All authorization requests require you to first be authenticated.

POST /api/issues

Parameter	Type	Rules	Required	Default	Description
category_ids	array	Must contain existing IDs	✅	-	Category IDs the issue belongs to
name	string	Text	✅	-	The name of the issue
description	string	Text	✅	-	A description of the current status/situation of the issue
severity	string	Must be one of: critical, important, info	✅	-	The level of severity

Sample response:

{
	"id": 1,
	"name": "Server login issues",
	"severity": "critical",
	"created_at": "2021-04-26T13:46:46.000000Z",
	"updated_at": "2021-04-26T13:46:46.000000Z"
}

Get a single issue

GET /api/issues/{issue-id}

Parameter	Type	Rules	Default	Description
with	array	Can be any combination of: categories, categories.company, events	-	What related objects to append to the JSON response

Sample response:

{
	"id": 1,
	"name": "Server login issues",
	"severity": "critical",
	"closed_at": null,
	"subscribers_count": 15,
	"created_at": "2021-04-26T13:46:46.000000Z",
	"updated_at": "2021-04-26T13:46:46.000000Z"
}

Edit a single issue

Authorization required

You must have access to each company in the issue category ids. If updating category ids, you must additionally have access/permission for any new category ids submitted.

All authorization requests require you to first be authenticated.

TIP

If the issue is already closed, you will receive a 403 response.

PUT /api/issues/{issue-id}

Parameter	Type	Rules	Required	Default	Description
category_ids	array	Must contain existing IDs	✅	-	Category IDs the issue belongs to. If this parameter is passed, ID's will be synced, meaning those not present in the request array will be removed from the issue
name	string	Text	✅	-	The name of the issue
description	string	Text	✅	-	A description of the current status/situation of the issue
severity	string	Must be one of: critical, important, info	✅	-	The level of severity

Close a single issue

Authorization required

User must be authenticated and have access to each company in the issue category ids.

All authorization requests require you to first be authenticated.

TIP

If the issue is already closed, you will receive a 403 response.

POST /api/issues/{issue-id}/close

Parameter	Type	Rules	Required	Default	Description
description	string	Text	✅	A description of the current situation of the issue

Delete a single issue

Authorization required

User must be authenticated and have access to each company in the issue category ids.

All authorization requests require you to first be authenticated.

DELETE /api/issues/{issue-id}

Issue/category subscriptions

TIP

To subscribe to categories instead: use categories in place of issues in this section.

Subscribe

POST /api/issues/{issue-id}/subscriptions

Parameter	Type	Rules	Required	Default	Description
email	string	A valid email address	✅	-	Category IDs the issue belongs to

If the subscription does not exist, it will be created and a confirmation email will be sent to the user. The API returns a 201 CREATED status code.

If the subscription exists (even if not confirmed) no emails are sent and the API returns a 200 OK status code.

Confirm subscription

You must confirm a subscription by following the signed URL in the email sent.

Unsubscribe/delete a subscription

You must delete a subscription by following the signed URL at the bottom of every notification email sent.

Categories

Get all public categories

GET /api/categories

Parameter	Type	Rules	Default	Description
with	array	Can be any combination of: company, issues	-	What related objects to append to the JSON response
company_ids	array	Must be an existing ID	-	Filter by the company IDs

Create a category

Authorization required

User must be authenticated and have access to the company.

All authorization requests require you to first be authenticated.

POST /api/categories

Parameter	Type	Rules	Required	Default	Description
name	string	Text	✅	-	The name of the category
company_id	string	Must be an existing company ID	✅	-	The company ID this category belongs to

Get a single category

GET /api/categories/{category-id}

Sample response:

{
  "id": 1,
  "name": "IT department",
  "company_id": 1,
  "created_at": "2021-07-05T09:31:38.000000Z",
  "updated_at": "2021-08-17T11:42:25.000000Z"
}

Edit a single category

Authorization required

User must be authenticated and have access to the company that the category belongs to.

All authorization requests require you to first be authenticated.

PUT /api/categories/{category-id}

Parameter	Type	Rules	Required	Default	Description
name	string	Text	✅	-	The name of the category

Delete a single category

Authorization required

User must be authenticated and have access to the company that the category belongs to.

All authorization requests require you to first be authenticated.

DELETE /api/categories/{category-id}

Companies

Get all public companies

GET /api/companies

Parameter	Type	Rules	Default	Description
with	array	Can be any combination of: categories, issues	-	What related objects to append to the JSON response

Create a company

Authorization required

You must be authorized to access this resource

All authorization requests require you to first be authenticated.

POST /api/companies

Parameter	Type	Rules	Required	Default	Description
name	string	Text	✅	-	The name of the category
logo_url	string	URL	-	-	The URL to a company logo

Get a single company

GET /api/companies/{company-id}

Sample response:

{
  "id": 1,
  "name": "ConnectNow",
  "created_at": "2021-07-05T09:31:38.000000Z",
  "updated_at": "2021-08-17T11:42:25.000000Z"
}

Edit a single company

Authorization required

User must be authenticated and have access to the company.

All authorization requests require you to first be authenticated.

PUT /api/companies/{company-id}

Parameter	Type	Rules	Required	Default	Description
name	string	Text	-	-	The name of the category
logo_url	string	URL	-	-	The URL to a company logo
slug	string	Text, not already registered	-	-	The company slug

Delete a single company

Authorization required

User must be authenticated and have access to the company.

All authorization requests require you to first be authenticated.

DELETE /api/companies/{company-id}

Authorization: user must be authenticated and have access to the specified company.

Company users

Get all company users

Authorization required

You must be authorized to access this company

All authorization requests require you to first be authenticated.

GET /api/companies/{company-id}/users

Add a company user

Authorization required

You must be authorized to access this company

All authorization requests require you to first be authenticated.

POST /api/companies/{company-id}/users

Parameter	Type	Rules	Required	Default	Description
email	email	Email	✅	-	The email of the person you want to invite

Delete a company user

Authorization required

You must be authorized to access this company

All authorization requests require you to first be authenticated.

TIP

The company-user-id is not the same as the user-id field. The company-user-id can commonly be found on the pivot object

DELETE /api/companies/{company-id}/users/{company-user-id}

Webhooks

Authorization required

User must be authenticated for all webhook endpoints and methods.

All authorization requests require you to first be authenticated.

Get all webhooks

GET /api/webhooks

Create a webhook

POST /api/webhooks

Parameter	Type	Rules	Required	Default	Description
url	string	Valid URL, unique	✅	-	The webhook url
description	string	Text	-	-	The description of what the webhook is for

Get a single webhook

GET /api/webhooks/{webhook-id}

Sample response:

{
  "id": 1,
  "user_id": 1,
  "url": "https:\/\/hooks.slack.com\/workflows\/12345678ABCDEFG",
  "description": "Slack Workflow webhook",
  "created_at": "2021-07-27T19:19:09.000000Z",
  "updated_at": "2021-07-27T19:19:09.000000Z"
}

Edit a single webhook

PUT /api/webhooks/{webhook-id}

Parameter	Type	Rules	Required	Default	Description
name	string	Text	✅	-	The name of the category

Delete a single webhook

DELETE /api/webhooks/{webhook-id}

Available webhook events

webhook_created

Sends an event to the user when a webhook is created belonging to their account

webhook_deleted

Sends an event to the user when a webhook is deleted that belonged to their account

category_subscription_confirmation

Sends an event to the user when the user subscribes to a category. Includes the subscription confirmation link.

issue_subscription_confirmation

Sends an event to the user when the user subscribes to an issue. Includes the subscription confirmation link.

issue_created

Sends an event to the user when an issue is created within a category they are subscribed to.

issue_closed

Sends an event to the user when an issue they are subscribed to is closed.

issue_updated

Sends an event to the user when an issue they are subscribed to is updated.

invited_to_company

Sends an event to the user when they are invited and become a member of a new company.