Newstex accepts feeds in multiple different transmission methods, and multiple different formats. You may deliver any format using any transmission method.
There are two primary methods of delivering stories to Newstex. Each method has it's own merits, depending on how fast you need your stories to be received.
Newstex has the ability to pull stories down via an HTTP(s) URL hosted by you. Using this method, several servers will hit your system every 15 minutes to grab any updates you may have posted. Servers must always provide at least the last 30 minutes worth of information, and it must not take more then 30 seconds to retrieve your entire feed.
We also provide the ability to give us next_page references in your feed, which will allow us to page through results so we may retrieve more stories if you have a high volume of stories.
A primary feed may be provided which contains multiple links to different feeds that must all be pulled in.
A url attribute may be used to specify the location of a story body.
You may require a Username/Password combination using either Digest or Basic authentication.
Newstex also allows you to push content to us as it arrives in your system. This is done by performing a POST operation on a URL provided to you in your contract agreement. You may use any transmission method you desire as the body of this POST request.
Important Note: You must re-try any requests that return any 5xx HTTP status codes. Any Status code other then a 2xx indicates an error. If the status code is in the 4xx range, then there is an error you must correct before re-trying.
You must authenticate yourself using one of the following methods:
- Provide a username/password using [Basic HTTP authentication (http://en.wikipedia.org/wiki/Basic_authentication)
- (Preferred) Provide an appropriate Etag header which is a signature of your request using HMAC and sha256 hashing against the body of your document along with a secret key we provide
PHP implementation of the HMAC signature method can be found here: http://www.php.net/manual/en/function.hash-hmac.php. In simplest terms you would use:
$Sig = base64_encode(hash_hmac('sha256', $Request, $SecretKey, true));
$Request is the entire body of the request,
$SecretKey is the key we provide you, and
$Sig is the value you would set to the Etag header.
As an alternative method to the HTTP protocol, you may also push files to Newstex via FTP. This method will require you to push to multiple servers for each file you wish to send for redundancy purposes.
If you elect this option, you will be provided with a username, password, and two FTP server addresses where you will be required to push your files to. Each File you push must have a unique name
Important Note: You must verify that you received a successful message on pushing the file, and you should also verify the file on our system is the same size as the one you submitted.
Important Note: Your files will only be available to you until you disconnect, on subsequent connections you will not be able to retrieve that file.
This section will go over the different formats for stories that we accept. This is not to be confused with transmission types, such as HTTP Push or HTTP Pull.
We accept any standard RSS format. Each story must contain at least the following elements:
All other meta is optional. If you provide a
<link> tag we assume the story can be shared using this URL publicly.
We also accept ATOM feeds, which simply contain next links within the base feed object:
<link rel="next" url="http://example.com/my_next_page.atom" />
This is useful in HTTP PULL only.
We also accept custom XML formatting, for which we require a specification before implementation so we can properly map fields. Any XML format must provide at the very minimum a unique ID, a title or headline, a publication date, and the story body. We strongly discourage using entirely new XML standards, but we do allow for adding custom namespaces with extra metadata within a standard RSS formatted feed.
For publishers who want to deliver the most robust amount of metadata, we also allow custom JSON to be used, which provides us with at least a unique ID, publication date, and story body. We also allow for categories, topics, links, and tickers.
All formats must provide the story body in XHTML or plain text. If you need any form of formatting on your story, it must be provided in XHTML.