EOL direct API

[Domovoy]

I suddenly realised that because of IRC to EOL gateway, I have the whole EOL protocol on my hands, and while its not very cool to publish it, it might be very cool to make a web API for it. Downloading levs, recs, getting various stats, starting balles, stopping balles, spying balles - you name it, everything is possible when you interact directly with EOL. And it all comes without making any impact on elmaonline site and EOL (because we just passively collect data most of times). Win-win for everyone.

Upon Pab's request, I already made a current_battle API method, which returns information on the current battle: http://elma.seamy.ru:8880/current_battle (documentation here), and I am ready to implement many more methods. So if you can code a program to fetch a web-site and if you have a neat idea of what you could have made with access to EOL protocol, don't hesitate to post your requests in here and bring your idea to life

The main difference from Kopaka's API is that I offer direct interaction with EOL server which is probably more suitable for realtime tasks, while Kopaka's API is more suitable for EOL database polling (i.e. post-batlle tasks).

[Igge]

I have absolutely no knowledge when it comes to these things, but I think it's really cool how dedicated people are in this scene, and how together each and everyone pulls their weight into improving the elma experience for everyone. Be it coding something new for everyone to use, hosting a cup, coming up with ideas for new kinds of levels, or just being nice and social in EOL or IRC. Some do more than others, but everyone still does their part.

Except for me. I'm just slacking and enjoying the ride.

Thanks!

[ville_j]

When I made my Lousy Touch Editor I got many requests to implement a start balle functionality in it. So I think that would be nice. My only concern would be how to handle the authentication elegantly and of course one can't test the levels with mobile device (but that's irrelevant in this API discussion).

Also this topic's name might be slightly misleading because another EOL API already exists and is maintained by Kopaka.

[Domovoy]

Oh wow I didn't know, sry. Will rename the tropic.

There are two ways to properly handle authentication:
1. pass name and password over to api so it would login as this user, uplevel, startballe and logout.
2. perform uplevel and startballe from special dedicated user (as irc for irc bot).

I dislike 2 very, so I suggest the first one. If it's oke I can start makeing it.

Edit:
Renamed the tropic and added description how it is different from Kopaka's API.

[ville_j]

While the first method is easily doable I don't think it is very "elegant" (as I wrote in my post) because it involves user to hand over their login information to third parties (the application created by whoever and the API created by you). Not that I'd think it would become a big problem in our small community but anyways. If there isn't any other way, well then there isn't and it probably does not hurt anyone if we try.

[Domovoy]

Ye well, that's the problems with unofficial APIs. However, we can reduce risks slightly:
1. User enters his password in special form on API site and gets lifetime API password (token).
2. User can then pass this token to whatever application that uses the API, and application passes it to API, and API gets the original password and logs in to EOL.

This way all misuse of user data will only be limited to EOL (which is ok, cuz why would anyone want to discredit his own application?). Of course I can still get all plaintext passwords, but I'm very discreet and stuf so passwords are safe, trust me

Seriously though we can do nothing about it, cuz EOL unfortunately requires password to be passed in plaintext (yes, I was mortified too), so the bottomline is that in any scenario the API will require password in plaintext in order to work, that's why we can only hide passwords from applications, not from API.

[Domovoy]

Progress report: StartBattle API is ready. I tested it as much as I could without actual battle starting (cuz I have neither EOL login, nor fresh levels). To test it, I need one volunteer with 3-4 unseen levels, who can start battles in EOL, and who can spend like 30 mins on debugging. I plan to test tomorrow 5 PM London time.

[Domovoy]

Successfully tested, release is due tomorrow noon. Documentation:

Code: Select all

1. GET http://elma.seamy.ru:8880/store_password
	parameters:
		password - string, EOL password
	returns:
		plain text that contains API password

2. GET http://elma.seamy.ru:8880/current_battle
	returns XML document:
		CurrentBattle
			id - integer, battle id on elmaonline (http://elmaonline.net/battles/%d)
			designer - string, nickname of the level starter
			file_name - string, filename of the level
			start_delta - integer, amount of seconds to battle start if positive, amount of seconds since start if negative
			battle_type - BATTLE_TYPE
			battle_attrs - BATTLE_ATTRS
			duration - battle duration in seconds

3. POST http://elma.seamy.ru:8880/start_battle
	parameters:
		login - string, EOL nick
		password - string, API password (see store_password)
		file_name - string, filename of the level, either with or without .lev
		level_data - string, base64-encoded level data, across levels not supported
		battle_type - BATTLE_TYPE
		battle_attrs - BATTLE_ATTRS
		duration - battle duration in minutes (1-60)
		countdown - battle countdown in seconds (20, 40, 60, 90, 120)
	returns XML document:
		StartBattle
			result - string, indicates success
			or
			error - string, error message
	possible error messages:
		Parameter missing - one or more of the parameters are missing
		Wrong parameter types - one or more of the last 4 parameters are not int
		Unknown password - invalid API password
		Bad level data - base64 decoding failed
		Wrong battle parameters - incompatible battle attributes and/or type (e.g. flagtag with no see others)
		Level name is too long - level name before extension should be 8 chars or less
		Level is too big - level is bigger than 1MB
		Level file corrupted - unable to parse level data
		No permissions to start battle - unable to connect to EOL or user has no permissions to start battles or user has no permissions to start special battles

BATTLE_TYPE - one of the following:
	T_NORMAL = 0
	T_ONELIFE = 1
	T_FIRSTFINISH = 2
	T_SLOWNESS = 3
	T_SURVIVOR = 4
	T_LASTCOUNTS = 5
	T_FINISHCOUNT = 6
	T_HOURTT = 7
	T_FLAGTAG = 8
	T_APPLECOLLECT = 9
	T_SPEED = 10

BATTLE_ATTRS - bitmask of the following:
	A_SEE_OTHERS = 1
	A_SEE_TIMES = 2
	A_STARTER_ALLOWED = 4
	A_BUGS_ACCEPTED = 8
	A_NO_VOLT = 16
	A_NO_TURN = 32
	A_ONE_TURN = 64
	A_NO_BRAKE = 128
	A_NO_THROTTLE = 256
	A_ALWAYS_THROTTLE = 512
	A_DRUNK = 1024