Standard Representations
hideThe REST API is built upon notions of resources and representations. The following formats are commonly used for representations of assorted resources within this API.
In the text below, we will frequently refer to collections and entities. An entity is usually some obviously singular resource, such as a page, whereas a collection is usually a group of such singular resources, such as all pages in a given workspace.
HTML (text/html)
When requesting text/html the system returns an HTML formatted fragment that contains a representation of the requested resource. For a collection this a list of links to the entities in the collection. For an entity one of two fragments are returned:
- If the entity is a page the HTML formatted version of the file is returned
- Otherwise, an HTML table of elements that describe the resource is returned
When browsing the API from a browser, the html type is usually returned. This makes it possible to explore the API without any code.
JSON (application/json)
JSON is a subset of Javascript used for data-interchange. There are parsers and generators available in many languages, making it quite useful for remote interactions, such as REST APIs. Because the data is proper Javascript, JSON is ideal for use with AJAX web hacks that use XMLHttpRequest, but it is just as usable in other settings.
When a collection returns JSON, it is an array of hashes. Each hash represent an individual entity contained in the collection. An entity that returns JSON is one hash. The hashes contain name value pairs. Generally there will be at least name and uri. See the backlinks of this page for resources that use application/json.
Wikitext (text/x.socialtext-wiki)
Only used for wiki pages in the workspace, this is the native Socialtext wikitext format. The x. in this MIME Type indicates that the MIME Type is experimental (as per RFC 4288). By 1.0, this type should be replaced by text/vnd.socialtext.wiki.
The text/x.socialtext-wiki representation is used to PUT or POST a page, or when using GET to retrieve a single page entity.
Plaintext (text/plain)
The text/plain representations are UTF-8 encoded strings.
For GET requests against collections, the text is delivered as a linefeed separated list, the name of an entity for each line in the list.
Only one entity supports a text/plain GET: tag.
The tags collection supports a text/plain POST to add a tag to a workspace or page. The body of the post is a text string containing the string that represents the tag.
