TUNEL.us API overview

TUNEL.us API overview.md

TUNEL.us API overview

We are ready to answer your questions via contact@tunel.us

Public data

This is the only request that does not require authorization. It is recommended to make it every 5 minutes or after other api requests.

GET http://tunel.us/graph?data={"type":"all1"}

Response:

{
	"version" : 2,
	"bands" : {
		...
		"<band_id>" : {
			"addr" : "<band_addr>",
			"fields" : {
				"about" : "<band_about>",
				"avatar" : "<band_avatar_url>",
				"genre" : "<band_genre>",
				"members" : "<band_members>",
				"title" : "<band_title>",
				"links" : "<band_links_json>"
			},
			"checkins" : [
				[<checkin_station_id>, <checkin_duration>, <checkin_timestamp>],
				...
			],
			"posts" : [
				["<post_text>", <post_timestamp>],
				...
			],
		}
	}
}

• "<band_id>" is an internal band identifier string (currently it looks like a number, but you should not rely on this).
• addr is a public band identifier (case insensitive). For example, for tunel.us/#TUNEL_BAND band, addr will be "TUNEL_BAND".
• avatar contains image address, uploaded via tunel.us/upload.
• If title contains [HIDDEN] or [BANNED] as substring (case sensitive), than band will not be shown in search or station page, but it still can be accessed by direct link.
• links is a JSON (quoted JSON inside JSON) dictionary, where keys correspond to links titles and values contain urls, for example:

{
	"official site" : "http://tunel-band.com",
	"youtube" : "http://youtube.com/tunel_band",
	"soundcloud" : "http://soundcloud.com/tunel_band",
	"extra link" : "http://tunel-band.livejournal.com",
}

• checkin_duration is a number of minutes.
• timestamps are in unix format (integers). Checkin timestamp is a time, when checkin starts.

Authorization

Suppose that user have login bob@example.com and password secretpas, than login and hashpas cookies should be set to

login = eh1/bob@example.com`
hashpas = sha224("secretpas:tunel.us:eh1/bob@example.com") = 3313315a5a4a3962db3d21928fee2d34e0d19dc0eaf7bf3cb7d6935c

eh1/ here is a login prefix, wich designates auth type. By now, only eh1 prefix is allowed.

Referer of HTTP request must be set to http://tunel.us/.

Profile

Requests have a form

GET http://tunel.us/api?data=<JSON>

Response is JSON with a field "response", which contains "ok" or error description.

Registration

Cookies should be set using new login and password.

GET http://tunel.us/api?data={
	"action" : "register1",
	"band_name" : "<band_name>"
}

Checking auth

GET http://tunel.us/api?data={
	"action" : "check_auth1"
}

Response can be either

{
	"response" : "ok",
	"role" : "no_auth"
}

{
	"response" : "ok",
	"role" : "moderator"
}

{
	"response" : "ok",
	"role" : "musician",
	"band_key" : "<band_key>"
}

or

{
	"response" : "<error_description>"
}

Check-in

GET http://tunel.us/api?data={
	"action" : "checkin1",
	"band_key" : "<band_key>",
	"station_id" : <station_id>,
	"duration" : <duration>
}

Add post

GET http://tunel.us/api?data={
	"action" : "add_post1",
	"band_key" : "<band_key>",
	"text" : "<post_text>"
}

Edit fields

GET http://tunel.us/api?data={
	"action" : "edit_band_field1",
	"band_key" : "<band_key>",
	"field" : "<field_name>",
	"value" : "<field_value>"
}

Possible values for <field_name> are about, avatar, genre, members, title, links.

Changing address

GET http://tunel.us/api?data={
	"action" : "set_addr1",
	"band_key" : "<band_key>",
	"addr" : "<new_addr>"
}

If <new_addr> is reserved by other band or incorrect (contains only digits) server will alter it in a way it becomes valid and unique. For example, if TUNEL_BAND is already reserved and somebody else tries to change his address to TUNEL_BAND, his band will have TUNEL_BAND1 adress as a result of an api request. Although operation was partially successfull, the response will contain explanation, why digit was appended to the end of address.

{
	"response" : "The address you entered was reserved.<br>"
}

Avatars

Getting thumbnails

Each band object contains avatar field, which contains url of original image. To get thumbnail square image, simply append =sNNN-c to the end, where NNN is a thumnail size. For example http://lh3.googleusercontent.com/l4Y6dCcqA3R9BYAiotCHLhI0148kDIUxzHNUNTjg0XY6zC_R6qWwm0yJ8aO9ZCAC-pdfWPqb1nzdAN2fRx0v=s240-c

Getting upload link

Before upload you should get upload link

GET http://tunel.us/get_upload_link

Response:

{
	"response" : "ok",
	"link" : "<upload_url>"
}

Uploading file

Make multipart/form-data POST request to the <upload_url> where type field is "avatar" and image is in file field.

Response will contain uploaded file url:

{
	"response" : "ok",
	"url" : "<uploaded_url>"
}

Changing avatar

But uploading avatar image does not automatically changes it. You should make edit_band_field1 request:

GET http://tunel.us/api/api?data={
	"action" : "edit_band_field1",
	"band_key" : "<band_key>",
	"field" : "avatar",
	"value" : "<uploaded_url>"
}

<uploaded_url> should be the result of uploading image by previous steps, you cannot host avatars on arbitrary servers.