Mania Exchange API (Controller Developers & Consumers)

[fastforza]

Hello controller developers!

What is the Mania Exchange API?
The MX API is a HTTP web service provided by Mania Exchange that returns information about tracks/maps, users and statistics.

Who can consume the API?
Anyone! Provided you make valid requests.

The old API. Version 1.0
The old API is not supported any more and I strongly advise against using it in your applications. It will continue to exist to avoid breaking applications that cannot update to the new API.

If you're an active controller developer, please upgrade your application to the new API immediately.

The new API. Version 2.0
The new API is functional and supports both TrackMania 2 and ShootMania. I strongly suggest this is the API you use!

For more information about the API, please visit the API website here.

Discussions and suggestions welcome. I will also be happy to provide support in this thread.

[Xymph]

Thanks to RamCUP2000 for withdrawing his broken versions of my MX-related PHP classes. I'm working on updating them myself.

Comments/questions on the new documentation:

http://api.mania-exchange.com/documents/changes describes a Content-Type request header, but its format and effect are somewhat unclear. In a HTTP request, I think it should be formatted "Content-Type: mime" rather than with a " => ".
Also, 'mime' appears to require a real MIME-type string such as 'application/json' to return JSON data, so maybe it's better described in parameter brackets, like "Content-Type: <MIME-type>" ?
And the new API does return a JSON response when this header is absent, so it's not actually required.

What is the new API format for the old /api/replays/get_replays/{trackID}/ call?

Edit: And for the old /api/tracks/get_latest_tracks/ call? It appears to (somewhat) work on the TM side but returns 100 entries instead of 10, and it's not clear what the corresponding SM call looks like.

Will http://tm.mania-exchange.com/api and http://sm.mania-exchange.com/api be updated or retired?

http://api.mania-exchange.com/documents/shootmania lists this string in the second section:
http://api.mania-exchange.com/tm/tracks/{ids,} which should be http://api.mania-exchange.com/sm/maps/{ids,}

Possible more to follow once I've spent more time on this.

[Electron]

Hello Forzyy,

why do you change the API? We all have to rewrite our code (if it already includes the expected queries for SM and QM).

This may be ok for a controller developer. But I use the API inside an Windows application (GbxDump). All users of this software have to download a new version.

Why don't you implement the 1.0 API for ShootMania and QuestMania? In my code are the queries already included. If my tool opens a SM map, I simply replace the sub domain from tm.mania-exchange.com to sm.mania-exchange.com. Same for QuestMania. And I expected that this works!


Some words to the new API:

They are consistent and also not future save.

Why can I choose the returning format (JSON or XML) in the search api and not in the map information api?

Why does the TM2 query path includes the folder "tracks" and the SM path the folder "maps"?
This results in unnecessary code with large if/else blocks. Someone deletes RamCUP2000's posting. But his posted code shows it in a good way. He also included already a query for QuestMania. He used also the Path api.mania-exchange.com/qm/maps/. But no one knows how do you really implemet this api in future, if you have a bad day (;-). Maybe api.mania-exchange.com/qm/quests/?
A API without any game name in the path (like the Dedimania API) would be very user friendly, because the UID of a map is unique (I am not sure if this is also with the MX id).

I use the WinINet API to access the MX API with this easy to use functions:

InternetOpen(g_szUserAgent, INTERNET_OPEN_TYPE_PRECONFIG, NULL, NULL, 0);
InternetOpenUrl(hInternet, pszUrl, NULL, 0, 0, 0);
InternetReadFile(hInternetFile, pszData, dwSize, &dwRead);

But these return only the JSON format. I do not know how to get the results in XML format.
So please include the format parameter also in the map info api!!

[fastforza]

t's better described in parameter brackets, like "Content-Type: <MIME-type>" ?

Documentation updated to better describe this.

What is the new API format for the old /api/replays/get_replays/{trackID}/ call?

This is the new route:

Code: Select all

http://api.mania-exchange.com/tm/replays/{id}/{amount?}

Will http://tm.mania-exchange.com/api and http://sm.mania-exchange.com/api be updated or retired?

I do not and will not support the old APIs. They will continue to exist, but will never be updated.

http://api.mania-exchange.com/documents/shootmania lists this string in the second section:
http://api.mania-exchange.com/tm/tracks/{ids,} which should be http://api.mania-exchange.com/sm/maps/{ids,}

Fixed.

why do you change the API?

I needed to unify the APIs. Having multiple APIs spread across multiple projects is a nightmare to manage. E.g modify core functionality in one project and every other project needs to be modified.

We all have to rewrite our code (if it already includes the expected queries for SM and QM).

I know it's a disaster for certain programs, but it's something you'll have to adjust to.

Why don't you implement the 1.0 API for ShootMania and QuestMania?

See my initial response to your first question.

n my code are the queries already included. If my tool opens a SM map, I simply replace the sub domain from tm.mania-exchange.com to sm.mania-exchange.com. Same for QuestMania. And I expected that this works!

You should never have done this in the first place. Assuming I continued to support the 1.0 API, did it ever occur to you that the API methods would have changed as well? E.g get_latest_tracks would have become get_latest_maps.

Why can I choose the returning format (JSON or XML) in the search api and not in the map information api?

I've added support back for the format parameter. You can use it for every request now.

Why does the TM2 query path includes the folder "tracks" and the SM path the folder "maps"?

It's a drawback from the original application design. MX was months into development before Nadeo decided to change everything to 'maps'. There were far too many references to 'tracks' in the application to change (speaking from the back-end where DB and classes had references to 'tracks').

But for the sake of consistency with 'maps', all methods that contain 'tracks' in the route can now be accessed with 'maps'.

The term 'maps' will be used for QuestMania when it arrives. I can guarantee you this will not change.

I've updated the API with new methods and documentation changes to address yours and Xymph's concerns.

[Electron]

Why can I choose the returning format (JSON or XML) in the search api and not in the map information api?

I've added support back for the format parameter. You can use it for every request now.

Thank you. But I will also look for a solution to use the HTTP MIME request by using the functions InternetConnect, HttpOpenRequest and HttpSendRequest. But at the moment I do not know which parameters I have to specify.

But for the sake of consistency with 'maps', all methods that contain 'tracks' in the route can now be accessed with 'maps'.

Fine! Now we need only one if/else instruction for the TrackID resp. MapID element. EDIT: Not really.

[Xymph]

Will http://tm.mania-exchange.com/api and http://sm.mania-exchange.com/api be updated or retired?

I do not and will not support the old APIs. They will continue to exist, but will never be updated.

My bad, I meant just their documentation pages, belatedly realizing that the docs are part of the API links.

http://api.mania-exchange.com/documents/shootmania lists this string in the second section:
http://api.mania-exchange.com/tm/tracks/{ids,} which should be http://api.mania-exchange.com/sm/maps/{ids,}

Fixed.

Almost, the syntax is shown as "http://api.mania-exchange.com/sm/map/{ids,}" without 's' after 'map'.

We all have to rewrite our code (if it already includes the expected queries for SM and QM).

I know it's a disaster for certain programs, but it's something you'll have to adjust to.

Yeah, it's a bit of a pain, but as long as it doesn't happen again this decade I don't have a problem with it.

Why does the TM2 query path includes the folder "tracks" and the SM path the folder "maps"?

It's a drawback from the original application design. MX was months into development before Nadeo decided to change everything to 'maps'. There were far too many references to 'tracks' in the application to change (speaking from the back-end where DB and classes had references to 'tracks').

Okay, but why does the SM section still use 'tracks' in the download links? E.g. http://sm.mania-exchange.com/tracks/download/195 on http://sm.mania-exchange.com/maps/view/195
That's an inconsistency I hope you'll still fix.

But for the sake of consistency with 'maps', all methods that contain 'tracks' in the route can now be accessed with 'maps'.

Thanks, but since TM2 links (e.g. to the track's file and download) still require 'tracks', it doesn't matter as I still have to test at least once in my MX classes whether the TM2 or another section is being requested.

I've updated the API with new methods and documentation changes to address yours and Xymph's concerns.

Thanks for all that, much clearer now.

While working through the changes I noticed a new field in the TM2 data: TrackValue. This is also shown on TM2 track pages, and while I found a reference to it in the site change log (being able to sort on it), it's not clear to me what the value means. Can you explain or point me to a description?

In the SM data there's also a new field: UnlimiterRequired. However, in both the TM2 and SM sections when using advanced search, there's a checkbox for that flag. Shouldn't the field then also be included in the TM2 data returned by the API?

On the TM2 side, track screenshots are available in two sizes, via /tracks/screenshot/normal/<id> and /tracks/screenshot/small/<id> links, but on the SM side it looks like just one (normal) size is available via a different path: /maps/thumbnail/<id> . Is that going to stay this way?

[fastforza]

My bad, I meant just their documentation pages, belatedly realizing that the docs are part of the API links.

They'll remain as is for now. I will eventually direct users to the new API.

Almost, the syntax is shown as "http://api.mania-exchange.com/sm/map/{ids,}" without 's' after 'map'.

Fixed.

but as long as it doesn't happen again this decade

Not likely.

Okay, but why does the SM section still use 'tracks' in the download links?

Fixed. It's now 'maps'.

While working through the changes I noticed a new field in the TM2 data: TrackValue

Track value is the name we gave to a tracks' leaderboard rating (formerly LB rating - TMX).

In the SM data there's also a new field: UnlimiterRequired.

I've updated the track class. The field is now visible.

On the TM2 side, track screenshots are available in two sizes, via /tracks/screenshot/normal/<id> and /tracks/screenshot/small/<id> links, but on the SM side it looks like just one (normal) size is available via a different path: /maps/thumbnail/<id> . Is that going to stay this way?

Thumbnails are not extracted from the files on the TM2 exchange. I will also add a smaller version of the thumbnail at a later stage.

Route clarification: {type} = tracks or maps.
/{type}/screenshot/normal/{id} => Returns the user uploaded screenshot. The default is the extracted thumbnail.
/{type}/screenshot/small/{id} => Smaller (thumbnail) version of the user uploaded screenshot. No default.

I don't recommend using the thumbnail images at this stage. References to them have been removed.

[Xymph]

Thanks for the remaining clarifications and fixes. I've now released the updated PHP classes MX Info Fetcher and MX Info Searcher.

[anvolcano]

Will you update the "TypeName" returned for a script to be the actual script type instead of simply "Script" for ShootMania maps? For example, this map is a JailbreakArena map, but the TypeName returned is "Script":

Code: Select all

[{"MapID":274,"UserID":41,"Username":"Akbalder","UploadedAt":"2012-07-12T19:51:14.213","
UpdatedAt":"2012-07-12T19:51:14.213","Name":"Jailbreak~Roundwalls","TypeName":"Script",
"Mood":"Day","DisplayCost":6177,"ModName":"","Lightmap":5,"ExeVersion":"3.2.0",
"ExeBuild":"2012-07-12_00_4","EnvironmentName":"Storm","UnlimiterRequired":false,
"DifficultyName":"Intermediate","Comments":"Jailbreak map on two levels with a lot of round walls. The goals are protected by walls.",
"Rating":0.0,"RatingExact":0.0,"RatingCount":0,"CommentCount":0}]

[fastforza]

Thanks for the remaining clarifications and fixes. I've now released the updated PHP classes MX Info Fetcher and MX Info Searcher.

Will you update the "TypeName" returned for a script to be the actual script type instead of simply "Script" for ShootMania maps? For example, this map is a JailbreakArena map, but the TypeName returned is "Script":

You're mistaking map type for the game type. Type name is an internal value like Race, Stunt or Platform. What's missing from the result is MapType which I'll add to both sites/games/APIs.