This project is read-only.
TODO: Add Effects as first class resources; Add section of authentication, authorization; Add section on response bodies with failed requests; Add a how to for common tasks; Add schema for requests and responses; Divide into multiple pages

Introduction

Introduction to JamNet goes here.

Overview

Overview of the the JamNet project goes here.

The JamNet Service

JamNet uses a RESTful service architecture in order to support the largest swath of clients. A description of both the resources exposed by the service and the URI space that the resources inhabit is provided below along with example request and response messages.

The JamNet Resources

The JamNet service exposes the following resources:
  • Users: Users have a login/password, first and last name and an email address. A user's login uniquely identifies the user.
  • Samples: Samples are fragments of audio in the WAV file format and associated metadata such as: the name of the sample, a description of the sample, tags associated with the sample, the duration of the sample, the login of the user that uploaded the sample, the date and time the sample was uploaded, and a unique integer id for the sample. Samples are immutable and while users can upload new samples, only the service administrators can delete samples.
  • Projects: Projects are a collection of applied samples arranged in an interesting way by one or more users to create a song. An applied sample, is a sample with an associated offset (the time interval from the beginning of the song to the beginning of the sample) and a collection of effects. An effect manipulates the aural properties on the sample in some manner. Example effects might include gain, reverb, or equalization. Projects also include metadata such as: the name of the project, a description of the project, tags associated with the project, and the login of the the owner and contributors of the project. A project can only have a single owner. The owner is the the user that created the project and the only user that has the authority to include or remove contributors from the project. Contributors, along with the owner, may retrieve and update the project by adding, removing, or changing the applied samples. Projects are versioned, such that updates don't irrevocably change the state of the project, but instead create a new version of the project. Owners and contributors are then able to retrieve previous versions of the project. Possible Feature: Contributors are able to branch from a project and become the owner of the new branch. The owner is also the only user that is authorized to publish a project as a song (see below).
  • Songs: A song is a published project. A song is a WAV file that can be retrieved by anyone. A song can be created, updated or deleted only by the owner of the project from which the song is published. Songs also include metadata such as: the name of the song, a description of the song, tags associated with song, and the login of the the owner and contributors of the song.

The JamNet URI Space

For each resource, the valid URI space and the associated HTTP verbs are provided below. Example request and response message in xml are provided to illustrate how the resource is exposed.

Users: GET <base_address>/Users?skip=<skip>&top=<top>&contains='<contains>'

Returns a list of users.

Parameter Default Valid Range Description
skip 0 >=0 The number of users to skip before including users in the returned list.
top 25 >0 The maximum number of users to include in the returned list.
contains NA string of alphanumeric characters in single quotes Filters the list of users to only include those whose first and last name concatenated (separated by a single space) contains the given string; matching is case insensitive.

EXAMPLE REQUEST:
GET <base_address>/Users?skip=5&contains='Bob'

EXAMPLE RESPONSE:
<Users href="<base_address>/Users?skip=5&top=25&contains='Bob'" skip="5" top="3" contains="Bob">
  <User href="<base_address>/Users/bobg">
    <Login>bobg</Login>
    <FirstName>Bob</FirstName>
    <LastName>Gutherie</LastName>
    <Samples href="<base_address>/Samples?author='bobg'"/>
    <Projects>
      <Owner href="<base_address>/Projects?owner='bobg'"/>
      <Contributor href="<base_address>/Projects?contributor='bobg'"/>
    </Projects>
    <Songs>
      <Owner href="<base_address>/Songs?owner='bobg'"/>
      <Contributor href="<base_address>/Songs?contributor='bobg'"/>
    </Songs>
  </User>
  <!-- Additional users -->
</Users>

Users: GET <base_address>/Users/<login>

Returns a single user with the login given by 'login'.

EXAMPLE REQUEST:
GET <base_address>/Users/bobg

EXAMPLE RESPONSE:
<User href="<base_address>/Users/bobg">
  <Login>bobg</Login>
  <FirstName>Bob</FirstName>
  <LastName>Gutherie</LastName>
  <Samples href="<base_address>/Samples?author='bobg'"/>
  <Projects>
    <Owner href="<base_address>/Projects?owner='bobg'"/>
    <Contributor href="<base_address>/Projects?contributor='bobg'"/>
  </Projects>
  <Songs>
    <Owner href="<base_address>/Songs?owner='bobg'"/>
    <Contributor href="<base_address>/Songs?contributor='bobg'"/>
  </Songs>
</User>

Users: POST <base_address>/Users

Creates a user with the given login, first and last names as given in the request body. A password must also be supplied via basic authentication. If the request is successful, the response body will be equivalent to a GET <base_address>/Users/<login>. Otherwise, the HTTP status code will reflect the cause of the request failure.

EXAMPLE REQUEST:
POST <base_address>/Users

<User>
  <Login>maryt</Login>
  <FirstName>Mary</FirstName>
  <LastName>Thatcher</LastName>
</User>

Users: PUT <base_address>/Users/<login>

Allows a user to update his/her first and/or last names. A user's login can not be changed. The response body will be equivalent to a GET <base_address>/Users/<login>.

EXAMPLE REQUEST:
PUT <base_address>/Users/maryt

<User>
  <Login>maryt</Login>
  <FirstName>Mary</FirstName>
  <LastName>Guthrie</LastName>
</User>

Samples: GET <baseaddress>/Samples?skip=<skip>&top=<top>&author='<author>'&tags='<tags>'&before='<beforedatetime>'&'after='<after_datetime>'

Returns a list of samples.

Parameter Default Valid Range Description
skip 0 >=0 The number of samples to skip before including samples in the returned list.
top 25 >0 The maximum number of samples to include in the returned list.
author NA any valid login in single quotes Filters the list of samples to only includes samples uploaded by the given user.
tags NA a comma-separated list of tags in single quotes Filters the list of samples to include only samples that contain one or more of the given tags
before NA a date time (RFC 1123 format) Filters the list of samples to include only samples that were uploaded before the given date time
after NA a date time (RFC 1123 format) Filters the list of samples to include only samples that were uploaded after the given date time


EXAMPLE REQUEST:
GET <base_address>/Samples?top=5&tags='snare drum, bass drum'

EXAMPLE RESPONSE:
<Samples href="<base_address>/Samples?skip=0&top=5&tags='snare drum, bass drum'" skip="0" top="5" author="" 
    tags="snare drum, bass drum" before="" after="">
  <Sample href="<base_address>/Sample/5">
    <Id>5</Id>
    <Name>Bob's wicked drum beat</Name>
    <Description>A wicked drum beat that I recorded in my basement.</Description>
    <Tags>
      <Tag>snare drum</Tag>
      <Tag>4/4 time</Tag>
    </Tags>
    <Duration>0:01:12.32</Duration>
    <UploadedOn>Sun, 06 Nov 2009 08:49:37 GMT</UploadedOn>
    <Author href="<base_address>/Users/bobg">bobg</Author>
    <Media href="<base_address>/Sample/5/Media.wav"/>
  </Sample>
  <!-- Additional Samples -->
</Samples>

Samples: GET <base_address>/Samples/<id>

Returns a single sample with the given 'id'.

EXAMPLE REQUEST:
GET <base_address>/Samples/5

EXAMPLE RESPONSE:
<Sample href="<base_address>/Samples/5">
  <Id>5</Id>
  <Name>Bob's wicked drum beat</Name>
  <Description>A wicked drum beat that I recorded in my basement.</Description>
  <Tags>
    <Tag>snare drum</Tag>
    <Tag>4/4 time</Tag>
  </Tags>
  <Duration>0:01:12.32</Duration>
  <UploadedOn>Sun, 06 Nov 2009 08:49:37 GMT</UploadedOn>
  <Author href="<base_address>/Users/bobg">bobg</Author>
  <Media href="<base_address>/Samples/5/Media.wav"/>
</Sample>

Samples: POST <base_address>/SampleUpload

Starts the process for creating a new sample. The user supplies the metadata for the sample in the request, and the response provides a URI to which the user must PUT the actual .WAV file in order to complete the sample creation process. The same credentials must be used with the POST and the subsequent PUT. The sample does not exist until the .WAV file has been uploaded. After the .WAV has been uploaded, it can not be replaced or deleted. All .WAV files must use a 44.1 kHz, 16-bit stereo format, and compression is not current supported.

EXAMPLE REQUEST:
POST <base_address>/SampleUpload

<SampleUpload>
  <Name>Bob's wicked drum beat</Name>
  <Description>A wicked drum beat that I recorded in my basement.</Description>
  <Tags>
    <Tag>snare drum</Tag>
    <Tag>4/4 time</Tag>
  </Tags>
</SampleUpload>


EXAMPLE RESPONSE:
{code.xml}
<SampleUpload>
<Media href="<base_address>/SamplesUpload/5"/>
</SampleUpload>
{code.xml}

EXAMPLE REQUEST (with the .WAV file as the entity body):
PUT <base_address>/SamplesUpload/5


EXAMPLE RESPONSE:
<Sample href="<base_address>/Samples/5">
  <Id>5</Id>
  <Name>Bob's wicked drum beat</Name>
  <Description>A wicked drum beat that I recorded in my basement.</Description>
  <Tags>
    <Tag>snare drum</Tag>
    <Tag>4/4 time</Tag>
  </Tags>
  <Duration>0:01:12.32</Duration>
  <UploadedOn>Sun, 06 Nov 2009 08:49:37 GMT</UploadedOn>
  <Author href="<base_address>/Users/bobg">bobg</Author>
  <Media href="<base_address>/Samples/5/Media.wav"/>
</Sample>

Samples: PUT <base_address>/Samples/<id>

Allows a user to update a sample's name, description or set of tags. Only the author of the sample is authorized to update the sample metadata. The response body will be equivalent to a GET <base_address>/Samples/<id>. Any elements not provided in the request are considered un-changed. The "Tags" element takes an optional "append" attribute, which can have a value of either "true" or "false". If "false", the child "Tag" elements replace the current set of tags for the sample; otherwise the tags in the request are appended to the current set tags for the sample. The default value is "true".

EXAMPLE REQUEST:
PUT <base_address>/Samples/5

<Sample>
  <Tags append="true">
    <Tag>basement session<Tag>
  </Tags>
</Sample>

Projects: GET <base_address>/Projects?skip=<skip>&top=<top>&owner='<owner>'&contributor=<contributor>&tags='<tags>'

Returns a list of projects with the project info provided. The project info includes the id, name, description, tags, owner and contributors of the project, as well as a link to the actual project. There is no mechanism to get a list of the actual projects.

Parameter Default Valid Range Description
skip 0 >=0 The number of projects to skip before including projects in the returned list.
top 25 >0 The maximum number of projects to include in the returned list.
owner NA any valid login in single quotes Filters the list of projects to only includes projects with the given owner.
contributor NA any valid login in single quotes Filters the list of projects to only includes projects with the given contributor.
tags NA a comma-separated list of tags in single quotes Filters the list of projects to include only projects that contain one or more of the given tags


EXAMPLE REQUEST:
GET <base_address>/Projects?top=5&owner='bobg'

EXAMPLE RESPONSE:
<Projects href="<base_address>/Projects?skip=0&top=5&owner='bobg'" skip="0" top="5" owner="bobg" 
    contributor="" tags="">
  <Project href="<base_address>/Projects/232">
    <ProjectInfo href="<base_address>/Projects/232/Info">
      <Id>232</Id>
      <Name>Midnight Trucker Jam</Name>
      <Description>A rocking jam about hauling freight all night long!</Description>
      <Tags>
        <Tag>trucking</Tag>
        <Tag>long nights</Tag>
      </Tags>
      <Owner href="<base_address>/Users/bobg">bobg</Owner>
      <Contributors>
        <Contributor href="<base_address>/Users/maryt">maryt</Contributor>
        <Contributor href="<base_address>/Users/paulz">paulz</Contributor>
      </Contributors>  
      </ProjectInfo>
  </Project>
  <!-- Additional Projects -->
</Projects>

Projects: GET <base_address>/Projects/<id>

Returns the current project data for the project with the given 'id'.

EXAMPLE REQUEST:
GET <base_address>/Projects/232

EXAMPLE RESPONSE:
<Project href="<base_address>/Projects/232">
  <AppliedSamples>
    <AppliedSample>
      <Sample href="<base_address>/Samples/5">
        <Id>5</Id>
        <Name>Bob's wicked drum beat</Name>
      </Sample>
      <Offset>0</Offset>
      <Effects>
        <Effect href="<base_address>/Effects/12">
          <Id>12</Id>
          <Name>Gain</Name>
          <Parameter Name="Amount">-1.25</Parameter>
        <Effect>
      <Effects>
    <AppliedSample>
    <!-- Additional Applied Samples -->
  </AppliedSamples>
</Project>

Projects: GET <base_address>/Projects/<id>/Info

Returns the project info for the project with the given 'id'.

EXAMPLE REQUEST:
GET <base_address>/Projects/232/Info

EXAMPLE RESPONSE:
<Project href="<base_address>/Projects/232">
  <ProjectInfo href="<base_address>/Projects/232/Info">
    <Id>232</Id>
    <Name>Midnight Trucker Jam</Name>
    <Description>A rocking jam about hauling freight all night long!</Description>
    <Tags>
      <Tag>trucking</Tag>
      <Tag>long nights</Tag>
    </Tags>
    <Owner href="<base_address>/Users/bobg">bobg</Owner>
    <Contributors>
      <Contributor href="<base_address>/Users/maryt">maryt</Contributor>
      <Contributor href="<base_address>/Users/paulz">paulz</Contributor>
    </Contributors>  
    </ProjectInfo>
</Project>

Last edited Nov 9, 2009 at 6:03 AM by randallt, version 11

Comments

No comments yet.