jdb/new-life-songs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Started working on API documentation.

Browse Source
This commit is contained in:
Jonathan Bernard 2015-03-23 04:10:55 -05:00
parent da3cf13267
commit 49178b44a3
1 changed files with 121 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

121
src/main/webapp/doc/api/v1/index.html Normal file
View File

@ -0,0 +1,121 @@
<!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 and modification to 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='&#109;&#97;&#105;&#108;&#116;&#111;&#58;&#106;&#100;&#98;&#101;&#114;&#110;&#97;&#114;&#100;&#64;&#103;&#109;&#97;&#105;&#108;&#46;&#99;&#111;&#109;'>&#106;&#100;&#98;&#101;&#114;&#110;&#97;&#114;&#100;&#64;&#103;&#109;&#97;&#105;&#108;&#46;&#99;&#111;&#109;</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>
<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>
<h4>Example</h4>
<pre>
GET http://newlifesongs.jdbernard.com/api/v1/songs</pre>
<p><pre>
HTTP/1.1 200 OK
Content-Length: 5146
Content-Type: application/json
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Server: Jetty(6.1.25)
[{"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.
<p><h4>Example</h4>
</section>
<section id=services>
<h2><code>/services</code></h2>
</section>
<section id=users>
<h2><code>/users</code></h2>
</section>
<section id=authentication>
<h2>Authentication</h2>
</section>
</body>
</html>