soundtoys.net - API documentation

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:

Every URI has a 1:1 mapping to an entity (resource) on this website
Every URI can either be read or written(*) to by using HTTP GET or POST requests to identify the direction of the data transfer.
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...

/api/artists
/api/artists/{id}
/api/journals
/api/journals/{id}
/api/toys
/api/toys/{id}
/api/tags
/api/tags/{id} [+id2[,id3...]]

Common details

Even though the XML should be fairly easy to parse and transform, it might be worth shedding some light on recurring details:

namespaces
...are part of the original XML specification, yet apparently still largely unused and misunderstood by many people (especially artists). Namespaces are used to logically group XML elements (or attributes) and to avoid semantic collisions. One example of this is the use of the "href" attribute, traditionally referring to a link URL of any kind. However, our API will return both normal weblinks to HTML pages, as well as links to other API methods only containing further XML data. To separate these 2 types of links, I have used the "href" attribute for HTML link targets and made use of the XLink namespace to relate other parts of the API to the current result via the attribute "xlink:href".
xml:base
This attribute of the root node specifies the base URI to be used for all XLinks. When attempting to load an XLink, the "xlink:href" attribute's value has to be appended to this "xml:base" value in order to work correctly.
item IDs
As mentioned above, every API URI maps to an unique data resource in the format of "/api/{resource_type}/{item_id}". A URI-safe version of a resource's name is used for its actual item ID. All XLinks have these IDs prepopulated. If the item ID is omitted, an index listing of all available items is returned.
dates
All dates are listed in ISO8601 format, like: 2003-05-09T16:23:42Z

/api/artists

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.

^ top

/api/artists/{id}

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.

^ top

/api/journals

Index summary list of all artist journals and interviews on soundtoys.net, again with XLinks leading to more detailed descriptions of all related resources.

^ top

/api/journals/{id}

Full content, artist, date and tagging information of an individual journal entry.

^ top

/api/toys

Index summary list of all currently available and active soundtoys, again with XLinks leading to more detailed descriptions of all related resources.

^ top

/api/toys/{id}

Full details of an individual soundtoy.

^ top

/api/tags/{id}

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.

^ top

/api/tags/{id} [+id2[,id3...]]

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:

/api/tags/shockwave+generative+kids will only return items which have been tagged with ALL 3 of those tags
/api/tags/shockwave,generative,kids will return items which haven been tagged with EITHER of these

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

^ top

Questions, comments & suggestions...

Please get in touch: contact