create-external-feed-subscription action endpoint

URL: /applications/<id>/create-external-feed-subscription.<format>

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.

Feed Identifiers

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



Filters


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:










Supported Methods







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,

))