The Ape

I’ve put up an Atom Protocol Exerciser at www.tbray.org/ape. It might evolve to become a sanity-checking tool something along the lines of the Feed Validator. I don’t want to call it a “validator” because a feed can be said unambiguously to be valid, or not; but a publishing-system interface might be unusably buggy or slow or have moronic authentication policies; all the Exerciser (let’s just say “the Ape” for short) does is perform a bunch of operations that a typical APP client might, and report the results. Also I’ve taken liberties in reporting some things that aren’t covered by the spec that implementors might want to know about. One of the most useful things the Ape does is provide a complete trace of exactly what the client and server sent back and forth to each other; immensely helpful as a debugging aid. Quite a few interesting war stories have been coming out of the Ape-building process. I’ll keep this post updated with the current Ape status. [Latest: i18n is back, and Elias Torres has a guinea-pig APP end-point to try it out on.]

How Can You Try It? · Best of all, use your own nascent Atom-Protocol server. In the interim, Elias Torres has wired up APP to WordPress (see also here), and graciously invited the world to test his; the URI is http://torrez.us/code/wp-app/demo/app.php, while the username and password are both demo. Plug in those values and watch the Ape expose some minor problems and give you a nice readout of the client/server traffic.

How Can You Help? · This has been tested on quite a collection of APP endpoints, but it’s still young, and there’s a chance that users will be debugging the Ape at the same time as their own implementation. So if the Ape goes weird or is accusing you of a bug you don’t think you have, it’s likely not your problem; let me know.

Now that I’ve got the basic framework down, it’s pretty easy to add tests. So please suggest APP tests.

What Does It Do? · The Ape has one required argument, the service document URI. Optionally, you can provide a username/password pair (Basic and Basic+TLS work at the moment) and the names of collections you want Ape to use for posting new entries and media files. Here’s what the Ape does:

1. Retrieves the Service doc, verifies that it can be fetched and is served as application/atomserv+xml.

2. Verifies that it’s well-formed.

3. Validates it against the non-normative RNC schema from the protocol-09 Working Group draft. Removed until I go back to JRuby or port RNV or something.

4. Lists the collections found in the service document, and the value of each one’s accept field.

5. Finds a collection to use in posting test entries; if no name is provided, picks the first.

6. Finds a collection that will accept image/jpeg postings; if no media-collection argument is provided, it picks the first available one that matches.

7. Retrieves the entries collection, makes sure it’s served as application/atom+xml, that it’s well-formed, and that it validates against the non-normative Atom schema from RFC4287.

8. Lists the entries currently found in the entries collection.

9. Posts a new entry to the entries collection, and reports on the success of the POST operation and the entry’s server-assigned location.

10. Verifies that the URI in the Location header in the Post response can be dereferenced to produce an Atom Entry that is consistent with that posted.

11. If the entry-creation POST sends back a body, checks whether its title, summary, and content are the same as that posted. The entry’s title is “From the <APE> (サル)”.

12. Re-fetches the entries feed, verifies that the new entry’s ID shows up there, and that the version in the feed has the same title, summary, and content.

13. Reports whether foreign markup (the posted entry has a dc:subject child) is preserved in the online version.

14. Checks whether the online version has a link@[rel=edit] URI.

15. PUTs a modified version of the entry to the edit URI.

16. Re-fetches the entries feed to verify that the update is reflected in the entry.

17. Deletes the entry and reports the success of the DELETE operation.

18. Re-fetches the entries feed to check that the deleted entry is no longer there.

19. If there’s no collection that accepts image/jpeg, that’s all. Otherwise, posts a small picture with a Title header saying “Picture of the APE” and reports on the success of the POST operation.

20. Verifies that there’s an appropriately-served media link entry at the URI returned in the Location header.

21. Verifies that the image can be retrieved as posted from the URI specified in the src attribute of the media link entry’s content element.

22. Deletes the media link entry and reports on the success of the DELETE operation.

23. Re-fetches the media feed and checks that the media link entry no longer appears.

To-Do · Please add to this section!

• Internationalization sanity-check; this was actually in an earlier version but fell by the wayside while chasing a JRuby bug, should be easy to add back in.

• Media resources and media link entries.

• Authentication options beyond Basic+TLS.

• Try to change an entry ID with a PUT, and report the results.

• Release the source code so you can run this locally against your own engine without having to use my website.

• Improve the diagnostics. For example, the posted summary might differ from the one in the feed because there isn’t any in the feed, or because it’s been converted from whatever you sent to type="html". Added a complete readout of the client/server dialog.

• Pretty up the ugly web-site. Anyone know of an appealing royalty-free picture of an ape grooming another?

• Categories.

• Make the changes that fall out of the imminent protocol-10 APP draft.