API Documentation

Purpose

I made an api to get music from my server. This API is public so feel free to try at api.musiques.nils.test.sc2mnrf0802.universe.wf (I also created a shorter url: bit.ly/API_nils_test).
If you want to get a quick reminder of the names of the headers, you can always request the endpoint with the OPTIONS verb.

URI list

• music-infos .php: Gives the ressource's headers (title, n° of track, etc...) in JSON or XML.

• mp3 .php: Gives the audio (in mp3) of the requested ressource, requesting an other type (like .wav) will send an error.

• html .php: Equivalent to music-infos but with a differnent style and in a HTML format.

• list .php: Gives the list of all available musics

• index .php: Redirects to music-infos.

How to make a good request

Quick explaination

In order to make a request, you have to send a HTTP request to one of the endpoints with the parameter "file" set to the name of the music you want, the extention (.mp3) is optional. Ex: curl api.musiques.nils.test.sc2mnrf0802.universe.wf/music-infos?file=An%20Oasis%20In%20Time

Typical (GET) request

Here is the request shown in the last part:

GET /music-infos?file=An%20Oasis%20In%20Time HTTP/1.0
X-Country-Code: FR
Host: api.musiques.nils.test.sc2mnrf0802.universe.wf
X-Forwarded-Proto: http
User-Agent: curl/8.4.0
Accept: */*
Content-Length: 0

This request will send back the body:

{
    "title":  "An oasis in time",
    "composers": [
        "Michiru Yamane"
    ],
    "track": 39,
    "commentaire": "",
    "path": "An Oasis In Time.mp3"
}

If the header Accept is set to application/xml the body will be:

<music>
    <title>An oasis in time</title>
    <composers>
        <composer>Michiru Yamane</composer>
    </composers>
    <track>39</track>
    <album>Skullgirls</album>
    <commentaire></commentaire>
    <path>An Oasis In Time.mp3</path>
</music>

A succeful request will send a response with those 5 fields

• String title : The full title of the music, often the file's name.
• String[] composers: The composers of the music.
• Unsigned Int track: The number of the track.
• String commentaire: A comment I wrote, often empty.
• String path: The path of the file on the server starting in the api folder (just the basename of the music).

POST Request

As I wrote, for now a POST request (with or without authorization) is equivalent to a GET request.
You must send a body formatted in JSON or as a HTML form (multipart/form-data).

Request with browser

With the new style compatibility, you can now request in browser. Make sure to have the redirect param disabled in order to not get redirected to the html page.

Particular URIs:

• html: You can set a boolean parameter title to true to get some metadatas. You can get a response:

<div class='music-head'>
    <p><span class='music-title'>An oasis in time</span> (<span class='music-artists'>Michiru Yamane</span> | <span class='music-track'> 39 </span> | music in album <span class='music-album'>Skullgirls</span>)
</div>
<audio src="http://musiques.nils.test.sc2mnrf0802.universe.wf/api/An Oasis In Time.mp3" type="audio/mp3" controls="" autoplay=""></audio>

The div element has the class music-head, the title music-title, the artists music-artists, ...

• music-infos: You can include the indent= n parameter to get the request with n indent (the \t char), the returned indent is in the header Body-Indent.

• list: This endpoint will send back a list of responses from music-infos, here is a short example:

[
    {
        "title":  "Resurrections",
        "composers": [
            "Lena Raine"
        ],
        "track": 3,
        "album": "Celeste",
        "commentaire": "",
        "path": "03 - Resurrections.mp3"
    },
    {
        "title":  "Awake",
        "composers": [
            "Lena Raine"
        ],
        "track": 4,
        "album": "Celeste",
        "commentaire": "",
        "path": "04-Awake.mp3"
    }
]

or

<musics>
    <music>
        <title>Resurrections</title>
        <composers>
            <composer>Lena Raine</composer>
        </composers>
        <track>3</track>
        <album>Celeste</album>
        <commentaire></commentaire>
        <path>03 - Resurrections.mp3</path>
    </music>
    <music>
        <title>Awake</title>
        <composers>
            <composer>Lena Raine</composer>
        </composers>
        <track>4</track>
        <album>Celeste</album>
        <commentaire></commentaire>
        <path>04-Awake.mp3</path>
    </music>
</music>

Particular parameters in URL

• bool redirect: Define if redirections should be done works for music-infos, mp3 and html endpoints.
• bool styled: Equivalent to the Req-Body-Style header, controls whether or not the response should have a predefined stylesheet attached. Works for music-infos and list.

Write a boolean parameter

There's 4 accepted values:

• true <=> 1
• false <=> 0

Headers

In a request

• Accept: The MIME types expected separated by a comma(,), you can include the weight argument (q). ex: Accept: application/json, */*; q=0.7. By convention, the weight should be between 0 and 1, however any positive value is correct.

  Accepted types:

  • application/json (default),
  • application/xml,
  • audio/mp3,
  • text/html
• Accept-Charset: The accepted charset. Can only provide utf-8.
• Accept-Language: The accepted language. Can only provide english.
• Accept-Error: The type to send back if an error occurs, will override the Accept header, takes only:
  • application/json (default),
  • application/xml

Particular headers

• bool Req-Body-Style: If the response should link a predefined stylesheet, specific to the music-infos and list endpoints with an XML response.
• unsigned int Req-Body-Indent: The number of horizontal indent to apply on all the body (override the param indent) (specific to music-infos and list).

In the response

• string Content-Type: The format of the response
• bool Body-Style: If the body has a stylesheet (Only availble in music-infos and music-infos)
• unsigned int Body-Indent: The indentation of the body (only in list and music-infos).

Handled methods

For now, any other method that GET, POST, HEAD or OPTIONS will send back an error message.
A GET request is equivalent to a POST request, the server will send the headers of the music. A HEAD request will send back only the headers.

Handling errors

The server will always send the error message in JSON.
The JSON will always have 5 fields:

• code: The HTTP error code or 0, if 0 the error is not intended.
• name: The name of the HTTP error or if code == 0 the name of the class of the error.
• message: A message explaining the error
• line: The number of the line from where the error was thrown
• stack_trace: the stack trace (only availble for testers and admin)
• other_info: further informations on the reason of the failure.

ex:

{
    "code": 404,
    "name": "Not found",
    "message": "The specified element does not exist."
    "other_info": "Path: http://musiques.nils.test.sc2mnrf0802.universe.wf/api/example.mp3"  
}