 |
 |
 |
||||||||||
|
Table of Contents
PubSub Concepts, Inc., operates a real-time Publish & Subscribe service. The company processes data from numerous sources and delivers information to subscribers. The PubSub REST API is an alternative delivery mechanism for the PubSub service. Subscribers who use the API specify the particular information they're interested in by creating a subscription. When messages are published which meet the criteria expressed in the subscription, PubSub makes an HTTP POST call to the URL specified in the subscription. This POST transaction contains the body of the message that matches the subscriber's specified criteria, as well as some information related to the susbcription. Unlike RSS delivery, which requires periodic polling by the client, REST delivery notifies subscribers of new information in real time. However, in order to use REST delivery you must have access to a publicly visible web server, and be able to run scripts or CGI processes on that server. Before using the PubSub REST API, please ensure that you have access to a publicly-addressable web server (it must have a static IP or a domain name), and that you can run scripts or CGI processes on the machine. You do not need your own domain name or your own IP address. You do not need to use a particular scripting language, and you do not need any privileges on the machine. Virtual host accounts are fine. All you need is the ability to handle HTTP POST transactions - in general, if you can host a web form, you can receive PubSub messages. In the PubSub system, subscriptions are stored centrally and are matched against messages as messages are published. If a published message matches one or more subscriptions, that message is delivered to the registered subscriber. Depending on the type of subscription, a message may be delivered immediately or may be collected for batch delivery. In the case of the PubSub REST API, messages are delivered to subscribers immediately after a match is found. If a published message matches a particular REST subscription, the PubSub system makes an outbound HTTP POST call to the URL associated with the subscription. This POST transaction includes the body of the message as well as some information relevant to the particular subscription, including a subscription "token". The server must return the token in the body of the HTTP response. If the PubSub system fails to connect to the server or fails to receive the correct token more than 7 times in sequence, the subscription will be automatically canceled. The intent of this automatic cancellation is to prevent accidental delivery to an unauthorized URL, as might occur if you mistype a web address. In this event the subscription will be canceled before too much traffic is sent. However, this means that you must have at least a simple script in place prior to confirming a subscription; otherwise, you may run the risk of having your subscription canceled before you are ready to use it. Before creating a subscription, please install a script that is capable of responding to PubSub messages. The section below includes both a sample script (in PHP) and a utility program (in Perl) for testing script files. This section should contain enough information for you to get a REST subscription up and running. If this section isn't clear enough or we've left something out, please let us know how we can improve it. Set up a simple script file on your server The best way to get started is to use a very simple script on your server. This will ensure that your subscription isn't canceled accidentally while you're preparing the script, and it will make testing easier down the road. For example, you can create a simple script with just a few lines of PHP:<?php // get the POST parameter that contains the subscription "token" $token = $_POST["subscription_code"]; // return the token as the body of the response echo $token; // that's it! exit; ?> Before you subscribe, you may want to test your script file for compliance. PubSub provides a simple perl script that you can use to test your program: https://www.pubsub.com/REST/check.pl Download the script, change the $url variable and run it to see if your script works as expected. This script will send a POST message to the indicated URL with a sample token and a simple message. If the script succeeds, you can continue by creating a subscription. If not, you may want to double-check your script file or its location. Create a new PubSub REST subscription
PubSub subscriptions are not like web search results - in many cases, you may not see results for some time. Remember that with the PubSub service, you will only receive messages that are published after your subscription has been created. Therefore it may be difficult to know if your application is working properly. We recommend that as part of building a REST application, you create a subscription using the PubSub RSS delivery mechanism. If you create an RSS subscription with identical query terms, you can use the RSS subscription to verify the operation of your REST application. Your use of the PubSub REST API service (the "service") is governed by the PubSub Terms of Service and Conditions of use as defined in this section. |
||||||||||||