# CactusAPI Specification

## General Information

### How to interact with the api

The API base path is `/api/v1`. This will change over time as our API changes versions, but this is the basic form. All API requests **must** start with that path.

### Responses

All responses from endpoints are returned in JSON form and are [JSON:API](http://jsonapi.org/) compliant.

Regular HTTP codes are in use. If the request completes successfully and is able to return data, then the status code will be `200`. Other results and their respective codes include:

* **`201`** Created:
* The request has been fulfilled and resulted in a new resource being created.

* **`204`** No Content:
* The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation.
* The server has successfully processed the request, but will not be returning any content.

* **`400`** Bad request:
* The request could not be understood by the server due to malformed syntax.

* **`500`** Internal Server Error:
* The server encountered an unexpected condition which prevented it from fulfilling the request.
* Used when there isn't a more specific error code

* **`404`** Resource not found:

* There is no API endpoint for that path

An error object will be returned with more details.

* **`409`** Conflict
* Data is syntactically valid, but the resource already exists with that exact information. Only occurs on POST or PUT requests
* Will return the already existing resource

### Authentication

The API requires a token-based authentication for some of the endpoints. You provide the required data by setting the `X-Auth-Token` and `X-Auth-Key` headers.

The values for these are your account's token and a generated access key respectively. The access token is in JSON Web Token format and will expire after 24 hours, after which you will have to reauthenticate to receive a new access key.

To get the access key, you will need to execute a `POST` request to the `/login` endpoint. The follow parameters are required:

* `token`: Your account's token which was created when you created your account
* `password`: Your account's API access password (note, this may be different than your bot account password if you are using a custom bot name)
* `scopes`: This is a list of the scopes you want access to.

Here is a complete example of the data to be passed in JSON form:

{
	"token": "paradigmshift3d",
	"password": "p0t4toS3crets!",
	"scopes": [
		"command:create",
		"command:details",
		"command:manage",
		"repeat:manage",
		"config:details"
	]
}

This will either return an error which will explain what is wrong with the authentication request, or will return a JSON response that looks similar to this:

{
	"scopes": [
		"command:create",
		"command:details",
		"command:manage",
		"repeat:manage",
		"config:details"
	],
	"key": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJzY29wZXMiOlsicmVwZWF0OmNyZWF0ZSIsInJlcGVhdDpkZXRhaWxzIiwicmVwZWF0Om1hbmFnZSIsInJlcGVhdDpsaXN0Il0sImV4cGlyZXMiOjE0ODMxNTY0ODAsInRva2VuIjoicGFyYWRpZ21zaGlmdDNkIn0.T8D54pDpKZbTNi5nDNWt4W2jlNlceyqrWladVWLAntm2sUpfVigkvs3u2kFn5Rgf7SO96bNd6STooNtbOAMuBg"
}

The `scopes` key is all of the scopes you now have access to with that access key.

In order to access the API, set the `X-Auth-Token` request header to your account's token and the `X-Auth-Key` header to the newly generated access key. Note, the `X-Auth-Token` header **must** match the token you used to generate your access key. Otherwise the request will fail.

You should now be all set to use the API!

### Errors

If an authentication error does occur, it will return either a 400 or 403 status code, along with a JSON payload with an `errors` key that will explain the error.

For example, if you attempt to generate an API access key and have not set up your account with an API password, then you would receive this response:

{
	"errors": [
		"User account is not configured for API access"
	]
}

with HTTP status code `400`.

Or, if you attempt to access an endpoint with an access key that lacks the proper scopes, you will receive a response similar to this:

{
	"errors": [
		{
			"message": "Scopes allowed for that access token do not meet endpoint requirements",
			"missing": [
				"command:manage",
				"command:details"
			]
		}
	]
}

## Endpoints

### Commands

* #### Get all commands
`GET` `/api/v1/user/:token/command`

**Scopes Required**: None

A `GET` request to this endpoint will return a list of all commands associated with the token supplied.

* #### Get an individual command

`GET` `/api/v1/user/:token/command/:command`

**Scopes required**: None

`:command` The string representation of the command's name. The string that is used to invoke the command.

A `GET` request to this endpoint will return a single command object in response if the command requested exists. If not, or if the user requested does not exist, the API will return no content with the HTTP response code set to `204`.

* ### Creating and editing a command

`PATCH` `/api/v1/user/:token/command/:command`

`:command` The string representation of the command's name. The string that is used to invoke the command.

**Scopes required**: `command:manage`, `command:create`

**Parameters**:

* `response` - **Required for creation, optional for editing unless otherwise marked**

List of objects

* `action` - Boolean
Declares if the message is to be sent in regular form or a special form, such as `/me`
* `target` - String, nullable
If this key is set, then it will whisper the response to the user that matches the string's contents
* `message` - List of objects - The command's response.

* `type` - String, required
One of either `emoji`, `link`, or `text`
* `data` - String, required
The service-agnostic representation of the contents
* `text` - String, required
The raw form of the contents from the command creation

* `role` - Integer, Required for creation optional for editing, defaults to `0`
The minimum user level required to run the command.

**Optional Parameters**:
* `enabled` - Boolean
Set to `true` or `false` to enable or disable the command

This endpoint will return the newly created command with HTTP status code `201` if the creation is successful.

When editing via this endpoint, simply supply any changes wished to be made. If successful, the the newly changed command will be returned with status code `200`.

* #### Changing a command's execution counter

`PATCH` `/api/v1/:token/command/:command/count`

**Parameters**:

* `count` - **Required**

String of format `[+-=][value]`

**Example**: `"count": "+2"` would increment the command's count by two. `=0` would set the count equal to 0

* #### Remove a command
`DELETE` `/api/v1/user/:token/command/:command`

`:command` The string representation of the command's name. The string that is used to invoke the command.

**Scopes required**: `command:manage`

A `DELETE` request to this endpoint will return nothing with the HTTP status code `204` if the deletion was successful.

### Quotes

* #### Get all quotes
`GET` `/api/v1/user/:token/quote`

**Scopes Required**: None

A `GET` request to this endpoint will return a list of all quotes associated with the username supplied.

* #### Get an individual quote

`GET` `/api/v1/user/:token/quote/:quoteId`

**Scopes Required**: None

A `GET` request to this endpoint will return a single quote object in response if the quote requested exists. If not, or if the user requested does not exist, the API will return no content with the HTTP response code set to `204`.

**Optional Parameters:**

- `random`
Passing either a form of `True` or `1` with this key in the URL will return a random quote from the DB for that user.

Will return a `404` if no quote exist for that user

- `limit`
Passing an whole number integer value with this key will change how many total number of quotes are returned.

Defaults to `1` if requesting a random quote, otherwise the lack of this key will not affect anything.

If a higher number is supplied than number of quotes that are available, all available quotes for the user will be returned

* #### Creating a quote
`POST` `/api/v1/user/:token/quote`

**Scopes required**: `quote:manage`, `quote:create`

**Parameters**:

* `quote` - **Required**
String - The quote's content

This endpoint will return the newly created quote with HTTP status code `201` if successful.

* #### Edit a quote
`PATCH` `/api/v1/user/:token/quote/:quoteId`

**Required scopes**: `quote:manage`

A `PATCH` request to this endpoint must have the following parameters included:

* `quote` - **Required**
String - The quote's new content

Endpoint will return the new quote object with status code `200` if it's successful in editing.

* #### Remove a quote
`DELETE` `/api/v1/user/:token/quote/:quoteName`

**Required scopes**: `quote:manage`

A `DELETE` request to this endpoint will return nothing with the HTTP status code `204` if the deletion was successful.

If it fails due to a token or quote ID being supplied that does not exist, then an error will be returned with what was missing.

### Repeats

* #### Get all repeats

`GET` `/api/v1/user/:token/repeat`

**Required scopes**: None

A `GET` request to this endpoint will return a list of all repeats associated with the user.

* #### Get a single repeat

`GET` `/api/v1/user/:token/repeat/:repeatId`

**Required scopes**: None

`GET` request to this endpoint will return a single repeat object in response if the repeat requested exists. If the repeat or user requested do not exist, the API will return no content with the HTTP response code set to `204`.

* #### Creating a repeat
`PATCH` `/api/v1/user/:token/repeat/:repeatName`

**Required scopes**: `repeat:manage`, `repeat:create`

`PATCH` request to this endpoint will return the newly created repeat with HTTP status code `201` if successful.

**Parameters**:

* `commandName` - **Required**
String - The command the repeat will be running every `period`. Command must already exist.

* `period` - **Required**
Integer - The repeat's period (in seconds)

* ### Edit a repeat
`PATCH` `/api/v1/user/:token/repeat/:repeatId`

`PATCH` request to this endpoint will return the new repeat object with status code `200` if it's successful in editing.

**Parameters**:

* `commandName` - **Optional**
The command the repeat will be running every `period`. Command must already exist.

* `period` - **Optional**
The repeat's period (in seconds)

* #### Remove a repeat
`DELETE` `/api/v1/user/:token/repeat/:repeatName`

A `DELETE` request to this endpoint will return nothing with the HTTP status code `204` if the deletion was successful.

If it fails due to a token or repeat name being supplied that does not exist, then an error will be returned with what was missing.

## Trusts

* ### Get all trusts

`GET` `/api/v1/user/:token/trust`

**Required scopes**: None

A `GET` request to this endpoint will return a list of all trusts associated with the channel supplied.

* ### Get an individual trust

`GET` `/api/v1/user/:token/trust/:userId`

**Required scopes**: None

A `GET` request to this endpoint will return a single trust object in response if the trust requested exists. If not, or if the user requested does not exist, the API will return no content with the HTTP response code set to `204`.

* ### Creating and editing a trust

`PATCH` `/api/v1/user/:token/trust/:userId`

**Required scopes**: `trust:manage`, `trust:create`

**Parameters**:
* `userName` - **Required**
String - The cased username associated with the userId given in the request URL.

This endpoint will return the newly created resource with HTTP status code `201` if the creation is successful.

When editing via this endpoint, simply supply any changes wished to be made. If successful, the endpoint will return the newly changed resource with status code `200`.

* ### Remove a trust

`DELETE` `/api/v1/channel/:token/trust/:username`

**Required scopes**: `trust:manage`

A `DELETE` request to this endpoint will return nothing with the HTTP status code `204` if the deletion was successful.

If it fails due to a channel being supplied that does not exist, then an error will be returned with what was missing.

### Social

* ### Get all social services

`GET` `/api/v1/user/:token/social`

**Required scopes**: None

A `GET` request to this endpoint will return a list of all social services associated with the user supplied.

* ### Get an individual social service

`GET` `/api/v1/user/:token/social/:service`

**Required scopes**: None

A `GET` request to this endpoint will return a single social service object in response if the service requested exists.

If the user or service requested does not exist, the API will return no content with the HTTP response code set to `204`.

* ### Create/edit a custom social service
`PATCH` `/api/v1/user/:token/social/:service`

`:service` A string for the social service that will be used for look up in the future

A `PATCH` request to this endpoint must have the following parameters included:

**Parameters**:
* `url` - **Required**
String/URL - A valid URL for the social service

This endpoint will return the newly created social with HTTP status code `201` if the creation is successful.

When editing via this endpoint, simply supply any changes wished to be made. If successful, the endpoint will return the newly changed object with status code `200`.