-
Notifications
You must be signed in to change notification settings - Fork 52
Using Atom Hopper
##### Table of Contents **[Adding a New Entry](#add-new-entry)**
== [Adding One or More Categories](#add-one-or-more-categories)
**[Getting the Feed](#get-feed)**
== [Getting the Feed Head](#get-feed-head)
== [Parsing Feed Links](#parse-links)
== [Self Referencing Links with HTTP/HTTPS](#self-referencing-links)
== [Getting an Archived Feed](#get-archived)
== [Query Parameters](#query-params)
== [Paging Forward and Backward](#paging-forward-backward)
== [Getting a Single Entry](#get-an-entry)
== [Filtering Entry by Category](#filter-by-category)
== [JSON Feed Response (SHOULD NOT BE USED FOR PRODUCTION)](#json-experimental-response)
== [Weak ETag Support](#week-etag)
**[Administering Atom Hopper](#admin-atomhopper)**
== [Getting Atom Hopper Version Information](#get-atomhopper-version)
== [Checking Atom Hopper Logging](#check-atomhopper-logging)
== [Viewing Atom Hopper Metrics](#view-atomhopper-metrics)
###Adding a New Entry### An HTTP POST is used to insert new Atom entries into Atom Hopper. The following is an example of a simple Atom entry (with three categories):
<entry xmlns="http://www.w3.org/2005/Atom">
<title type="text">This is the title</title>
<author>
<name>John Doe</name>
</author>
<content type="text">Hello World</content>
<category term="MyCategory 1" />
<category term="MyCategory 2" />
<category term="MyCategory 3" />
</entry>The above Atom XML can be sent to Atom Hopper via an HTTP POST along with the following required HTTP Header:
Content-Type: application/atom+xml
- You can use whatever tool you feel comfortable with to POST this entry to Atom Hopper
- To support using SSL/HTTPS, you will need to make the appropriate changes to Apache Tomcat (or whatever application server you are using).
- Control and illegal characters must be escaped, whether XML or JSON.
Once you have posted the above Atom XML to the correct Atom Hopper endpoint you should receive an HTTP 201 (Created) response back along with the Atom XML you posted in the body.
####Adding One or More Categories####Atom Hopper can query based upon Categories (see further below for an example). To add categories to an Atom entry you must include the category element along with a term attribute:
Single Category
<category term="mycategory1" />Multiple Categories
<category term="mycategory1" />
<category term="mycategory2" />Note: Category tags are case sensitive.
###Getting the Feed###An HTTP GET is used to retrieve the Atom feed or a single entry from Atom Hopper. The HTTP GET request supports asking for the most recent entries in a feed (also called the Feed Head), a specific/single atom entry, forward and backward paging, and category searches.
Note: Control and illegal characters must be escaped in the url.
####Getting the Feed Head#### To get the feed on a default installation perform an HTTP GET against the following URL:http://localhost:8080/namespace/feed/
By default, Atom Hopper version 1.1.0 and above returns an Atom XML document as a response. As described in the later section, there is also a way to return an experimental JSON document.
The Atom XML document response from Atom Hopper will contain the following links:
<feed>
...
<link href="http://localhost:8080/namespace/feed/?marker=urn:uuid:676f3860-447c-40a3-8f61-9791819cc82f&limit=25&search=&direction=forward" rel="previous" />
<link href="http://localhost:8080/namespace/feed/?marker=urn:uuid:2de9cd50-5665-48f2-be91-d8fe06fdc471&limit=25&search=&direction=backward" rel="next" />
<link href="http://localhost:8080/namespace/feed/?marker=urn:uuid:580ea828-67a7-4f96-8c69-b4d05e81e0fa&limit=25&search=&direction=backward" rel="last" />
<link href="http://localhost:8080/namespace/feed/" rel="current" />
<link href="http://localhost:8080/namespace/feed/" rel="self" />
...
</feed>The semantics of the links are described below:
-
The current links to the current feed.
-
The last links to the last page of Atom entries in the database for the specified feed. This can be useful for finding the oldest Atom entry ever inserted for a given feed.
NOTE: The JDBC adapter uses a mock last link marker. This is done to help move some of the heavier queries off the feed head request.
-
The self link brings back the entry you're currently viewing. Keep in mind: in the example above we are hitting the feed with no parameters. This means you are requesting the most recent entries in the specified feed. If any new Atom entries have been entered, then those will appear in the descending time order (the most recent entries appear on top). See also the Self Referencing Links section below.
-
The next link allows you to page to the next page of Atom entries. The entries in the next page would be older than those in the current page. When you get to the end of the feed this link will not be present.
-
The previous link allows you to page to the previous page of Atom entries. This link is always present in the feed header and if you are at the top of the feed and you follow this link it will return an empty feed (assuming no need entries have come in since you last polled). The entries in the previous page would be newer than those in the current page.
If HTTP client sends in
Accept: */*
or
Accept: application/xml
Atom Hopper response will be an Atom XML document. Here, the same rule will apply as the above W3C HTML spec. The link element with href attribute will contain a URL and all the XML special characters will need to be escaped.
Warning: Note that when viewed in a web browser or web tool such as Poster, each & characters in a link is returned as an XML ampersand character code. To follow the link in a web browser or web tool such as Poster, you must change each XML ampersand character code to &. When using Atom Hopper from an application, this will not occur.
For example, when viewed in a web browser, the feed will return:
<feed>
...
<link href="http://localhost:8080/namespace/feed/?marker=urn:uuid:676f3860-447c-40a3-8f61-9791819cc82f&limit=25&search=&direction=forward" rel="previous" />
...
</feed>To follow this link from a web browser:
http://localhost:8080/namespace/feed/?marker=urn:uuid:676f3860-447c-40a3-8f61-9791819cc82f&limit=25&search=&direction=forward
It must be changed to:
http://localhost:8080/namespace/feed/?marker=urn:uuid:676f3860-447c-40a3-8f61-9791819cc82f&limit=25&search=&direction=forward
This should not be a concern though when using an XML parser. The XML parser will un-escape all XML special characters.
####Self Referencing Links with HTTP/HTTPS#### You will notice when the Atom XML document is returned each Atom entry will have a self-referencing link. The appearance of your self-referencing Atom entry links will depend upon whether you use HTTP or HTTPS.With HTTPS POST:
<feed>
...
<entry>
...
<link href="https://domain.com/namespace/feed/entries/urn:uuid:9b850562-d357-4cf8-8811-048a6730e869" rel="self" />
...
</entry>
...
</feed>With HTTP POST:
<feed>
...
<entry>
...
<link href="http://domain.com/namespace/feed/entries/urn:uuid:9b850562-d357-4cf8-8811-048a6730e869" rel="self" />
...
</entry>
...
</feed>An archived feed is accessed with the same URL format as a regular feed, but the feed XML is constructed slightly differently.
The header for an archive feed will look like the following:
<link href="http://localhost:8080/archive/namespace/feed/?timestamp=2013-10-23T20:45:50.888+0000&uuid=b1ee2b02-b3a9-48c2-bae5-80146f55dd87&direction=backward&limit=100" rel="self" />
<link href="http://localhost:8080/namespace/feed" rel="current" />
<link href="http://localhost:8080/archive/namespace/feed/?timestamp=2013-10-23T20:40:04.125+0000&uuid=07eb3cd1-6c87-40e3-9645-6d1788ad8de2&direction=backward&limit=100" rel="next-archive" />
<link href="http://localhost:8080/archive/namespace/feed/?timestamp=2013-10-23T20:45:50.912+0000&uuid=57a59556-af53-4414-baed-17efe2fe8594&direction=forward&limit=100" rel="prev-archive" />
<fh:archive />The semantics of the links are described below:
-
The current links to the corresponding regular (non-archived) feed.
-
The self link brings back the entry you're currently viewing.
-
The next-archive link allows you to page to the next archived page of Atom entries. When you get to the end of the archived feed this link will not be present.
-
The prev-archive link allows you to page to the previous archived page of Atom entries.
The feed will also contain an <fh:archive> XML element, denoting it as an archive feed.
| Parameter Name | Description | Data Type / Acceptable Values | Default |
|---|---|---|---|
| marker | The unique id of an Atom entry | Valid ID | none |
| direction | The direction from the current marker (or entry) to start getting more entries from | forward | backward | forward |
| limit | The number of entries returned. If the entered limit is greater than the actual number of entries, the actual number of entries will be used | 1 to 1000 | 25 |
| format | Returns the feed in specified format (Experimental) | json | none |
| search | Allows filtering of feed for only events of specified category | String | none |
Forward
http://localhost:8080/namespace/feed/?marker=urn:uuid:8439541b-b40e-4c23-b290-2820bd64257d&direction=forward
Backward
http://localhost:8080/namespace/feed/?marker=urn:uuid:8439541b-b40e-4c23-b290-2820bd64257d&direction=backward
The limit parameter may be used to control the size of each page, i.e: the number of entries Atom Hopper returns in a page. By default this limit is set to 25. The minimum limit is 1 and the maximum is 1000.
This example shows a marker set and the limit set to 50, paging forward
http://localhost:8080/namespace/feed/?marker=urn:uuid:8439541b-b40e-4c23-b290-2820bd64257d&direction=forward&limit=50
This example shows a marker set and the limit set to 50, paging backward
http://localhost:8080/namespace/feed/?marker=urn:uuid:8439541b-b40e-4c23-b290-2820bd64257d&direction=backward&limit=50
<feed>
...
<entry>
...
<link href="http://domain.com/namespace/feed/entries/urn:uuid:9b850562-d357-4cf8-8811-048a6730e869" rel="self" />
...
</entry>
...
</feed>If you send Atom Hopper an HTTP GET request with the link URL of an entry, such as the above self link, Atom Hopper will return an XML document containing the one single entry requested.
Note: The urn:uuid keyword is the unique ID of the Atom entry and will be entered by Atom Hopper.
####Filtering Entries by Category####The JDBC Data Adapter supports advanced filtering by category, including OR, NOT, and AND criteria. See details and examples at the "Advanced Filtering by Category with the JDBC Adapter" section of Using-the-JDBC-Data-Adapter.
Note: The category search functionality using the Hibernate data adapter is limited to one search item (one category term) at this time. If the query string is malformed it will be ignored and return all results with no filter.
Single category:
The entry category must be an exact match and is (currently) case sensitive. No wild cards are supported.
The following is an example of searching on a category entered as CAT1:
http://localhost:8080/namespace/feed/?search=%2BCAT1
Note: The %2B is the url encoded value of the + operator.
Multiple categories:
To perform a search on multiple categories simply append additional categories. This is demonstrated in the following example that searches for two categories (CAT1 and CAT5):
http://localhost:8080/namespace/feed/?search=%2BCAT1%2BCAT5
Note: Current searching with multiple categories is an "OR" search. Any entry with containing one or more of the categories specified will be returned. This style of search is deprecated for the JDBC Adapter.
####JSON Feed Response (SHOULD NOT BE USED FOR PRODUCTION)####THE FOLLOWING FEATURE SHOULD NOT BE USED FOR PRODUCTION
You can receive a feed in JSON format by doing the following:
http://localhost:8080/namespace/feed/?format=json
You can also send your HTTP GET request with an Accept header like this:
Accept: application/json
We use the Abdera JSON Writer to translate simple Atom entries to JSON. Make sure to fully test this with your Atom entries to ensure the JSON is properly matched.
Note: If you want to embed JSON into an Atom XML entry then make sure to wrap the JSON content in an XML CDATA section.
####Weak ETag Support####Atom Hopper supports weak entity tags (ETags). An ETag identifies a specific version of a feed. When the content of the feed changes, a different ETag is assigned. This is an efficient way of checking whether a previously-processed feed has changed.
Weak ETags are sent back in the HTTP header with a name of ETag.
A weak ETag for a feed containing more than one Atom entry looks like this:
W/"urn:uuid:21d39ce9-940b-4277-baa3-7daa3f209e76:urn:uuid:def3ba91-799f-4347-833e-d9a97d3359dc"
A weak ETag for a feed with only one Atom entry looks like this:
W/"urn:uuid:21d39ce9-940b-4277-baa3-7daa3f209e76:urn:uuid:21d39ce9-940b-4277-baa3-7daa3f209e76"
There are a couple scenarios where an ETag will not be returned:
- If the feed is empty
- If you use a marker and set the direction as forward and no entries exists after that marker
When Atom Hopper has been deployed via a WAR file (the RPM installs a WAR as well), you can perform an HTTP GET to find out what version of Atom Hopper you are running by using the following URL (modify the URL to suit your environment):
http://localhost:8080/context/buildinfo
Where context/buildinfo is whatever context you configure the AtomHopperVersionServlet to map to. You normally set this up in the web.xml of the Atom Hopper WAR file.
The AtomHopperVersionServlet will return a response similar to the following:
{"version":"1.2.15-SNAPSHOT","groupId":"org.atomhopper","artifactId":"ah-war"}
When Atom Hopper is deployed as a WAR file (the RPM installs a WAR as well) then you can perform an HTTP GET to verify logging is working (assuming your Log4J file is formatted correctly and in the /etc/atomhopper/ folder) by using the following URL (modify the URL to suit your environment):
http://localhost:8080/context/logtest
Where context/logtest is whatever context you configure the AtomHopperLogCheckServlet to map to. You normally set this up in the web.xml of the Atom Hopper WAR file.
The AtomHopperLogCheckServlet returns a response similar to the following:
["The following are messages entered into logging","Test entry for INFO logging","Test entry for WARN logging","Test entry for DEBUG logging","Test entry for ERROR logging"]