soundtoys api documentation

About

We want you to contribute and play with our data...

Like many other websites these days, the Soundtoys backend has been redesigned so that most information stored about our artists and works in our database is not only available as normal web pages for human consumption, but is also exposed in a machine-readable raw data format easily digested by 3rd party software.

The information below is intended for those of you interested in working and playing with our (meta)data, build new soundtoys, come up with new ways to navigate the site, visualize the artist community, etc. If you're interested in any of these things, please do read on to get an overview of the...

REST API

The new website features a so called REST API to simply communicate with external applications using XML. REST is much simpler than other popular forms of XML based API protocols like SOAP or WS, since it is mainly relying on pre-assumptions and on HTTP's implicit semantics to interpret incoming requests:
  1. Every URI has a 1:1 mapping to an entity (resource) on this website
  2. Every URI can either be read or written(*) to by using HTTP GET or POST requests to identify the direction of the data transfer.
  3. Use HTTP status codes to determine and communicate the result of an operation
Note: At current only "Getter" methods are available for retrieving data from the Soundtoys backend in a simple to parse XML format.

Available methods

The various methods below represent the different possible axes through the data space: artist-centric, toy-centric, tags and journals.

For each of these axes, there're 2 methods available. One of them is used to retrieve the entire set of entities in summary form and the other to return a full description of an individual entity. Except for one difference, the same logical structure is used for the main website too.

Here is the current list of methods, their descriptions and links to (live) sample outputs...

Common details

Even though the XML should be fairly easy to parse and transform, it might be worth shedding some light on recurring details:
Retrieves a summary index listing of all active artists on soundtoys.net. Each artist node will contain XLinks to more complete XML descriptions as well as to API methods to directly get full information about toys or journal entries created by that artist. Currently there're no plans to expose any other personal details of an artist or group via this interface.

Returns the complete overview of a single artist's work published on the Soundtoys website. This can include the full artist statement, exhibition history, website URL, location and more importantly full details of all soundtoys and journals by that artist.

For better flexibility and more use cases each artist also has an associated data feed (example) containing 99% identical information, but exported as Atom 1.0 (RFC4287) format which is understood by most feed reader applications.

Index summary list of all artist journals and interviews on soundtoys.net, again with XLinks leading to more detailed descriptions of all related resources.
Full content, artist, date and tagging information of an individual journal entry.
Index summary list of all currently available and active soundtoys, again with XLinks leading to more detailed descriptions of all related resources.
Full details of an individual soundtoy.
Returns the list of all tags currently assigned to individual soundtoys, journals, news items or web links. For each item absolute use count and normalized use frequency is computed.

Returns a list of all content items related to the given tag or set of tags. The returned items are grouped by content type and nested inside a container node for each type.

Multiple input tags are possible, but tags have to be separated with a logical operator, which can either be "+" (logical AND, to narrow down search results) or "," (logical OR, to broaden results). For example:

Only one operator can be used per request with AND ("+") having precedence.

Questions, comments & suggestions...

Please get in touch: contact