Started working on API documentation.
This commit is contained in:
Jonathan Bernard
parent
da3cf13267
commit
49178b44a3
121
src/main/webapp/doc/api/v1/index.html
Normal file
121
src/main/webapp/doc/api/v1/index.html
Normal 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='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>
|
||||||
|
<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>
|
||||||
Loading…
x
Reference in New Issue
Block a user