DeforaNetworks/corteza
3
0
Fork 0
Code Activity

finely control API call order, array instead of object notation

Browse Source
This commit is contained in:
Tit Petric
2018-06-03 15:28:34 +02:00
parent 7988bffc9b
commit 1f3e4edf51
3 changed files with 347 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files

349
docs/README.md
View File

@@ -2,6 +2,39 @@
Organisations represent a top-level grouping entity. There may be many organisations defined in a single deployment.
## Update organisation details
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | POST | Organisation ID | N/A | NO |
| name | string | POST | Organisation Name | N/A | YES |
## Remove organisation
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | GET | Organisation ID | N/A | YES |
## Read organisation details
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | GET | Organisation ID | N/A | YES |
## Search organisations
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| query | string | GET | Search query | N/A | NO |
## Archive organisation
### Request parameters
@@ -19,7 +52,7 @@ Organisations represent a top-level grouping entity. There may be many organisat
| id | uint64 | POST | Organisation ID | N/A | NO |
| name | string | POST | Organisation Name | N/A | YES |
## Read organisation details
## Remove organisation
### Request parameters
@@ -27,7 +60,7 @@ Organisations represent a top-level grouping entity. There may be many organisat
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | GET | Organisation ID | N/A | YES |
## Remove organisation
## Read organisation details
### Request parameters
@@ -43,14 +76,7 @@ Organisations represent a top-level grouping entity. There may be many organisat
| --------- | ---- | ------ | ----------- | ------- | --------- |
| query | string | GET | Search query | N/A | NO |
# Teams
An organisation may have many teams. Teams may have many channels available. Access to channels may be shared between teams.
## Archive team
## Archive organisation
### Request parameters
@@ -58,6 +84,13 @@ An organisation may have many teams. Teams may have many channels available. Acc
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | POST | Organisation ID | N/A | YES |
# Teams
An organisation may have many teams. Teams may have many channels available. Access to channels may be shared between teams.
## Update team details
### Request parameters
@@ -68,16 +101,7 @@ An organisation may have many teams. Teams may have many channels available. Acc
| name | string | POST | Name of Team | N/A | YES |
| members | []uint64 | POST | Team member IDs | N/A | NO |
## Move team to different organisation
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | POST | Organisation ID | N/A | YES |
| organisation_id | uint64 | POST | Organisation ID | N/A | YES |
## Read team details and memberships
## Remove team
### Request parameters
@@ -85,7 +109,7 @@ An organisation may have many teams. Teams may have many channels available. Acc
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | GET | Organisation ID | N/A | YES |
## Remove team
## Read team details and memberships
### Request parameters
@@ -101,6 +125,74 @@ An organisation may have many teams. Teams may have many channels available. Acc
| --------- | ---- | ------ | ----------- | ------- | --------- |
| query | string | GET | Search query | N/A | NO |
## Archive team
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | POST | Organisation ID | N/A | YES |
## Move team to different organisation
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | POST | Organisation ID | N/A | YES |
| organisation_id | uint64 | POST | Organisation ID | N/A | YES |
## Update team details
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | POST | Team ID | N/A | NO |
| name | string | POST | Name of Team | N/A | YES |
| members | []uint64 | POST | Team member IDs | N/A | NO |
## Remove team
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | GET | Organisation ID | N/A | YES |
## Read team details and memberships
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | GET | Organisation ID | N/A | YES |
## Search teams
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| query | string | GET | Search query | N/A | NO |
## Archive team
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | POST | Organisation ID | N/A | YES |
## Move team to different organisation
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | POST | Organisation ID | N/A | YES |
| organisation_id | uint64 | POST | Organisation ID | N/A | YES |
@@ -108,14 +200,6 @@ An organisation may have many teams. Teams may have many channels available. Acc
A channel is a representation of a sequence of messages. It has meta data like channel subject. Channels may be public, private or direct (between two users).
## Archive channel
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | POST | Channel ID | N/A | YES |
## Update channel details
### Request parameters
@@ -126,24 +210,7 @@ A channel is a representation of a sequence of messages. It has meta data like c
| name | string | POST | Name of Channel | N/A | YES |
| topic | string | POST | Subject of Channel | N/A | YES |
## Merge one team into another
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| destination | uint64 | POST | Destination Channel ID | N/A | YES |
| source | uint64 | POST | Source Channel ID | N/A | YES |
## Move channel to different team or organisation
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | POST | Channel ID | N/A | YES |
## Read channel details
## Remove channel
### Request parameters
@@ -151,7 +218,7 @@ A channel is a representation of a sequence of messages. It has meta data like c
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | GET | Channel ID | N/A | YES |
## Remove channel
## Read channel details
### Request parameters
@@ -167,6 +234,90 @@ A channel is a representation of a sequence of messages. It has meta data like c
| --------- | ---- | ------ | ----------- | ------- | --------- |
| query | string | GET | Search query | N/A | NO |
## Archive channel
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | POST | Channel ID | N/A | YES |
## Move channel to different team or organisation
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | POST | Channel ID | N/A | YES |
## Merge one team into another
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| destination | uint64 | POST | Destination Channel ID | N/A | YES |
| source | uint64 | POST | Source Channel ID | N/A | YES |
## Update channel details
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | POST | Channel ID | N/A | NO |
| name | string | POST | Name of Channel | N/A | YES |
| topic | string | POST | Subject of Channel | N/A | YES |
## Remove channel
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | GET | Channel ID | N/A | YES |
## Read channel details
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | GET | Channel ID | N/A | YES |
## Search channels
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| query | string | GET | Search query | N/A | NO |
## Archive channel
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | POST | Channel ID | N/A | YES |
## Move channel to different team or organisation
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | POST | Channel ID | N/A | YES |
## Merge one team into another
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| destination | uint64 | POST | Destination Channel ID | N/A | YES |
| source | uint64 | POST | Source Channel ID | N/A | YES |
@@ -192,6 +343,16 @@ The following event types may be sent with a message event:
| EDITED | A message has been edited by the sender |
| REMOVED | A message has been removed by the sender |
## New message / edit message
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | POST | Message ID | N/A | NO |
| channel_id | uint64 | POST | Channel ID where to post message | N/A | NO |
| contents | string | POST | Message contents (markdown) | N/A | YES |
## Attach file to message
### Request parameters
@@ -199,6 +360,47 @@ The following event types may be sent with a message event:
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
## Remove message
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | GET | Message ID | N/A | YES |
## Read message details
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| channel_id | uint64 | POST | Channel ID to read messages from | N/A | YES |
## Search messages
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| query | string | GET | Search string to match against messages | N/A | NO |
| message_type | string | GET | Limit results to message type | N/A<br><br>Values:<br><br><ul><li>`history`</li><li>`message`</li><li>`attachment`</li><li>`media`</li> | NO |
## Pin message to channel (public bookmark)
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | POST | Message ID | N/A | YES |
## Flag message for user (bookmark)
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | POST | Message ID | N/A | YES |
## New message / edit message
### Request parameters
@@ -209,29 +411,12 @@ The following event types may be sent with a message event:
| channel_id | uint64 | POST | Channel ID where to post message | N/A | NO |
| contents | string | POST | Message contents (markdown) | N/A | YES |
## Flag message for user (bookmark)
## Attach file to message
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | POST | Message ID | N/A | YES |
## Pin message to channel (public bookmark)
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | POST | Message ID | N/A | YES |
## Read message details
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| channel_id | uint64 | POST | Channel ID to read messages from | N/A | YES |
## Remove message
@@ -241,6 +426,14 @@ The following event types may be sent with a message event:
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | GET | Message ID | N/A | YES |
## Read message details
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| channel_id | uint64 | POST | Channel ID to read messages from | N/A | YES |
## Search messages
### Request parameters
@@ -250,6 +443,22 @@ The following event types may be sent with a message event:
| query | string | GET | Search string to match against messages | N/A | NO |
| message_type | string | GET | Limit results to message type | N/A<br><br>Values:<br><br><ul><li>`history`</li><li>`message`</li><li>`attachment`</li><li>`media`</li> | NO |
## Pin message to channel (public bookmark)
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | POST | Message ID | N/A | YES |
## Flag message for user (bookmark)
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| id | uint64 | POST | Message ID | N/A | YES |
@@ -259,6 +468,14 @@ The following event types may be sent with a message event:
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| query | string | GET | Search query to match against users | N/A | NO |
## Search members (Directory)
### Request parameters
| Parameter | Type | Method | Description | Default | Required? |
| --------- | ---- | ------ | ----------- | ------- | --------- |
| query | string | GET | Search query to match against users | N/A | NO |

4
docs/README.php
View File

@@ -38,7 +38,6 @@ $spec = json_decode(file_get_contents("src/spec.json"), true);
$apis = array();
foreach ($spec as $api) {
$entrypoint = $api['entrypoint'];
var_dump($entrypoint);
$filename = "src/spec/" . $entrypoint . ".json";
$filename_md = "src/" . $entrypoint . "/index.md";
$api = json_decode(file_get_contents($filename), true);
@@ -46,7 +45,8 @@ foreach ($spec as $api) {
if (file_exists($filename_md)) {
$api['description'] = file_get_contents($filename_md);
}
foreach ($api['apis'] as $name => $call) {
foreach ($api['apis'] as $call) {
$name = $call['name'];
$filename_md = "src/" . $entrypoint . "/" . $name . ".md";
if (file_exists($filename_md)) {
$call['description'] = file_get_contents($filename_md);

98
docs/src/spec.json
View File

@@ -4,8 +4,9 @@
"description": "Organisations represent a top-level grouping entity. There may be many organisations defined in a single deployment.",
"package": "crust",
"entrypoint": "organisation",
"apis": {
"edit": {
"apis": [
{
"name": "edit",
"method": "POST",
"title": "Update organisation details",
"parameters": {
@@ -15,7 +16,8 @@
]
}
},
"remove": {
{
"name": "remove",
"method": "DELETE",
"title": "Remove organisation",
"parameters": {
@@ -24,7 +26,8 @@
]
}
},
"read": {
{
"name": "read",
"method": "GET",
"title": "Read organisation details",
"parameters": {
@@ -33,7 +36,8 @@
]
}
},
"search": {
{
"name": "search",
"method": "GET",
"title": "Search organisations",
"parameters": {
@@ -42,7 +46,8 @@
]
}
},
"archive": {
{
"name": "archive",
"method": "POST",
"title": "Archive organisation",
"parameters": {
@@ -51,15 +56,16 @@
]
}
}
}
]
},
{
"title": "Teams",
"description": "An organisation may have many teams. Teams may have many channels available. Access to channels may be shared between teams.",
"package": "crust",
"entrypoint": "team",
"apis": {
"edit": {
"apis": [
{
"name": "edit",
"method": "POST",
"title": "Update team details",
"parameters": {
@@ -70,7 +76,8 @@
]
}
},
"remove": {
{
"name": "remove",
"method": "DELETE",
"title": "Remove team",
"parameters": {
@@ -79,7 +86,8 @@
]
}
},
"read": {
{
"name": "read",
"method": "GET",
"title": "Read team details and memberships",
"parameters": {
@@ -88,7 +96,8 @@
]
}
},
"search": {
{
"name": "search",
"method": "GET",
"title": "Search teams",
"parameters": {
@@ -97,7 +106,8 @@
]
}
},
"archive": {
{
"name": "archive",
"method": "POST",
"title": "Archive team",
"parameters": {
@@ -106,7 +116,8 @@
]
}
},
"move": {
{
"name": "move",
"method": "POST",
"title": "Move team to different organisation",
"parameters": {
@@ -116,15 +127,16 @@
]
}
}
}
]
},
{
"title": "Channels",
"description": "A channel is a representation of a sequence of messages. It has meta data like channel subject. Channels may be public, private or direct (between two users).",
"package": "crust",
"entrypoint": "channel",
"apis": {
"edit": {
"apis": [
{
"name": "edit",
"method": "POST",
"title": "Update channel details",
"parameters": {
@@ -135,7 +147,8 @@
]
}
},
"remove": {
{
"name": "remove",
"method": "DELETE",
"title": "Remove channel",
"parameters": {
@@ -144,7 +157,8 @@
]
}
},
"read": {
{
"name": "read",
"method": "GET",
"title": "Read channel details",
"parameters": {
@@ -153,7 +167,8 @@
]
}
},
"search": {
{
"name": "search",
"method": "GET",
"title": "Search channels",
"parameters": {
@@ -162,7 +177,8 @@
]
}
},
"archive": {
{
"name": "archive",
"method": "POST",
"title": "Archive channel",
"parameters": {
@@ -171,7 +187,8 @@
]
}
},
"move": {
{
"name": "move",
"method": "POST",
"title": "Move channel to different team or organisation",
"parameters": {
@@ -180,7 +197,8 @@
]
}
},
"merge": {
{
"name": "merge",
"method": "POST",
"title": "Merge one team into another",
"parameters": {
@@ -190,14 +208,15 @@
]
}
}
}
]
},
{
"title": "Messages",
"package": "crust",
"entrypoint": "message",
"apis": {
"edit": {
"apis": [
{
"name": "edit",
"method": "POST",
"title": "New message / edit message",
"parameters": {
@@ -208,7 +227,8 @@
]
}
},
"attach": {
{
"name": "attach",
"method": "PUT",
"title": "Attach file to message",
"params": {
@@ -218,7 +238,8 @@
]
}
},
"remove": {
{
"name": "remove",
"method": "DELETE",
"title": "Remove message",
"parameters": {
@@ -227,7 +248,8 @@
]
}
},
"read": {
{
"name": "read",
"method": "GET",
"title": "Read message details",
"parameters": {
@@ -236,7 +258,8 @@
]
}
},
"search": {
{
"name": "search",
"method": "GET",
"title": "Search messages",
"parameters": {
@@ -252,7 +275,8 @@
]
}
},
"pin": {
{
"name": "pin",
"method": "POST",
"title": "Pin message to channel (public bookmark)",
"parameters": {
@@ -261,7 +285,8 @@
]
}
},
"flag": {
{
"name": "flag",
"method": "POST",
"title": "Flag message for user (bookmark)",
"parameters": {
@@ -270,14 +295,15 @@
]
}
}
}
]
},
{
"title": "Members",
"package": "crust",
"entrypoint": "member",
"apis": {
"search": {
"apis": [
{
"name": "search",
"method": "GET",
"title": "Search members (Directory)",
"parameters": {
@@ -286,6 +312,6 @@
]
}
}
}
]
}
]