corteza/sam/docs/src/spec.json

[
	{
		"title": "Organisations",
		"description": "Organisations represent a top-level grouping entity. There may be many organisations defined in a single deployment.",
		"package": "sam",
		"entrypoint": "organisation",
		"authentication": ["Client ID", "Session ID"],
		"struct": [
			{
				"name": "Organisation",
				"fields": [
					{ "name": "ID", "type": "uint64" },
					{ "name": "Name", "type": "string" }
				]
			}
		],
		"apis": [
			{
				"name": "edit",
				"method": "POST",
				"title": "Update organisation details",
				"parameters": {
					"post": [
						{ "type": "uint64", "name": "id", "required": false, "title": "Organisation ID" },
						{ "type": "string", "name": "name", "required": true, "title": "Organisation Name" }
					]
				}
			},
			{
				"name": "remove",
				"method": "DELETE",
				"title": "Remove organisation",
				"parameters": {
					"get": [
						{ "type": "uint64", "name": "id", "required": true, "title": "Organisation ID" }
					]
				}
			},
			{
				"name": "read",
				"method": "GET",
				"title": "Read organisation details",
				"parameters": {
					"get": [
						{ "type": "uint64", "name": "id", "required": true, "title": "Organisation ID" }
					]
				}
			},
			{
				"name": "search",
				"method": "GET",
				"title": "Search organisations",
				"parameters": {
					"get": [
						{ "type": "string", "name": "query", "required": false, "title": "Search query" }
					]
				}
			},
			{
				"name": "archive",
				"method": "POST",
				"title": "Archive organisation",
				"parameters": {
					"post": [
						{ "type": "uint64", "name": "id", "required": true, "title": "Organisation ID" }
					]
				}
			}
		]
	},
	{
		"title": "Teams",
		"description": "An organisation may have many teams. Teams may have many channels available. Access to channels may be shared between teams.",
		"package": "sam",
		"entrypoint": "team",
		"authentication": ["Client ID", "Session ID"],
		"struct": [
			{
				"name": "Team",
				"fields": [
					{ "type": "uint64", "name": "ID" },
					{ "type": "string", "name": "Name" },
					{ "type": "[]uint64", "name": "MemberIDs", "tag": "json:\"-\"", "complex": true },
					{ "type": "[]User", "name": "Members", "tag": "json:\",omitempty\"", "complex": true }
				]
			}
		],
		"apis": [
			{
				"name": "edit",
				"method": "POST",
				"title": "Update team details",
				"parameters": {
					"post": [
						{ "type": "uint64", "name": "id", "required": false, "title": "Team ID" },
						{ "type": "string", "name": "name", "required": true, "title": "Name of Team" },
						{ "type": "[]uint64", "name": "members", "required": false, "title": "Team member IDs" }
					]
				}
			},
			{
				"name": "remove",
				"method": "DELETE",
				"title": "Remove team",
				"parameters": {
					"get": [
						{ "type": "uint64", "name": "id", "required": true, "title": "Organisation ID" }
					]
				}
			},
			{
				"name": "read",
				"method": "GET",
				"title": "Read team details and memberships",
				"parameters": {
					"get": [
						{ "type": "uint64", "name": "id", "required": true, "title": "Organisation ID" }
					]
				}
			},
			{
				"name": "search",
				"method": "GET",
				"title": "Search teams",
				"parameters": {
					"get": [
						{ "type": "string", "name": "query", "required": false, "title": "Search query" }
					]
				}
			},
			{
				"name": "archive",
				"method": "POST",
				"title": "Archive team",
				"parameters": {
					"post": [
						{ "type": "uint64", "name": "id", "required": true, "title": "Organisation ID" }
					]
				}
			},
			{
				"name": "move",
				"method": "POST",
				"title": "Move team to different organisation",
				"parameters": {
					"POST": [
						{ "type": "uint64", "name": "id", "required": true, "title": "Organisation ID" },
						{ "type": "uint64", "name": "organisation_id", "required": true, "title": "Organisation ID" }
					]
				}
			},
			{
				"name": "merge",
				"method": "POST",
				"title": "Merge one team into another",
				"parameters": {
					"post": [
						{ "type": "uint64", "name": "destination", "required": true, "title": "Destination Channel ID" },
						{ "type": "uint64", "name": "source", "required": true, "title": "Source Channel ID" }
					]
				}
			}
		]
	},
	{
		"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": "sam",
		"entrypoint": "channel",
		"authentication": ["Client ID", "Session ID"],
		"struct": [
			{
				"name": "Channel",
				"fields": [
					{ "type": "uint64", "name": "ID" },
					{ "type": "string", "name": "Name" },
					{ "type": "string", "name": "Topic" }
				]
			}
		],
		"apis": [
			{
				"name": "edit",
				"method": "POST",
				"title": "Update channel details",
				"parameters": {
					"post": [
						{ "type": "uint64", "name": "id", "required": false, "title": "Channel ID" },
						{ "type": "string", "name": "name", "required": true, "title": "Name of Channel" },
						{ "type": "string", "name": "topic", "required": true, "title": "Subject of Channel" }
					]
				}
			},
			{
				"name": "remove",
				"method": "DELETE",
				"title": "Remove channel",
				"parameters": {
					"get": [
						{ "type": "uint64", "name": "id", "required": true, "title": "Channel ID" }
					]
				}
			},
			{
				"name": "read",
				"method": "GET",
				"title": "Read channel details",
				"parameters": {
					"get": [
						{ "type": "uint64", "name": "id", "required": true, "title": "Channel ID" }
					]
				}
			},
			{
				"name": "search",
				"method": "GET",
				"title": "Search channels",
				"parameters": {
					"get": [
						{ "type": "string", "name": "query", "required": false, "title": "Search query" }
					]
				}
			},
			{
				"name": "archive",
				"method": "POST",
				"title": "Archive channel",
				"parameters": {
					"post": [
						{ "type": "uint64", "name": "id", "required": true, "title": "Channel ID" }
					]
				}
			},
			{
				"name": "move",
				"method": "POST",
				"title": "Move channel to different team or organisation",
				"parameters": {
					"post": [
						{ "type": "uint64", "name": "id", "required": true, "title": "Channel ID" }
					]
				}
			}
		]
	},
	{
		"title": "Messages",
		"package": "sam",
		"entrypoint": "message",
		"authentication": ["Client ID", "Session ID"],
		"struct": [
			{
				"name": "Message",
				"fields": [
					{ "name": "Service", "type": "string" },
					{ "name": "Channel", "type": "string" },
					{ "name": "UserName", "type": "string" },
					{ "name": "UserID", "type": "uint64" },
					{ "name": "User", "type": "*User", "complex": true },
					{ "name": "UserAvatar", "type": "string" },
					{ "name": "Message", "type": "string" },
					{ "name": "MessageID", "type": "string" },
					{ "name": "Type", "type": "MessageType" }
				]
			}
		],
		"apis": [
			{
				"name": "edit",
				"method": "POST",
				"title": "New message / edit message",
				"parameters": {
					"post": [
						{ "type": "uint64", "name": "id", "required": false, "title": "Message ID" },
						{ "type": "uint64", "name": "channel_id", "required": false, "title": "Channel ID where to post message" },
						{ "type": "string", "name": "contents", "required": true, "title": "Message contents (markdown)" }
					]
				}
			},
			{
				"name": "attach",
				"method": "PUT",
				"title": "Attach file to message",
				"params": {
					"get": [
						{ "name": "message_id", "type": "uint64", "title": "Message ID" },
						{ "name": "name", "type": "string", "title": "File name to drop" }
					]
				}
			},
			{
				"name": "remove",
				"method": "DELETE",
				"title": "Remove message",
				"parameters": {
					"get": [
						{ "type": "uint64", "name": "id", "required": true, "title": "Message ID" }
					]
				}
			},
			{
				"name": "read",
				"method": "GET",
				"title": "Read message details",
				"parameters": {
					"post": [
						{ "type": "uint64", "name": "channel_id", "required": true, "title": "Channel ID to read messages from" }
					]
				}
			},
			{
				"name": "search",
				"method": "GET",
				"title": "Search messages",
				"parameters": {
					"get": [
						{ "type": "string", "name": "query", "required": false, "title": "Search string to match against messages" },
						{
							"type": "string",
							"name": "message_type",
							"required": false,
							"title": "Limit results to message type",
							"values": ["history", "message", "attachment", "media"]
						}
					]
				}
			},
			{
				"name": "pin",
				"method": "POST",
				"title": "Pin message to channel (public bookmark)",
				"parameters": {
					"post": [
						{ "type": "uint64", "name": "id", "required": true, "title": "Message ID" }
					]
				}
			},
			{
				"name": "flag",
				"method": "POST",
				"title": "Flag message for user (bookmark)",
				"parameters": {
					"post": [
						{ "type": "uint64", "name": "id", "required": true, "title": "Message ID" }
					]
				}
			}
		]
	},
	{
		"title": "Users",
		"package": "sam",
		"entrypoint": "user",
		"authentication": ["Client ID", "Session ID"],
		"struct": [
			{
				"name": "User",
				"fields": [
					{ "type": "uint64", "name": "ID" },
					{ "type": "string", "name": "Username" },
					{ "type": "string", "name": "Password", "tag": "json:\"-\"" }
				]
			}
		],
		"apis": [
			{
				"name": "login",
				"method": "POST",
				"title": "User login",
				"parameters": {
					"post": [
						{ "type": "string", "name": "username", "required": true, "title": "Username or email" },
						{ "type": "string", "name": "password", "required": true, "title": "Password for user" }
					]
				}
			},
			{
				"name": "search",
				"method": "GET",
				"title": "Search users (Directory)",
				"parameters": {
					"get": [
						{ "type": "string", "name": "query", "required": false, "title": "Search query to match against users" }
					]
				}
			}
		]
	},
	{
		"title": "Websocket",
		"package": "sam",
		"entrypoint": "websocket",
		"protocol": "WebSockets",
		"authentication": ["Client ID", "Session ID"],
		"struct": [
			{
				"name": "WebSocket",
				"fields": [
					{ "type": "uint64", "name": "UserID" },
					{ "type": "User", "name": "User", "complex": true }
				]
			}
		],
		"apis": [
			{
				"name": "client",
				"method": "GET",
				"title": "Bidirectional websocket chat connection"
			}
		]
	}
]