txtr (1.22.2) release date: 09:57 02.02.2012
On this page, we've put together the API entry points that you will most likely find interesting.
If you haven't done so already, reading the background page now would be a good idea.
Depending on the protocol you use, your calls will have to look differently. To get an idea of how calls should look like in JSON or REST, for example, have a look at the RPC page.
For most of the Reaktor methods (and the delivery API) you will need a token. A token (some might call it a session ID) is a secret that identifies you with the server. Tokens will time out after some time of inactivity.
To obtain a token, you have to call WSAuth.authenticateUserByName(userName, password, boolean stickyToken).
Pass your user name, the SHA1 hash of your password, and a boolean that indicates if the token should be sticky.
The SHA1 hashing of passwords is obviously not a security feature - we just don't like to send people's passwords around in cleartext.
Sticky tokens will never time out, so it's your responsibility to make sure you don't lose or leak them. As a rule of thumb: Don't use sticky tokens.
When you're done, please call WSAuth.deAuthenticate(token) and the token will be invalidated.
There are three ways to create documents: Upload, create "empty" (metadata-only) documents, or import documents from the WWW.
Uploading is done via the delivery API. To upload a document, POST the binary content of the document to the following URL:
http://txtr.com/delivery/document/upload?token=$token&fileName=$fileName
The Reaktor will respond with an "OK", followed by a newly created document ID (udid) that can be used for further manipulation of the document.
Empty documents can be created by a remote procedure call to
WSDocMgmt.createDocument(token, displayName, List categoryIDs, Map attributes, List tags)
Parameters:
| token | a valid txtr token |
| displayName | a human-readable document display name. Normally, the Reaktor will come up with a display name, but for some formats, infering a display name can be quite hard. So you should supply one here as a fallback. |
| categoryIDs | A list of category IDs of metadata attribute categories to be added to the document. This may be empty, in which case only the default category will be added. |
| attributes | A map of metadata attribute IDs to attribute values. Only the attributes that you wish to set need to be present in the map. You can leave the map empty to indicate that you don't want to set any attributes. |
| tags | A list of tags to be added to the document. May be empty. |
Documents can be imported from the web by a remote procedure call to
WSDocMgmt.createDocumentFromWeb(token, url, displayName, List categoryIDs, Map attributes, List tags)
Parameters:
| token | a valid txtr token |
| url | the URL of the document data on the web. |
| displayName | a human-readable document display name. Normally, the Reaktor will come up with a display name, but for some formats, infering a display name can be quite hard. So you should supply one here as a fallback. |
| categoryIDs | A list of category IDs of metadata attribute categories to be added to the document. This may be empty, in which case only the default category will be added. |
| attributes | A map of metadata attribute IDs to attribute values. Only the attributes that you wish to set need to be present in the map. You can leave the map empty to indicate that you don't want to set any attributes. |
| tags | A list of tags to be added to the document. May be empty. |
Document metadata is organized into key-value pairs, called attributes. Any attribute belongs to one ore more attribute categories. A document has one, ore more, attribut categories attached.
To set an attribute, you'll have to:
A list of all available attributes in their categories can be found at the end of this page. Note that the default category (with attributes such as title, subtitle and author) will always be present.
To add an attribute category to a document, call: WSDocMgmt.addDocumentAttributeCategory(token, List documentIDs, categoryID)
Parameters:
| token | a valid txtr token |
| documentIDs | a list of IDs of documents where the category is to be added |
| categoryID | a category ID (see this) of an attribute category to be added |
To set document attributes, call: WSDocMgmt.changeDocumentAttributes(token, List documentIDs, Map newAttributes)
Parameters:
| token | a valid txtr token |
| documentIDs | a list of IDs of documents whose metadata is to be updated with the new values |
| newAttributes | a map, attribute IDs (see this) to values. |
WSDocMgmt.changeDocumentTags(token, List documentIDs, List tagsToAdd, List tagsToRemove)
Parameters:
| token | a valid txtr token |
| documentIDs | a list of IDs of documents whose tags are to be modified |
| tagsToAdd | a list of tags to add to the documents, may be empty |
| tagsToRemove | a list of tags to be removed from the documents, may be empty |
Documents in the Reaktor can be accessed through txtr.com by their owner, by their unique ID. But they are not visible by default, neither through search nor through navigation in the UI.
To make a document public, it needs to be in a public collection. Collections consist of two parts: Lists and views. Lists specify what documents can be seen, and who can see them; views specify the appearance of lists on txtr.com.
You can create lists without views. Lists without views are fully functional, but they won't show up on txtr.com. Documents in those lists will be found by the txtr.com search, though.
If you want to work with txtr.com views, you'll also have to deal with view sets - these show up on txtr.com as tabs.
Here's a list of list/view handling methods:
WSViewMgmt.createViewSet(token, Map initialProperties) |
creates a new view set |
WSViewMgmt.getViewSets(token, user) |
returns a list of all existing view sets of the given user (i.e. you) |
WSViewMgmt.createViewAndEmptyList(token, viewSetID, listName, description, Map initialViewProperties) |
Creates a view and the underlying, empty, list. |
WSListMgmt.addDocumentsToList(token, listID, List documentIDs, int addAt) |
Adds documents to a list, at a given position |
WSListMgmt.removeDocumentsFromList(token, listID, List documentIDs) |
Removes document from a list |
WSListMgmt.changeListType(token, listID, ListType newListType, boolean resetUserPermissions) |
Changes the list type (its visibility) to either SECRET, PRIVATE, or PUBLIC Note that the visibility types are ListType constants, not Strings. If you're using JSON, see the notes on encoding types on the rpc calls page. |
WSListMgmt.getList(token, listID, int offset, int count) |
Retrieves a list object |
WSDocMgmt.getDocumentsInList(token, listID, int offset, int count) |
Retrieves actual document objects (with metadata) from a list |
For binary data access, versioning, and conversion, use the delivery API.
For information on accessing the txtr Catalog, see the catalog API.
There are a lot more methods to call than those documented on this page - some of them untested, some of them well-hung and under heavy use by txtr.com. These methods and components are documented in the Expert API documentation.
The Expert API documentation is generated from the Java sourcecode of our interfaces. Those of you familiar with Java will easily recognize this as JavaDoc output. If you're doing a Java RPC client, these classes are what you will be actually using. For all other kinds of client, no matter if you're using REST, JSON or SOAP, there's always a simple mapping of the names and conventions used in the Expert API documentation to your protocol and client. (The RPC page has some hints on this; you'll figure out the rest pretty quickly.)