# Gossip

Gossip, at a very high level, is a specification for an API that allows different bots to talk to each other in a simple and predictable way. The specification is flexible and customizable to allow for developers to customize implementations to suit their needs while also ensuring standards to allow bots of any caliber to work with each other. The specification is loosely inspired by [SCIM](http://www.simplecloud.info/).

Gossip allows bot developers to:

- Create an arbitrary network of bots capable of exchanging information
- Pull information from other clients in a network ("lookups")
- Push information to other clients in a network ("notifies")
- Implement and expect a common set of extensible schemas
- Extend or create schemas for application-specific use cases, such as IPC

The Gossip specification follows a federated model where clients (generally bots) will directly communicate with each other. While clients are generally bots, persistent datastores known as "brokers" may be present in any given Gossip network.

## Clients

Clients are, fundamentally, HTTP servers that allow data exchange between nodes in a Gossip network.

Gossip clients shall have four operating capabilities:

- Receiving Lookups from clients (inbound `GET`)
- Sending Lookups to clients (outbound `GET`)
- Receiving Notifies from clients (inbound `POST`/`PUT`)
- Sending Notifies to clients (outbound `POST`/`PUT`)

Clients are encouraged to support all above modes, however a client may only implement those that are necessary to the client's operation. Of specific note, however, is that a client that supports receiving Notifies MUST additionally support receiving Lookups.

## Schemas

### General Schema Design

TBD, tiers:

* **Tier I - Core Attributes**
All Schemas contain a core set of *required* data known as Core Attributes. Any client capable of reporting information of this schema type MUST include all Core Attributes. Core Attributes MAY be `null` depending on the type of data, but the field values must be present.
* **Tier II - Extended Attributes**
Schemas may contain an extended set of in-specification data values. This data MAY be provided by clients if available, but clients SHALL NOT expect this data to be present. Optional Extended Data MAY be `null` or missing entirely.
* **Tier III - Client-Specific Attributes**
Schemas may contain Client-Specific Attributes, which are to be considered an extension of a Schema. Client-Specific Attributes MAY be provided by clients if available. Clients SHOULD be aware of extra data although processing of this data is not required. These attributes are not defined in the specification.

## Some Initial API Routes (not final please change)

API Base: `/api/v1`

### `POST /guilds/{guild_id}/mod/cases/{member_id}`

Create a new case for a member

### `GET /guilds/{guild_id}/mod/cases/{member_id}`

Fetch all cases for a member

### `GET /guilds/{guild_id}/mod/case/{case_id}`

Fetch a specific case by ID

### `PATCH /guilds/{guild_id}/mod/case/{case_id}`

Update an existing case by ID

### `DELETE /guilds/{guild_id}/mod/case/{case_id}`

Delete an existing case by ID

### `POST /messages/send/{event_name}`

Create a new {event_name} message

### `POST /messages/register/{event_name}`

Register a webhook to send events of {event_name} to

### alternate proposal

## Alternate API routes proposal with API versioning, topics, and query parameters for filtering

Basic format: `/{version}/{topic}/{resource}`

### `GET /v1/mod/cases`

Fetch cases with optional filtering

#### Parameters
* `guild_id` — Filter to a specific guild id
* `user_id` — Filter to a specific user id

### `GET /v1/mod/cases/{id}`

Fetch a specific case by ID

### `POST /v1/core/messages/{event_name}`

Create a new {event_name} message