Messic API: Usage
Messic API allows to external applications to connect with messic database, pushing and retrieving all kind of information stored at messic. All the API is documented and autogenerated by messic. You can consult it at the web page of messic and also at the messic service (in the about page).
The purpose of this wiki is to give a basic overview of the API, and explain the basic usage following a set of examples. For the moment, there is no a detailed documentation of the API, with a lot of examples, but we hope that it is the minimal enough to start using the messic API. In any case, any question regarding the API can be launched at the google group forum, and we or the community will try to answer you as soon as possible.
The purpose to use the api provided by messic could be very diverse. For example, an user could build an external client to play the messic music, or just to connect the messic database with another system, or whatever idea you have in your mind.
Before starting to explain the API, it's necessary to give a simple description of how are the communications between any possible client and the messic service.
Messic is constructed in JAVA language. It is divided basically in six layers:
- The Data model, which are those packages responsibles with the communication with the database.
- The Core, in charge of the bussiness logics of messic.
- The web facade, exposing the REST API to connect with the core, and also the web pages for the web client constructed for messic.
- The Web container (jetty) which is the responsible to publish the messic web facade over a web server.
- The OSGI framework (felix) where are deployed all the messic bundles (included some messic plugins), and jetty bundles. Therefore, the OSGI framework contains all the previous described bundles. This could be considered as the messic service.
- The messic monitor application, is an independent application. It is responsible to monitor the status of the messic service, launching it or stopping it when necessary.
This is a necessary generic overview to understand what's the process to comunicate with the messic service. Once explained this, is an easy question to understand that the messic core is exposed to any third client as a REST api through the web container. So, you only need to do a REST client in order to communicate with the messic service (for sure, the messic service must be launched and listening).
So, messic service is always listening to give you all the information you need. But whats the URL you need to attack in order to retrieve any information? Of course, it depends. The messic monitor can says to you this easily. It is the same URL when you launch the default messic web client. ... something like for example:
http://192.168.0.100:8080/messic
This example could be the base url to attack messic. It means that we are connecting with the ip (192.168.0.100), through the port 8080 (and without security, http).
Messic is listening at the machine where you have launched it, and at the port you have configured (if you have configured none, messic try to get any free port). Please, pay attention to the security (https or http), because it could be different at each case. The security can be activated at each time.
If you can access to the messic installation folder, there is a way to know what's the current port, and if the security is activated or not. You only need to read the file "currentport". This file is created each time messic is launched, and give you the possibility to know what is the current port and if it have been launched through http or https.
This is an example of this file:
currentPort=8085
secured=falseOk. Your are now ready to start connecting with the messic service, but you can't get anything without login first at the service. This means, that any external rest client should login first, and then start retrieving information.
This is a problem for the DLNA services, due to the fact that they cannot implement any security extension. Currently, to allow this, the security is desactivated for DLNA devices. So, be awareness of this.
This is what the API explain about the login services, at the current version (1.0.0-alpha):
What you can read here is that the service to retrieve a messic token is the "/messiclogin". The method to retrieve this information is a POST, sending the username and password by the variables j_username and j_password. This service will return a messic token when validating the username and password, and this token should be used in every other call you want to do to obtain other information. We will see this later. Let's try to do an small example with the login service.
Let's suppose that our base url is the following:
http://192.168.0.100:8080/messic
So, to construct the url to get the token should be:
http://192.168.0.100:8080/messic/messiclogin
messiclogin service is the only one which doesn't have the "services" context. It's directly behind messic: /messic/messiclogin
We need to do a POST to this URL, sending a valid username and password. The incoming information will be at JSON format. For the example purposes, I will show you a linux curl command to make a post:
curl --data "j_username=messicUser&j_password=messicPassword" http://192.168.0.100:8080/messic/messiclogin
The response is the following:
{
"success":true,
"targetUrl" : "null",
"userId" : "messicUser" ,
"messic_token":"a12f515c-815c-42af-949c-e5f549825297"
}Congratulations! You have just logged at Messic. You know must stored this messic_token, because it is your key to acces to other resources at messic.
Once you have logged at the messic service you can acces to the rest of resources adding this token as part of the URL or as an http header.
This is an example captured using firebug. You can see there the messic_token variable as a header value.
Accept application/json, text/javascript, */*; q=0.01
Accept-Encoding gzip, deflate
Accept-Language en
Connection keep-alive
Cookie JSESSIONID=1lh1iio36ium311xrvlbjlp540; messic_login_cookie=
Host 192.168.0.100
Referer http://192.168.0.100/messic/login.do
User-Agent Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:31.0) Gecko/20100101 Firefox/31.0
X-Requested-With XMLHttpRequest
messic_token 9b9d652f-3bcc-4ff7-9867-9a9512ba435aBut you can also include the messic_token as other parameter. The following is an url to obtain an album cover:
http://192.168.0.100:8080/messic/services/albums/374/cover?preferredWidth=100&preferredHeight=100&messic_token=9b9d652f-3bcc-4ff7-9867-9a9512ba435a
One illustrative example of the use of messic API could be the Author services. As you can see in the following capture (remember that you can obtain all the API info from the web page or the messic service web app (about page).
Pay attention at the messic version. Depending on it, the API could change.
Above is a capture of one author service. This service return the list of all authors at the messic database. To retrieve this information the only thing you need to do is to the following url:
http://192.168.0.100:8080/messic/services/authors
but, remember! you need the messic token! So, you can send a GET with this information at the header of the petition, or adding the token information at the url, like this:
http://192.168.0.100:8080/messic/services/authors?messic_token=9b9d652f-3bcc-4ff7-9867-9a9512ba435a
Here an example of the returned information, as JSON format.
[
{"sid":413,"code":null,"name":"Acid Trax","year":2010,"author":{"sid":412,"name":"TeKnoizer","albums":null},"cover":null,"songs":[],"artworks":[],"others":[],"genre":{"sid":306,"name":"Techno"},"comments":"Attribution-Noncommercial-Sh"},{"sid":259,"code":null,"name":"Ajan Vartija","year":2013,"author":{"sid":258,"name":"Django de la Poppavati","albums":null},"cover":null,"songs":[],"artworks":[],"others":[],"genre":{"sid":300,"name":"alternative"},"comments":""},{"sid":362,"code":null,"name":"Born in the Country","year":2014,"author":{"sid":361,"name":"FJGI","albums":null},"cover":null,"songs":[],"artworks":[],"others":[],"genre":{"sid":303,"name":"Flamenco - Jazz"},"comments":"Attribution-Noncommercial-No"},{"sid":374,"code":null,"name":"BUENA MIERDA","year":2014,"author":{"sid":373,"name":"MARISKADA SOUND","albums":null},"cover":null,"songs":[],"artworks":[],"others":[],"genre":{"sid":304,"name":"Reggae"},"comments":"Attribution-Noncommercial-Shar"},{"sid":296,"code":null,"name":"Epic Soul Factory - Volume One","year":2013,"author":{"sid":295,"name":"Epic Soul Factory","albums":null},"cover":null,"songs":[],"artworks":[],"others":[],"genre":{"sid":302,"name":"Epic"},"comments":"Attribution-Noncommercial-Shar"},{"sid":251,"code":null,"name":"Erratics","year":2014,"author":{"sid":250,"name":"Aniqatia","albums":null},"cover":null,"songs":[],"artworks":[],"others":[],"genre":{"sid":104,"name":"Rock"},"comments":"Attribution-Noncommercial-Sh"},{"sid":276,"code":null,"name":"Katzennetz...und das viele essen","year":2008,"author":{"sid":275,"name":"Brynet","albums":null},"cover":null,"songs":[],"artworks":[],"others":[],"genre":{"sid":105,"name":"Electronic"},"comments":"Attribution-Noncommercial-Shar"},{"sid":384,"code":null,"name":"lu","year":2010,"author":{"sid":383,"name":"Kubelik","albums":null},"cover":null,"songs":[],"artworks":[],"others":[],"genre":{"sid":305,"name":"Instrumental"},"comments":""},{"sid":290,"code":null,"name":"Tambores de Guerra (Single)","year":2014,"author":{"sid":289,"name":"Escarnio","albums":null},"cover":null,"songs":[],"artworks":[],"others":[],"genre":{"sid":301,"name":"Death Metal"},"comments":"Attribution-Noncommercial-Sh"}]But there are a set of parameters that you can use also (there are explained at the api doc). For example, the filterName param:
http://192.168.0.100:8080/messic/services/authors?filtername=Kubelik&messic_token=9b9d652f-3bcc-4ff7-9867-9a9512ba435a
You must read all the posibilities that the API gives to you in order to retrieve the information you need at each moment.