From dd75d7db7015cc60520c6d86812bf821fed7b4b3 Mon Sep 17 00:00:00 2001 From: Tit Petric Date: Fri, 26 Apr 2019 20:38:01 +0200 Subject: [PATCH] add(api,docs): webhooks schema and docs --- api/messaging/spec.json | 257 ++++++++++++++++++++++++ api/messaging/spec/webhooks.json | 183 +++++++++++++++++ api/messaging/spec/webhooks_public.json | 75 +++++++ docs/messaging/README.md | 144 +++++++++++++ 4 files changed, 659 insertions(+) create mode 100644 api/messaging/spec/webhooks.json create mode 100644 api/messaging/spec/webhooks_public.json diff --git a/api/messaging/spec.json b/api/messaging/spec.json index 7b9a6801c..11893f54a 100644 --- a/api/messaging/spec.json +++ b/api/messaging/spec.json @@ -860,5 +860,262 @@ } } ] + }, + { + "entrypoint": "webhooks", + "authentication": [], + "path": "/webhooks", + "method": "GET", + "title": "Webhooks", + "struct": [ + { + "imports": [ + "github.com/crusttech/crust/messaging/types" + ] + } + ], + "parameters": {}, + "apis": [ + { + "name": "list", + "path": "/", + "method": "GET", + "title": "List created webhooks", + "parameters": { + "get": [ + { + "name": "channelID", + "type": "uint64", + "required": false, + "title": "Channel ID" + }, + { + "name": "userID", + "type": "uint64", + "required": false, + "title": "Owner user ID" + } + ] + } + }, + { + "name": "create", + "path": "/", + "method": "POST", + "title": "Create webhook", + "parameters": { + "post": [ + { + "name": "channelID", + "type": "uint64", + "required": true, + "title": "Channel ID" + }, + { + "name": "kind", + "type": "types.WebhookKind", + "required": true, + "title": "Kind (incoming, outgoing)" + }, + { + "name": "trigger", + "type": "string", + "required": false, + "title": "Trigger word" + }, + { + "name": "url", + "type": "string", + "required": false, + "title": "POST URL" + }, + { + "name": "username", + "type": "string", + "required": false, + "title": "Default user name" + }, + { + "name": "avatar", + "type": "*multipart.FileHeader", + "required": false, + "title": "Default avatar" + }, + { + "name": "avatarURL", + "type": "string", + "required": false, + "title": "Default avatar (from URL)" + } + ] + } + }, + { + "name": "update", + "path": "/{webhookID}", + "method": "POST", + "title": "Attach file to channel", + "parameters": { + "path": [ + { + "name": "webhookID", + "type": "uint64", + "required": true, + "title": "Webhook ID" + } + ], + "post": [ + { + "name": "channelID", + "type": "uint64", + "required": true, + "title": "Channel ID" + }, + { + "name": "kind", + "type": "types.WebhookKind", + "required": true, + "title": "Kind (incoming, outgoing)" + }, + { + "name": "trigger", + "type": "string", + "required": false, + "title": "Trigger word" + }, + { + "name": "url", + "type": "string", + "required": false, + "title": "POST URL" + }, + { + "name": "username", + "type": "string", + "required": false, + "title": "Default user name" + }, + { + "name": "avatar", + "type": "*multipart.FileHeader", + "required": false, + "title": "Default avatar" + }, + { + "name": "avatarURL", + "type": "string", + "required": false, + "title": "Default avatar (from URL)" + } + ] + } + }, + { + "method": "GET", + "name": "get", + "path": "/{webhookID}", + "title": "Get webhook details", + "parameters": { + "path": [ + { + "name": "webhookID", + "type": "uint64", + "required": true, + "title": "Webhook ID" + } + ] + } + }, + { + "method": "DELETE", + "name": "delete", + "path": "/{webhookID}", + "title": "Delete webhook", + "parameters": { + "path": [ + { + "name": "webhookID", + "type": "uint64", + "required": true, + "title": "Webhook ID" + } + ] + } + } + ] + }, + { + "entrypoint": "webhooks_public", + "authentication": [], + "path": "/webhooks", + "method": "GET", + "title": "Webhooks (Public)", + "parameters": {}, + "apis": [ + { + "method": "DELETE", + "name": "delete", + "path": "/{webhookID}/{webhookToken}", + "title": "Delete webhook", + "parameters": { + "path": [ + { + "name": "webhookID", + "type": "uint64", + "required": true, + "title": "Webhook ID" + }, + { + "name": "webhookToken", + "type": "string", + "required": true, + "title": "Authentication token" + } + ] + } + }, + { + "method": "POST", + "name": "create", + "path": "/{webhookID}/{webhookToken}", + "title": "Create a message from a webhook payload", + "parameters": { + "path": [ + { + "name": "webhookID", + "type": "uint64", + "required": true, + "title": "Webhook ID" + }, + { + "name": "webhookToken", + "type": "string", + "required": true, + "title": "Authentication token" + } + ], + "get": [ + { + "name": "username", + "type": "string", + "required": false, + "title": "Custom username for webhook message" + }, + { + "name": "avatarURL", + "type": "string", + "required": false, + "title": "Custom avatar picture for webhook message" + }, + { + "name": "content", + "type": "string", + "required": true, + "title": "Message contents" + } + ] + } + } + ] } ] diff --git a/api/messaging/spec/webhooks.json b/api/messaging/spec/webhooks.json new file mode 100644 index 000000000..cddc9ab4d --- /dev/null +++ b/api/messaging/spec/webhooks.json @@ -0,0 +1,183 @@ +{ + "Title": "Webhooks", + "Interface": "Webhooks", + "Struct": [ + { + "imports": [ + "github.com/crusttech/crust/messaging/types" + ] + } + ], + "Parameters": {}, + "Protocol": "", + "Authentication": [], + "Path": "/webhooks", + "APIs": [ + { + "Name": "list", + "Method": "GET", + "Title": "List created webhooks", + "Path": "/", + "Parameters": { + "get": [ + { + "name": "channelID", + "required": false, + "title": "Channel ID", + "type": "uint64" + }, + { + "name": "userID", + "required": false, + "title": "Owner user ID", + "type": "uint64" + } + ] + } + }, + { + "Name": "create", + "Method": "POST", + "Title": "Create webhook", + "Path": "/", + "Parameters": { + "post": [ + { + "name": "channelID", + "required": true, + "title": "Channel ID", + "type": "uint64" + }, + { + "name": "kind", + "required": true, + "title": "Kind (incoming, outgoing)", + "type": "types.WebhookKind" + }, + { + "name": "trigger", + "required": false, + "title": "Trigger word", + "type": "string" + }, + { + "name": "url", + "required": false, + "title": "POST URL", + "type": "string" + }, + { + "name": "username", + "required": false, + "title": "Default user name", + "type": "string" + }, + { + "name": "avatar", + "required": false, + "title": "Default avatar", + "type": "*multipart.FileHeader" + }, + { + "name": "avatarURL", + "required": false, + "title": "Default avatar (from URL)", + "type": "string" + } + ] + } + }, + { + "Name": "update", + "Method": "POST", + "Title": "Attach file to channel", + "Path": "/{webhookID}", + "Parameters": { + "path": [ + { + "name": "webhookID", + "required": true, + "title": "Webhook ID", + "type": "uint64" + } + ], + "post": [ + { + "name": "channelID", + "required": true, + "title": "Channel ID", + "type": "uint64" + }, + { + "name": "kind", + "required": true, + "title": "Kind (incoming, outgoing)", + "type": "types.WebhookKind" + }, + { + "name": "trigger", + "required": false, + "title": "Trigger word", + "type": "string" + }, + { + "name": "url", + "required": false, + "title": "POST URL", + "type": "string" + }, + { + "name": "username", + "required": false, + "title": "Default user name", + "type": "string" + }, + { + "name": "avatar", + "required": false, + "title": "Default avatar", + "type": "*multipart.FileHeader" + }, + { + "name": "avatarURL", + "required": false, + "title": "Default avatar (from URL)", + "type": "string" + } + ] + } + }, + { + "Name": "get", + "Method": "GET", + "Title": "Get webhook details", + "Path": "/{webhookID}", + "Parameters": { + "path": [ + { + "name": "webhookID", + "required": true, + "title": "Webhook ID", + "type": "uint64" + } + ] + } + }, + { + "Name": "delete", + "Method": "DELETE", + "Title": "Delete webhook", + "Path": "/{webhookID}", + "Parameters": { + "path": [ + { + "name": "webhookID", + "required": true, + "title": "Webhook ID", + "type": "uint64" + } + ] + } + } + ] +} \ No newline at end of file diff --git a/api/messaging/spec/webhooks_public.json b/api/messaging/spec/webhooks_public.json new file mode 100644 index 000000000..be0a63fe5 --- /dev/null +++ b/api/messaging/spec/webhooks_public.json @@ -0,0 +1,75 @@ +{ + "Title": "Webhooks (Public)", + "Interface": "Webhooks_public", + "Struct": null, + "Parameters": {}, + "Protocol": "", + "Authentication": [], + "Path": "/webhooks", + "APIs": [ + { + "Name": "delete", + "Method": "DELETE", + "Title": "Delete webhook", + "Path": "/{webhookID}/{webhookToken}", + "Parameters": { + "path": [ + { + "name": "webhookID", + "required": true, + "title": "Webhook ID", + "type": "uint64" + }, + { + "name": "webhookToken", + "required": true, + "title": "Authentication token", + "type": "string" + } + ] + } + }, + { + "Name": "create", + "Method": "POST", + "Title": "Create a message from a webhook payload", + "Path": "/{webhookID}/{webhookToken}", + "Parameters": { + "get": [ + { + "name": "username", + "required": false, + "title": "Custom username for webhook message", + "type": "string" + }, + { + "name": "avatarURL", + "required": false, + "title": "Custom avatar picture for webhook message", + "type": "string" + }, + { + "name": "content", + "required": true, + "title": "Message contents", + "type": "string" + } + ], + "path": [ + { + "name": "webhookID", + "required": true, + "title": "Webhook ID", + "type": "uint64" + }, + { + "name": "webhookToken", + "required": true, + "title": "Authentication token", + "type": "string" + } + ] + } + } + ] +} \ No newline at end of file diff --git a/docs/messaging/README.md b/docs/messaging/README.md index 55e3811a4..dec14221f 100644 --- a/docs/messaging/README.md +++ b/docs/messaging/README.md @@ -642,4 +642,148 @@ The following event types may be sent with a message event: | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | +--- + + + + +# Webhooks + +| Method | Endpoint | Purpose | +| ------ | -------- | ------- | +| `GET` | `/webhooks/` | List created webhooks | +| `POST` | `/webhooks/` | Create webhook | +| `POST` | `/webhooks/{webhookID}` | Attach file to channel | +| `GET` | `/webhooks/{webhookID}` | Get webhook details | +| `DELETE` | `/webhooks/{webhookID}` | Delete webhook | + +## List created webhooks + +#### Method + +| URI | Protocol | Method | Authentication | +| --- | -------- | ------ | -------------- | +| `/webhooks/` | HTTP/S | GET | | + +#### Request parameters + +| Parameter | Type | Method | Description | Default | Required? | +| --------- | ---- | ------ | ----------- | ------- | --------- | +| channelID | uint64 | GET | Channel ID | N/A | NO | +| userID | uint64 | GET | Owner user ID | N/A | NO | + +## Create webhook + +#### Method + +| URI | Protocol | Method | Authentication | +| --- | -------- | ------ | -------------- | +| `/webhooks/` | HTTP/S | POST | | + +#### Request parameters + +| Parameter | Type | Method | Description | Default | Required? | +| --------- | ---- | ------ | ----------- | ------- | --------- | +| channelID | uint64 | POST | Channel ID | N/A | YES | +| kind | types.WebhookKind | POST | Kind (incoming, outgoing) | N/A | YES | +| trigger | string | POST | Trigger word | N/A | NO | +| url | string | POST | POST URL | N/A | NO | +| username | string | POST | Default user name | N/A | NO | +| avatar | *multipart.FileHeader | POST | Default avatar | N/A | NO | +| avatarURL | string | POST | Default avatar (from URL) | N/A | NO | + +## Attach file to channel + +#### Method + +| URI | Protocol | Method | Authentication | +| --- | -------- | ------ | -------------- | +| `/webhooks/{webhookID}` | HTTP/S | POST | | + +#### Request parameters + +| Parameter | Type | Method | Description | Default | Required? | +| --------- | ---- | ------ | ----------- | ------- | --------- | +| webhookID | uint64 | PATH | Webhook ID | N/A | YES | +| channelID | uint64 | POST | Channel ID | N/A | YES | +| kind | types.WebhookKind | POST | Kind (incoming, outgoing) | N/A | YES | +| trigger | string | POST | Trigger word | N/A | NO | +| url | string | POST | POST URL | N/A | NO | +| username | string | POST | Default user name | N/A | NO | +| avatar | *multipart.FileHeader | POST | Default avatar | N/A | NO | +| avatarURL | string | POST | Default avatar (from URL) | N/A | NO | + +## Get webhook details + +#### Method + +| URI | Protocol | Method | Authentication | +| --- | -------- | ------ | -------------- | +| `/webhooks/{webhookID}` | HTTP/S | GET | | + +#### Request parameters + +| Parameter | Type | Method | Description | Default | Required? | +| --------- | ---- | ------ | ----------- | ------- | --------- | +| webhookID | uint64 | PATH | Webhook ID | N/A | YES | + +## Delete webhook + +#### Method + +| URI | Protocol | Method | Authentication | +| --- | -------- | ------ | -------------- | +| `/webhooks/{webhookID}` | HTTP/S | DELETE | | + +#### Request parameters + +| Parameter | Type | Method | Description | Default | Required? | +| --------- | ---- | ------ | ----------- | ------- | --------- | +| webhookID | uint64 | PATH | Webhook ID | N/A | YES | + +--- + + + + +# Webhooks (Public) + +| Method | Endpoint | Purpose | +| ------ | -------- | ------- | +| `DELETE` | `/webhooks/{webhookID}/{webhookToken}` | Delete webhook | +| `POST` | `/webhooks/{webhookID}/{webhookToken}` | Create a message from a webhook payload | + +## Delete webhook + +#### Method + +| URI | Protocol | Method | Authentication | +| --- | -------- | ------ | -------------- | +| `/webhooks/{webhookID}/{webhookToken}` | HTTP/S | DELETE | | + +#### Request parameters + +| Parameter | Type | Method | Description | Default | Required? | +| --------- | ---- | ------ | ----------- | ------- | --------- | +| webhookID | uint64 | PATH | Webhook ID | N/A | YES | +| webhookToken | string | PATH | Authentication token | N/A | YES | + +## Create a message from a webhook payload + +#### Method + +| URI | Protocol | Method | Authentication | +| --- | -------- | ------ | -------------- | +| `/webhooks/{webhookID}/{webhookToken}` | HTTP/S | POST | | + +#### Request parameters + +| Parameter | Type | Method | Description | Default | Required? | +| --------- | ---- | ------ | ----------- | ------- | --------- | +| username | string | GET | Custom username for webhook message | N/A | NO | +| avatarURL | string | GET | Custom avatar picture for webhook message | N/A | NO | +| content | string | GET | Message contents | N/A | YES | +| webhookID | uint64 | PATH | Webhook ID | N/A | YES | +| webhookToken | string | PATH | Authentication token | N/A | YES | + --- \ No newline at end of file