Channels Management¶
Channels Management is presently done via a list of endpoints, reachable via a common API, that let the channel administrator make CRUD operations on channels, channels categories, subscriptions and even publishing of news on the channels.
It’s only reachable via the internal MONK infrastructure interface (e.g. xxxx.localmonks.net), on port 3030, on the related environments, so:
Environment |
Endpoint |
|---|---|
Production |
|
Preprod |
|
Development |
Every endpoint supports the following operations through a simple REST API.
GET Lists all elements for that given endpoint. If you add the element identifier, in the query string, just that element is returned. You can also add one of the elements that you can use in the JSON parameters as a filter for results, and also have pagination by using the query string fields limit and skip. In the GET result, you will also always have the total number of elements, in order to prepare pagination properly.
POST Creates a new element for that given endpoint.
PATCH Updates a single element with new data. You have to pass the element identifier in the query string.
DELETE Completely removes an element: you have to pass the element identifier when you call the endpoint with the DELETE method.
Channels¶
Endpoint: /channels
Through this endpoint, you can manage channels for a given domain. If you GET it with the channel_id, for example GET /channels/1234, you will get information for just that given channel. Otherwise, you can get all the available channels. If you use one of the criterion below as a query string, you will be able to fetch only the channels pertaining to that given criterion: for example, using:
GET /channels?domain=timpersonal
You will retrieve only channels for the “timpersonal” domain.
Following, the list of supported JSON parameters that can be passed in when updating, or adding, a new channel.
Json Parameters:
Param |
Description |
|---|---|
name |
The channel name to create. Please use only alphanumeric characters |
domain |
The channel domain. Must be one of the XMPP-managed domains. |
category |
The channel category. You can fetch available categories using the /categories endpoint below |
Upon success, you will receive a JSON with the full data for the newly-created channel, also with a unique ID which identifies it.
Categories¶
Endpoint: /categories
Through this endpoint, you can create channels categories. Each channel can have only one category, and it must be one of the categories below!
If you use one of the criterion below as a query string when GET’ing, you will be able to fetch only the categories pertaining to that given criterion: for example, using:
GET /categories?domain=timpersonal
You will retrieve only categories available in the “timpersonal” domain.
Json Parameters:
Param |
Description |
|---|---|
name |
The category name to create. Use only alphanumeric characters |
domain |
The category domain. Must be one of the XMPP-managed domains. |
type |
The channel type. Must be one of “news” or “push”. For now, use “news”, as “push” will be used in the near future for evil purposes |
Upon success, you will receive all data regarding the newly-created channel category.
Publishing¶
Endpoint: /news
Through this endpoint, you can publish stuff to a given channel. All the above tricks regarding pagination and filters apply.
Json Parameters:
Param |
Description |
|---|---|
channel_id |
The channel numeric id to use. |
packet |
The full <x/> payload to send to the user. Remember to escape JSON data in the payload when sending it in the POST request |
expiration_timestamp |
The expiration timestamp for the news. If you don’t provide it, it will default to 24 hours after the publishing |
Subscription¶
Endpoint: /subscribers
Through this endpoint, you can manage subscription an unsubscriptions for users. Please notice that data returned from this endpoint can be quite a lot, and so it’s adviceable to use pagination and filters to retrieve only useful data when GET’ing stuff. When deleting a subscription, you have to use the subscriber_id in the DELETE call (see below), and also pass the channel_id in the JSON parameters, or avoid passing the channel_id in order to delete all subscription for a given user. while for the creation you can also pass the node and domain for the given user.
Json Parameters:
Param |
Description |
|---|---|
node |
The XMPP node to use. Either this, or the subscriber_id must be present |
subscriber_id |
The XMPP subscriber id to use. Either this or the node must be present |
domain |
The subscriber and channel domain. Must be one of the XMPP-managed domains. |
channel_name |
The channel name to operate with. Either this or channel_id must be present. |
channel_id |
The channel id to operate with. Either this or channel_id must be present. |
Final Note¶
Please notice that all tables are foreign key’ed with ON UPDATE CASCADE ON DELETE CASCADE. This means that:
If you delete a category, all channels of that category go down with it
If you delete a channel, all subscriptions to that channel, and all news for that channel, go down with it
If you delete a XMPP user, all subscription for that user go down with it
