Convos API specification

Version 1.2.0 - OpenAPI 2.0

Description

This document describes the API for Convos, a multiuser persistent IRC proxy with web interface.

Terms of service

SSL (HTTPS) is highly suggested, since login credentials and session cookies are transmitted over this API.

Resources

Base URL

DELETE /api/user

Operation ID: deleteUser

Delete a user.

Parameters

This resource has no input parameters.

Response 200

Successfully deleted.
{"$ref":"#\/definitions\/Success"}

Response 400

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response default

Error.
{"$ref":"#\/definitions\/Error"}

GET /api/user

Operation ID: getUser

Get user data.

Parameters

Name In Type Required Description
connections query boolean No Retrieve connection list.
dialogs query boolean No Retrieve dialog list.
notifications query boolean No Retrieve notifications list.

Response 200

User profile.
{"$ref":"#\/definitions\/User"}

Response 400

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response default

Error.
{"$ref":"#\/definitions\/Error"}

POST /api/user

Operation ID: updateUser

Update an existing user.

Parameters

Name In Type Required Description
body body object Yes

Body

{"properties":{"highlight_keywords":{"description":"Extra keywords to highlight on","items":{"type":"string"},"type":"array"},"password":{"description":"User password","type":"string"}},"type":"object"}

Response 200

User profile.
{"$ref":"#\/definitions\/User"}

Response 400

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response default

Error.
{"$ref":"#\/definitions\/Error"}

GET /api/embed

Operation ID: embed

Get information from a URL

Parameters

Name In Type Required Description
url query string Yes URL to resource

Response 200

Information about resource.
null

Response 400

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response default

Error.
{"$ref":"#\/definitions\/Error"}

GET /api/dialogs

Operation ID: listDialogs

Get a list of all dialogs.

Parameters

This resource has no input parameters.

Response 200

List of messages.
{"properties":{"dialogs":{"items":{"$ref":"#\/definitions\/Dialog"},"type":"array"}},"type":"object"}

Response 400

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response default

Internal server error.
{"$ref":"#\/definitions\/Error"}

POST /api/user/login

Operation ID: loginUser

Log in a user based on email and password.

Parameters

Name In Type Required Description
body body object Yes

Body

{"properties":{"email":{"description":"User email","format":"email","type":"string"},"password":{"description":"User password","type":"string"}},"required":["email","password"],"type":"object"}

Response 200

User profile.
{"$ref":"#\/definitions\/User"}

Response 400

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response default

Error.
{"$ref":"#\/definitions\/Error"}

GET /api/user/logout

Operation ID: logoutUser

Logout a user.

This resource will delete any sessions cookies that might be stored in the client.

Parameters

This resource has no input parameters.

Response 200

Successfully logged out.
{"$ref":"#\/definitions\/Success"}

Response 400

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response default

Error.
{"$ref":"#\/definitions\/Error"}

GET /api/connections

Operation ID: listConnections

Get all the connections for a user.

Parameters

This resource has no input parameters.

Response 200

List of connections.
{"properties":{"connections":{"items":{"$ref":"#\/definitions\/Connection"},"type":"array"}},"type":"object"}

Response 400

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response default

Error.
{"$ref":"#\/definitions\/Error"}

POST /api/connections

Operation ID: createConnection

Add a connection.

Parameters

Name In Type Required Description
body body object Yes

Body

{"properties":{"on_connect_commands":{"description":"Commands to be run after the connection is established","items":{"type":"string"},"type":"array"},"url":{"description":"Example: irc:\/\/user:[email protected]?nick=superman","type":"string"},"wanted_state":{"description":"Connection state","enum":["connected","disconnected"],"type":"string"}},"required":["url"],"type":"object"}

Response 200

Connection information.
{"$ref":"#\/definitions\/Connection"}

Response 400

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response default

Error.
{"$ref":"#\/definitions\/Error"}

GET /api/notifications

Operation ID: notificationMessages

Get list of notications.

A notification is added once your name is mentioned in a chat.

Parameters

This resource has no input parameters.

Response 200

List of notifications.
{"properties":{"messages":{"items":{"$ref":"#\/definitions\/Notification"},"type":"array"}},"type":"object"}

Response 400

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response default

Error.
{"$ref":"#\/definitions\/Error"}

POST /api/user/register

Operation ID: registerUser

Register a new user.

Parameters

Name In Type Required Description
body body object Yes

Body

{"properties":{"email":{"description":"User email","format":"email","type":"string"},"invite_code":{"description":"Secret invite code set on server side.","type":"string"},"password":{"description":"User password","type":"string"}},"required":["email","password"],"type":"object"}

Response 200

User profile.
{"$ref":"#\/definitions\/User"}

Response 400

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response default

Error.
{"$ref":"#\/definitions\/Error"}

POST /api/notifications/read

Operation ID: readNotifications

Mark notications as read.

TODO: Notification count vs red/green toggling of a single notification.

Parameters

This resource has no input parameters.

Response 200

Successful response.
{"properties":{},"type":"object"}

Response 400

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response default

Error.
{"$ref":"#\/definitions\/Error"}

DELETE /api/connection/{connection_id}

Operation ID: removeConnection

Delete a connection and all assosiated data.

Parameters

Name In Type Required Description
connection_id path string Yes A unique connection identifier

Response 200

Remove a connection.
{"$ref":"#\/definitions\/Success"}

Response 400

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response default

Error.
{"$ref":"#\/definitions\/Error"}

POST /api/connection/{connection_id}

Operation ID: updateConnection

Update a connection.

Parameters

Name In Type Required Description
connection_id path string Yes A unique connection identifier
body body object Yes

Body

{"properties":{"on_connect_commands":{"description":"Commands to be run after the connection is established","items":{"type":"string"},"type":"array"},"url":{"description":"Example: irc:\/\/user:[email protected]?nick=superman","format":"uri","type":"string"},"wanted_state":{"description":"Connection state","enum":["connected","disconnected"],"type":"string"}},"type":"object"}

Response 200

Update a connection.
{"$ref":"#\/definitions\/Connection"}

Response 400

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response default

Error.
{"$ref":"#\/definitions\/Error"}

POST /api/connection/{connection_id}/read

Operation ID: setConnectionLastRead

Set 'last_read' for a connection dialog.

Parameters

Name In Type Required Description
connection_id path string Yes A unique connection identifier

Response 200

Successful response.
{"properties":{"last_read":{"format":"date-time","type":"string"}},"type":"object"}

Response 400

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response default

Internal server error.
{"$ref":"#\/definitions\/Error"}

GET /api/connection/{connection_id}/messages

Operation ID: connectionMessages

Get a list of messages. Note: this resource require the user to be authenticated first.

Parameters

Name In Type Required Description
connection_id path string Yes A unique connection identifier
after query string No Find messages after a given ISO 8601 timestamp
before query string No Find messages before a given ISO 8601 timestamp
limit query integer No Max number of messages to retrieve
match query string No Messages must match this string

Response 200

List of messages.
{"properties":{"end":{"description":"Indicates if historic messages can be received.","type":"boolean"},"messages":{"items":{"$ref":"#\/definitions\/Message"},"type":"array"}},"type":"object"}

Response 400

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response default

Internal server error.
{"$ref":"#\/definitions\/Error"}

POST /api/connection/{connection_id}/dialog/{dialog_id}/read

Operation ID: setDialogLastRead

Set 'last_read' for a dialog.

Parameters

Name In Type Required Description
connection_id path string Yes A unique connection identifier
dialog_id path string Yes The name of the person or room

Response 200

Successful response.
{"properties":{"last_read":{"format":"date-time","type":"string"}},"type":"object"}

Response 400

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response default

Internal server error.
{"$ref":"#\/definitions\/Error"}

GET /api/connection/{connection_id}/dialog/{dialog_id}/messages

Operation ID: dialogMessages

Get a list of messages. Note: this resource require the user to be authenticated first.

Parameters

Name In Type Required Description
connection_id path string Yes A unique connection identifier
dialog_id path string Yes The name of the person or room
after query string No Find messages after a given ISO 8601 timestamp
before query string No Find messages before a given ISO 8601 timestamp
limit query integer No Max number of messages to retrieve
match query string No Messages must match this string

Response 200

List of messages.
{"properties":{"end":{"description":"Indicates if historic messages can be received.","type":"boolean"},"messages":{"items":{"$ref":"#\/definitions\/Message"},"type":"array"}},"type":"object"}

Response 400

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 500

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response default

Internal server error.
{"$ref":"#\/definitions\/Error"}

GET /api/connection/{connection_id}/dialog/{dialog_id}/participants

Operation ID: participants

Get a list of participants. Note: this resource require the user to be authenticated first.

Parameters

Name In Type Required Description
connection_id path string Yes A unique connection identifier
dialog_id path string Yes The name of the person or room

Response 200

List of participants.
{"properties":{"participants":{"items":{"properties":{"mode":{"type":"string"},"name":{"type":"string"}},"required":["name"],"type":"object"},"type":"array"}},"required":["participants"],"type":"object"}

Response 400

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 401

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 404

Default response.
{"$ref":"#\/definitions\/_definitions_DefaultResponse"}

Response 500

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response 501

Default response.
{"$ref":"#\/definitions\/DefaultResponse"}

Response default

Internal server error.
{"$ref":"#\/definitions\/Error"}

References

#/definitions/Connection

{"properties":{"connection_id":{"description":"Unique identifier for this connection","type":"string"},"name":{"description":"Name for this connection","type":"string"},"on_connect_commands":{"description":"Commands to be run after the connection is established","items":{"type":"string"},"type":"array"},"state":{"description":"Actual connection state","enum":["connected","queued","disconnected"],"type":"string"},"url":{"description":"Example: irc:\/\/user:@irc.perl.org?nick=superman (Note: Without password)","format":"uri","type":"string"},"wanted_state":{"description":"Wanted connection state","enum":["connected","disconnected"],"type":"string"}},"required":["connection_id","url"]}

#/definitions/DefaultResponse

{"properties":{"errors":{"items":{"properties":{"message":{"type":"string"},"path":{"type":"string"}},"required":["message"],"type":"object"},"type":"array"}},"required":["errors"],"type":"object"}

#/definitions/Dialog

{"properties":{"connection_id":{"description":"Unique identifier for the connection this dialog is part of","type":"string"},"dialog_id":{"description":"Unique identifier for the dialog","type":"string"},"last_active":{"format":"date-time","type":"string"},"last_read":{"format":"date-time","type":"string"},"name":{"description":"Name of the room or person","type":"string"},"topic":{"description":"The subjec\/topic for this room","type":"string"},"unread":{"description":"Number of unread messages","type":"integer"}},"required":["connection_id","dialog_id","last_read","name","unread"]}

#/definitions/Error

{"properties":{"errors":{"items":{"properties":{"message":{"description":"Human readable description of the error","type":"string"},"path":{"description":"JSON pointer to the input data where the error occur","type":"string"}},"required":["message"]},"type":"array"}}}

#/definitions/Message

{"properties":{"from":{"description":"Identifier for who sent this message","type":"string"},"message":{"description":"The message","type":"string"},"ts":{"description":"Example: 2015-09-06T13:49:37Z","format":"date-time","type":"string"}},"required":["message","from","ts"]}

#/definitions/Notification

{"properties":{"connection_id":{"description":"Unique identifier for the connection this notification came from","type":"string"},"dialog_id":{"description":"Dialog ID","type":"string"},"from":{"description":"Identifier for who sent this message","type":"string"},"message":{"description":"The message","type":"string"},"ts":{"description":"Example: 2015-09-06T13:49:37Z","format":"date-time","type":"string"}},"required":["message","from","ts"]}

#/definitions/Success

{"properties":{"message":{"description":"Human readable description","type":"string"}}}

#/definitions/User

{"properties":{"connections":{"items":{"$ref":"#\/definitions\/Connection"},"type":"array"},"dialogs":{"items":{"$ref":"#\/definitions\/Dialog"},"type":"array"},"email":{"description":"Unique email identifying a user in Convos","type":"string"},"highlight_keywords":{"description":"Extra keywords to highlight on","items":{"type":"string"},"type":"array"},"registered":{"description":"Example: 2015-09-06T10:47:31Z","format":"date-time","type":"string"},"unread":{"description":"Number of unread notifications","type":"integer"}},"required":["email","unread"]}

#/definitions/_definitions_DefaultResponse

{"properties":{"errors":{"items":{"properties":{"message":{"type":"string"},"path":{"type":"string"}},"required":["message"],"type":"object"},"type":"array"}},"required":["errors"],"type":"object"}

#/parameters/connection_id - "connection_id"

A unique connection identifier

#/parameters/dialog_id - "dialog_id"

The name of the person or room

#/parameters/ident - "ident"

User email or server identity

License

Artistic License version 2.0

Contact information

https://github.com/Nordaaker/convos