create-external-feed-subscription action endpoint
This endpoint allows an application to subscribe to one or more external feeds. These can be syndicated web content feeds (Atom or RSS) or TypePad content matching particular keywords. Items from these feeds will be delivered via an HTTP POST ping to a callback URL specified by the application. The subscription can include filters that TypePad will apply to each item to determine whether or not to deliver it.
In order to create a subscription for an application, or to view or modify that subscription subsequently, the request must be authenticated with the application's anonymous access tokens.
When a subscription is successfully created, the endpoint returns a response containing an ExternalFeedSubscription object. The client must store the urlId included in this response in order to be able to manage the subscription. although it can also be obtained through the /applications/<id>/external-feed-subscriptions endpoint, which returns a list of all subscriptions belonging to the application.
NOTE: Subscriptions to feed idents other than typepad: are only available to Six Apart partners.
The feedIdents property submitted in a request to this endpoint is a list of one or more strings, each of which is a feed identifier: either the http: or https: URI of an XML feed, or a string beginning with typepad: that specifies a keyword to subscribe to across all TypePad content. Both types of identifiers may be included in a subscription.
Some examples of identifiers:
- http://profile.typepad.com/typepad/activity/atom.xml - The activity of The TypePad Team across the whole of TypePad.
- http://everything.typepad.com/blog/atom.xml - The content of the Everything TypePad blog.
- typepad:cat - All posts containing the word "cat" across the whole of TypePad.
- http://api.flickr.com/services/feeds/photos_public.gne?tags=unicorn&lang=en-us&format=rss_200 - All posts added to this feed of photos tagged "unicorn" on Flickr.
You can add more feeds to a subscription after it's created, or remove feeds from it; see Managing a Subscription, below.
Callback URL Verification
Before your subscription can be saved, TypePad must confirm that you legitimately own the callbackUrl. It does this by pinging the URL with a GET request containing the verifyToken provided in the API request, and a challenge string that the script receiving the callback must echo back to TypePad. This is implemented according to the PubSubHubbub specification for a "Hub Verifies Intent of the Subscriber" ping, with the following differences:
- No hub.topic is included
- The hub.verify_token is always included, meaning that the verifyToken property in the request to this endpoint is required.
One or more filterRules may optionally be specified. These rules apply to all feeds subscribed to. Each filter rule is a sequence of matching tokens separated by spaces.
The most basic form of matching token is a simple keyword, which matches any item which contains that keyword in any of its properties. If a set of keywords are included in quotes, these words must appear together in any of the item's properties.
Matching tokens can be prefixed with title: or content: to match only within the item's title and content respectively.
The symbol - (minus) can be prefixed to any matching token to negate its meaning.
If multiple rules are specified, they will be treated as "OR" clauses; a feed item will pass the filter if its text matches any of the rules.
Receiving Callback Pings
Feed items are delivered to the subscription's callbackUrl in an HTTP POST request that follows the PubSubHubbub specifications for Content Distribution. The receiving script should process the item as it sees fit, and respond to the request with a 2xx status code indicating success.
If a secret was provided along with the subscription, an X-Hub-Signature header will be included in the request according to the Authenticated Content Distribution specification.
Managing a Subscription
To inspect and update a subscription after its creation, use the following endpoints:
- /external-feed-subscriptions/<id> to view the ExternalFeedSubscription object
- /external-feed-subscriptions/<id>/feeds to view a list of the feed identifiers currently included in the subscription
- /external-feed-subscriptions/<id>/add-feeds to add more feed identifiers to the subscription
- /external-feed-subscriptions/<id>/remove-feeds to remove feed identifiers from the subscription
- /external-feed-subscriptions/<id>/update-filters to set the subscription's filterRules
- /external-feed-subscriptions/<id>/update-notification-settings to change the subscription's callbackUrl and secret
- Make a DELETE request to /external-feed-subscriptions/<id> to remove the subscription from the system entirely
|POST||Subscribe the application to one or more external feeds.|
POST Request Object Type
This endpoint accepts the following properties in POST requests:
- callbackUrl (string)
- (Required) The URL which will receive notifications of new content in the subscribed feeds.
- feedIdents (array<string>)
- (Required) A list of identifiers of the initial set of feeds to be subscribed to.
- filterRules (array<string>)
- A list of rules for filtering notifications to this subscription; each rule is a query string using the search API's syntax.
- secret (string)
- An optional subscriber-provided opaque token that will be used to compute an HMAC digest to be sent along with each item delivered to the callbackUrl.
- verifyToken (string)
- (Required) A subscriber-provided opaque token that will be echoed back in the verification request to assist the subscriber in identifying which subscription request is being verified.
Response Object Type
This endpoint returns an object with the following properties:
- subscription (ExternalFeedSubscription)
- The subscription object that was created.
Client Library Methods for PHP
- Subscribe the application to one or more external feeds.
$tp->applications->createExternalFeedSubscription(array( # Required Parameters "id" => $id, "payload" => $payload, ))