Convos API specification

Version 0.99_37

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 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 default

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

POST /api/user

Operation ID: updateUser

Update an existing user.

Parameters

Name In Type Required Description
body body Yes

Body

{
  "properties": {
    "password": {
      "description": "User password",
      "type": "string"
    }
  },
  "type": "object"
}

Response 200

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

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.
undef

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 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 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 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 302

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

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 default

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

POST /api/connections

Operation ID: createConnection

Add a connection.

Parameters

Name In Type Required Description
body body 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:pass\@irc.perl.org?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 default

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

GET /api/notifications

Operation ID: listNotifications

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": {
    "notifications": {
      "items": {
        "\$ref": "#/definitions/Notification"
      },
      "type": "array"
    }
  },
  "type": "object"
}

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 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 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 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 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 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:pass\@irc.perl.org?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 default

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

GET /api/connection/{connection_id}/rooms

Operation ID: roomsForConnection

Get a list of all available chat rooms.

Parameters

Name In Type Required Description
connection_id path string Yes A unique connection identifier
match query string No Rooms must match this string to be returned

Response 200

List of rooms.
{
  "properties": {
    "end": {
      "description": "True if the backend has loaded all the rooms",
      "type": "boolean"
    },
    "n_rooms": {
      "description": "Total number of rooms",
      "type": "integer"
    },
    "rooms": {
      "items": {
        "properties": {
          "n_users": {
            "description": "Number of participants in the room",
            "type": "integer"
          },
          "name": {
            "description": "Name of the room or person",
            "type": "string"
          },
          "topic": {
            "description": "The subjec/topic for this room",
            "type": "string"
          }
        },
        "type": "object"
      },
      "type": "array"
    }
  },
  "type": "object"
}

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 default

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

POST /api/connection/{connection_id}/last-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 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 default

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

POST /api/connection/{connection_id}/dialog/{dialog_id}/last-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 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 default

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

License

Artistic License version 2.0

Contact information

https://github.com/Nordaaker/convos