7d7f2eed87
Moved all the existing service code into the `service` submodule. Stubbed out project and GUI frame for the uploader. Idea is to have a GUI that infers all the correct meta-data from media tag values and creates service, songs, and performance records appropriately based on the tagged mp3/ogg files of the performances.
352 lines
14 KiB
HTML
352 lines
14 KiB
HTML
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<meta name="referrer" content="origin">
|
|
<link rel="shortcut icon" href="../images/favicon.ico">
|
|
|
|
<title>API V1 - New Life Songs Database</title>
|
|
<link
|
|
href='http://fonts.googleapis.com/css?family=Roboto+Condensed|Cantarell|Anonymous+Pro' rel='stylesheet' type='text/css'>
|
|
<link href='../../../css/new-life-songs-@version@.css' rel='stylesheet' type='text/css'>
|
|
</head>
|
|
<body class=api-doc>
|
|
<header>
|
|
<h1><a href="../../../">New Life Songs API V1</a></h1>
|
|
<nav><ul>
|
|
<li><a href="../../../admin/">Admin</a></li>
|
|
<li><a href="../../../songs/">Songs</a></li>
|
|
<li><a href="../../../services/">Services</a></li>
|
|
</ul></nav>
|
|
</header>
|
|
<section id=api-overview>
|
|
The New Life Songs database exposes a REST API. This allows
|
|
programatic access to and modification of the data. Version 1 of
|
|
the API defines several endpoints, all of which are built off of
|
|
<code>http://newlifesongs.jdbernard.com/api/v1</code> as a base
|
|
URL.
|
|
|
|
<p>Some of the service's endpoints require the client to authenticate
|
|
itself to the server. See the <a href="#authentication">section on
|
|
authentication</a> for details concerning authentication.
|
|
|
|
<p>The endpoints that the API defines are:
|
|
<ul><li><a href="#songs"><code>/songs</code></a></li>
|
|
<li><a href="#services"><code>/services</code></a></li>
|
|
<li><a href="#users"><code>/users</code></a></li></ul>
|
|
|
|
<p>If you run across any problems or have questions, feel free to send me an email at
|
|
<a href='mailto:jdbernard@gmail.com'>jdbernard@gmail.com</a>
|
|
</section>
|
|
<section id=songs>
|
|
<h2><code>/songs</code></h2>
|
|
<h3 id=song-object>Song object</h3>
|
|
A song object is defined with the following fields:
|
|
<dl><dt>id</dt>
|
|
<dd>An identifier unique to this song record among all song
|
|
records. <em>Type: integer</em></dd>
|
|
|
|
<dt>name</dt>
|
|
<dd>The name of the song. <em>Type: string</em></dd>
|
|
|
|
<dt>artists</dt>
|
|
<dd>A list of the artists known to have written or performed
|
|
this song. <em>Type: list of strings</em></dl>
|
|
|
|
<h4>Example</h4>
|
|
<pre>
|
|
{
|
|
"id":8,
|
|
"name":"Here I Am To Worship",
|
|
"artists":[
|
|
"Tim Hughes",
|
|
"Chris Tomlin",
|
|
"Michael W. Smith"
|
|
]
|
|
}</pre>
|
|
<h3>Method Summary</h3>
|
|
<table class=method-summary>
|
|
<thead>
|
|
<tr><th class=action>HTTP Action</th>
|
|
<th class=path>Path</th>
|
|
<th class=desc>Description</th>
|
|
<th class=public>Public?</th></tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr><td class=action>GET</td>
|
|
<td class=path><code>/songs</code></td>
|
|
<td class=desc>Retrieve all songs.</td>
|
|
<td class=public>yes</td></tr>
|
|
<tr><td class=acion>POST</td>
|
|
<td class=path><code>/songs</code></td>
|
|
<td class=desc>Create a new song record.</td>
|
|
<td class=public>no</td></tr>
|
|
<tr><td class=acion>GET</td>
|
|
<td class=path><code>/songs/<songId></code></td>
|
|
<td class=desc>Retrieve a single record.</td>
|
|
<td class=public>yes</td></tr>
|
|
<tr><td class=acion>PUT</td>
|
|
<td class=path><code>/songs/<songId></code></td>
|
|
<td class=desc>Update a song record.</td>
|
|
<td class=public>no</td></tr>
|
|
<tr><td class=acion>DELETE</td>
|
|
<td class=path><code>/songs/<songId></code></td>
|
|
<td class=desc>Delete a song record.</td>
|
|
<td class=public>no</td></tr>
|
|
<tr><td class=acion>GET</td>
|
|
<td class=path><code>/songs/forService/<serviceId></code></td>
|
|
<td class=desc>Retrieve all songs performed in a given service.</td>
|
|
<td class=public>yes</td></tr>
|
|
<tr><td class=acion>GET</td>
|
|
<td class=path><code>/songs/byArtist/<artist></code></td>
|
|
<td class=desc>Retrieve all songs performed by a given artist.</td>
|
|
<td class=public>yes</td></tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<ul class=method-list>
|
|
<li><h3><code>GET /songs</code></h3>
|
|
|
|
<p>Retrieve all songs.
|
|
<p><h4>Response</h4>
|
|
A list of <a href="song-object">song objects</a>
|
|
|
|
<p><h4>Example</h4>
|
|
<pre>
|
|
GET http://newlifesongs.jdbernard.com/api/v1/songs</pre>
|
|
<p><pre>
|
|
HTTP/1.1 200 OK
|
|
Content-Length: 433
|
|
Content-Type: application/json
|
|
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
|
|
|
|
[{"id":1,"name":"Welcome Holy Spirit","artists":["Mark Condon"]},
|
|
{"id":3,"name":"Let's Sing Praises to our God","artists":["Traditional"]},
|
|
{"id":5,"name":"Blessed Assurance","artists":["Frances J. Crosby"]},
|
|
{"id":8,"name":"Here I Am To Worship","artists":["Tim Hughes", "Chris Tomlin", "Michael W. Smith"]},
|
|
{"id":12,"name":"Healer","artists":["Kari Jobe", "Hillsong"]},
|
|
{"id":15,"name":"I Am Free","artists":["Newsboys"]}]
|
|
</pre></li>
|
|
|
|
<li><h3><code>POST /songs</code></h3>
|
|
|
|
<p>Create a new song record. In order to be allowed access to
|
|
this method, the request must be made with a valid
|
|
authentication token which belongs to a user with
|
|
administrative priviliges. See <a href="#authentication">Authentication</a>
|
|
for details.
|
|
|
|
<p><h4>Request Body</h4>
|
|
Must be a <a href="#song-object">song object</a>. The
|
|
<code>name</code> field is required. Any <code>id</code> passed
|
|
in with the request will be ignored.
|
|
|
|
<p><h4>Reponse</h4>
|
|
The newly-created song record. If a value is given in the
|
|
request for the <tt>id</tt> attribute it is ignored. The
|
|
attribute for new records is determined by the service and
|
|
returned as part of the response.
|
|
|
|
<p><h4>Example</h4>
|
|
<pre>
|
|
POST http://newlifesongs.jdbernard.com/api/v1/songs
|
|
Content-Length: 60
|
|
Content-Type: application/json
|
|
|
|
{"id":22,"name":"This is How We Praise Him","artists":[""]}
|
|
</pre>
|
|
<p><pre>
|
|
HTTP/1.1 201 Created
|
|
Content-Length:
|
|
Content-Type: application/json
|
|
|
|
|
|
</pre></li>
|
|
|
|
<li><h3><code>GET /songs/<songId></code></h3>
|
|
|
|
<p>Retrieve song data for the given song id.
|
|
|
|
<p><h4>Response</h4>
|
|
A <a href="song-object">song object</a>.
|
|
|
|
<p><h4>Example</h4>
|
|
<pre>
|
|
GET http://newlifesongs.jdbernard.com/api/v1/songs/1</pre>
|
|
<p><pre>
|
|
HTTP/1.1 200 OK
|
|
Content-Length: 63
|
|
Content-Type: application/json
|
|
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
|
|
|
|
{"id":1,"name":"Welcome Holy Spirit","artists":["Mark Condon"]}
|
|
</pre></li>
|
|
</li>
|
|
|
|
<li><h3><code>PUT /songs/<songId></code></h3>
|
|
|
|
<p>Method description
|
|
<p><h4>Request Body</h4>
|
|
Request body description
|
|
|
|
<p><h4>Response</h4>
|
|
Return value description
|
|
|
|
<p><h4>Example</h4>
|
|
<pre>
|
|
</pre></li>
|
|
|
|
</li>
|
|
|
|
<li><h3><code>DELETE /songs/<songId></code></h3>
|
|
|
|
<p>Method description
|
|
<p><h4>Request Body</h4>
|
|
Request body description
|
|
|
|
<p><h4>Response</h4>
|
|
Return value description
|
|
|
|
<p><h4>Example</h4>
|
|
<pre>
|
|
</pre></li>
|
|
|
|
</li>
|
|
|
|
<li><h3><code>GET /songs/forService/<serviceId></code></h3>
|
|
|
|
<p>Method description
|
|
<p><h4>Request Body</h4>
|
|
Request body description
|
|
|
|
<p><h4>Response</h4>
|
|
Return value description
|
|
|
|
<p><h4>Example</h4>
|
|
<pre>
|
|
GET /api/v1/songs/forService/1 HTTP/1.1</pre>
|
|
<p><pre>
|
|
HTTP/1.1 200 OK
|
|
Content-Length: 256
|
|
Content-Type: application/json
|
|
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
|
|
|
|
[{"id":7,"name":"Mighty God","artists":[""]},
|
|
{"id":8,"name":"Here I Am To Worship","artists":["Tim Hughes: Chris Tomlin, Michael W. Smith"]},
|
|
{"id":9,"name":"Worthy","artists":[""]},
|
|
{"id":4,"name":"I Am A Friend Of God","artists":["Israel Houghton"]}]j
|
|
</pre></li>
|
|
|
|
</li>
|
|
|
|
<li><h3><code>GET /songs/byArtist/<artist></code></h3>
|
|
|
|
<p>Method description
|
|
<p><h4>Request Body</h4>
|
|
Request body description
|
|
|
|
<p><h4>Response</h4>
|
|
Return value description
|
|
|
|
<p><h4>Example</h4>
|
|
<pre>
|
|
</pre></li>
|
|
|
|
</li>
|
|
|
|
</section>
|
|
<section id=services>
|
|
<h2><code>/services</code></h2>
|
|
|
|
<h3 id=service-object>Service object</h3>
|
|
A Service object is defined with the following fields:
|
|
<dl><dt>id</dt>
|
|
<dd>An identifier unique to this service record among all
|
|
service records. <em>Type: integer</em></dd>
|
|
|
|
<dt>date</dt>
|
|
<dd>The date of the service. <em>Type: Date</em></dd>
|
|
|
|
<dt>serviceType</dt>
|
|
<dd>Service type. <em>Type: string</em> Valid values:
|
|
<table><thead><tr><th>Value</th><th>Description</th></tr></thead>
|
|
<tbody>
|
|
<tr><td><code>SUN_AM</code></td>
|
|
<td>Sunday morning service.</td></tr>
|
|
<tr><td><code>SUN_PM</code></td>
|
|
<td>Sunday evening service</td></tr>
|
|
<tr><td><code>WED</code></td>
|
|
<td>Wednesday, midweek Bible study.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
|
|
<h4>Example</h4>
|
|
<pre>
|
|
{
|
|
"id": 1,
|
|
"date": 1235887200000,
|
|
"serviceType": "SUN_PM"
|
|
}</pre>
|
|
|
|
<h3>Method Summary</h3>
|
|
<table class=method-summary>
|
|
<thead>
|
|
<tr><th class=action>HTTP Action</th>
|
|
<th class=path>Path</th>
|
|
<th class=desc>Description</th>
|
|
<th class=public>Public?</th></tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr><td class=action>GET</td>
|
|
<td class=path><code>/services</code></td>
|
|
<td class=desc>Retrieve all services.</td>
|
|
<td class=public>yes</td></tr>
|
|
<tr><td class=acion>POST</td>
|
|
<td class=path><code>/services</code></td>
|
|
<td class=desc>Create a new service record.</td>
|
|
<td class=public>no</td></tr>
|
|
<tr><td class=acion>GET</td>
|
|
<td class=path><code>/services/<serviceId></code></td>
|
|
<td class=desc>Retrieve a single service record.</td>
|
|
<td class=public>yes</td></tr>
|
|
<tr><td class=acion>PUT</td>
|
|
<td class=path><code>/services/<serviceId></code></td>
|
|
<td class=desc>Update a service record.</td>
|
|
<td class=public>no</td></tr>
|
|
<tr><td class=acion>DELETE</td>
|
|
<td class=path><code>/services/<serviceId></code></td>
|
|
<td class=desc>Delete a service record.</td>
|
|
<td class=public>no</td></tr>
|
|
<tr><td class=acion>GET</td>
|
|
<td class=path><code>/services/withSong/<serviceId></code></td>
|
|
<td class=desc>Retrieve all services in which the given song was performed.</td>
|
|
<td class=public>yes</td></tr>
|
|
<tr><td class=acion>GET</td>
|
|
<td class=path><code>/services/byDate/after/<date></code></td>
|
|
<td class=desc>Retrieve all services after the given date.</td>
|
|
<td class=public>yes</td></tr>
|
|
<tr><td class=acion>GET</td>
|
|
<td class=path><code>/services/byDate/before/<date></code></td>
|
|
<td class=desc>Retrieve all services before the given date.</td>
|
|
<td class=public>yes</td></tr>
|
|
<tr><td class=acion>GET</td>
|
|
<td class=path><code>/services/byDate/between/<date1>/<date2></code></td>
|
|
<td class=desc>Retrieve all services between the two given dates.</td>
|
|
<td class=public>yes</td></tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
|
|
</section>
|
|
<section id=users>
|
|
<h2><code>/users</code></h2>
|
|
</section>
|
|
<section id=authentication>
|
|
<h2>Authentication</h2>
|
|
</section>
|
|
</body>
|
|
|
|
</html>
|