rss-bridge/docs/04_For_Developers/04_Actions.md

RSS-Bridge currently supports four 'actions' which it can operate:

1. Display (?action=display)
2. Detect (?action=detect)
3. List (?action=list)
4. FindFeed (?action=findfeed)

Display

The display action returns feeds generated by bridges. It requires additional parameter, some of which are specific to each bridge (see implementation details for your specific bridge). The following list contains mandatory parameter applicable to all bridges, excluding parameters that require additional options. Errors are returned for missing mandatory parameters:

Parameter	Required	Description
bridge	yes	Specifies the name of the bridge to display. Possible values are determined from the bridges available to the current instance of RSS-Bridge and the whitelist.
format	yes	Specifies the name of the format to use for displaying the feed. Possible values are determined from the formats available to the current instance of RSS-Bridge.

Detect

The detect action attempts to redirect the user to an appropriate display action for a feed based on a supplied URL. As bridges have to individually implement this it may not work for every bridge.

If an appropriate bridge is found, a 301 Moved Permanently HTTP status code is returned with a relative location for a display action. If no appropriate bridge is found or a required parameter is missing, a 400 Bad Request status code is returned.

The parameters for this action are listed below:

Parameter	Required	Description
url	yes	Specifies the URL to attempt to find a feed from. The value of this should be URL encoded.
format	yes	Specifies the name of the format to use for displaying the feed. This is passed to the detected display action. Possible values are determined from the formats available to the current instance of RSS-Bridge.

List

The list action returns a JSON formatted text containing information on all bridges available to the current instance of RSS-Bridge. Inactive bridges (not whitelisted) are included as well. Broken bridges are also included, but with limited parameters (only "status": "inactive").

This example shows JSON data for a single bridge:

{
    "bridges": {
        "ABCTabs": {
            "status": "active",
            "uri": "https:\/\/www.abc-tabs.com\/",
            "name": "ABC Tabs Bridge",
            "parameters": [],
            "maintainer": "kranack",
            "description": "Returns 22 newest tabs"
        }
    },
    "total": 1
}

The top-level JSON object contains two parameters:

• bridges: A collection of bridges
• total: The total number of bridges

{
  "bridges": { },
  "total": 0
}

bridges

The bridges parameter is a collection of bridge objects. The name of each object represents the name of the bridge as needed for the display action. Each object contains parameters, most of which are optional. The following table summarizes the parameters:

Parameter	Optional	Description
status	No	Indicates the status of the bridge. Possible values are 'active' and 'inactive'. Only active bridges can be used for the display action.
uri	Yes	Returns the URI of the bridge, as returned by the getURI function of the bridge.
name	Yes	Returns the name of the bridge, as returned by the getName function of the bridge.
parameters	Yes	Returns the PARAMETERS object of the bridge
maintainer	Yes	Returns the name(s) of maintainer(s) for the bridge
description	Yes	Returns the description of the bridge

total

This parameter represents the total number of bridges available to the current instance of RSS-Bridge.

FindFeed

The findfeed action attempts to list all available feeds based on a supplied URL for the active bridges of this instance. As bridges have to individually implement detectParameters, this it may not work for every bridge.

If one or more bridges return a feed, a JSON data array structure is returned. If no feeds were found, a 404 Not Found status code is returned. If a required parameter is missing, a 400 Bad Request status code is returned.

For each feed, the whole feed URL is sent in the url member, the feed specific bridge parameters metadata in the bridgeData member and the Bridge metadata in the bridgeMeta member.

This example shows JSON data for the NASA Instagram account URL (https://www.instagram.com/nasa/) using the Html format :

[
    {
        "url": "https://rssbridge.host/?action=display&context=Username&u=nasa&bridge=InstagramBridge&format=Html",
        "bridgeParams": {
            "context": "Username",
            "u": "nasa",
            "bridge": "InstagramBridge",
            "format": "Html"
        },
        "bridgeData": {
            "context": {
                "name": "Context",
                "value": "Username"
            },
            "u": {
                "name": "username",
                "value": "nasa"
            }
        },
        "bridgeMeta": {
            "name": "Instagram Bridge",
            "description": "Returns the newest images",
            "parameters": {
                "Username": {
                    "u": {
                        "name": "username",
                        "exampleValue": "aesoprockwins",
                        "required": true
                    }
                },
                "Hashtag": {
                    "h": {
                        "name": "hashtag",
                        "exampleValue": "beautifulday",
                        "required": true
                    }
                },
                "Location": {
                    "l": {
                        "name": "location",
                        "exampleValue": "london",
                        "required": true
                    }
                },
                "global": {
                    "media_type": {
                        "name": "Media type",
                        "type": "list",
                        "required": false,
                        "values": {
                            "All": "all",
                            "Video": "video",
                            "Picture": "picture",
                            "Multiple": "multiple"
                        },
                        "defaultValue": "all"
                    },
                    "direct_links": {
                        "name": "Use direct media links",
                        "type": "checkbox"
                    }
                }
            },
            "icon": "https://www.instagram.com//favicon.ico"
        }
    }
]

The parameters for this action are listed below:

Parameter	Required	Description
url	yes	Specifies the URL to attempt to find a feed from. The value of this should be URL encoded.
format	yes	Specifies the name of the format to use for the URL of the feeds. This is passed to the detected display action. Possible values are determined from the formats available to the current instance of RSS-Bridge.