I have been investigating with different API structures (REST, XML-RPC and SOAP) as part of work and I think it's a good time to talk about the Chom 4 Application Programming Interface.
API What?
The Chom 4 API will allow other developers to easily get at data in Chom Isis and perform some actions without visiting the web page.
API Why?
I've been asked by a number of Chom players for access to an API so that they can make their own tools to help them play. You can do this now by using a "screen scraper" and by writing your own HTTP post agent with cookie/session support but it's a huge amount of work.
REST
REST is a type of API that uses query strings to input data and gives data back in a variety of formats. For example:http://www.chomisis.net/api/alliances
Would send you information about all the allianceshttp://www.chomisis.net/api/alliances/1
Would send you information about alliance with id of 1
Return data type would be specified using a parameter like:http://www.chomisis.net/api/alliance/1/format/jsonhttp://www.chomisis.net/api/alliances/1/format/xmlhttp://www.chomisis.net/api/alliances/1/format/html
So you could just pop the url into the browser. If you're a developer, there are lots of libraries out there depending on your chosen language.
Details
The examples above are ok but they don't really cover the complexities of authentication and API bashing. The API would work by the following process:
- Authenticate: provide username and password for the user account
- Chom returns a token character string such as jgmbcvjhgksdf
- When you make a call to the api, you include the token: http://www.chomisis.net/api/alliances/1/token/gmbcvjhgksdf
- If you don't use the token for 20 minutes, you need to ask for a new one and you can only make a limited number of calls to the API each hour for a given user account.
Features
Phase 1
Very much a read-only phase where you can get data out of the system but not do much to it.
- Authentication - Getting your token
- Dashboard - simple list of useful stuff from front page
- Players - List of players and leaderboard positions
- Pawns - pawn list
- Comms - Messageboard/PM listing
- Jobs - Get info on your own jobs
Phase 2
Adding some send information, alliance and the map.
- Comms - Able to send messages
- Alliances - get information
- Map - get information on map levels
The future phases will depend on what people want to do after.
Supporting stuff
The API will have its own Development Server, with a perpetually running game that resets overnight. This will give developers something to test against. I will also need to produce a load of documentation for it. APIs without documentation are fucking annoying.
So, that's what will happen in 4. It's a long way off but I have to plan now to code later.
Comments
I reckon it's a great idea.
While initially I was thinking "I'll do something in Flash", I'd actually be tempted to see if I can whip something up for Android. I now a little bit of java, and the documentation seems pretty good, and in all honesty I'm more lightly to play on my phone than on a flash app on a PC, which could easily just access the normal page anyway.
I'm glad I'm barking up the right sort of tree. The end goal is to have an API such that you don't need to log into the site except to do admin tasks. Of course, I will not extend my 'protection' of neutrality to 3rd party CI apps. I would even entertain the concept of AI players, if one could be created that was clever enough and wasn't just chaff.
Chom 4 will have a mobile site too (thanks to the framework it is built on) but I think there is a huge amount of benefit in having an Android App that connects to the game and provides notifications and the like.
I've had a play with a few little apps in Android and I'd say it was a superb Dev environment. The documentation and support is superb. Eclipse is a bit heavyweight but it does everything you need.
I've actually had some training on Eclipse at work..main issue with it was that it was a complete pig to install on our work machines...a combination of stupid base-builds, and varying admin rights.
I do wonder how well a facebook app would work, mainly for the increase in audience it would bring?