Maniaplanet Forum

Posted: **08 Jul 2012, 06:48**

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.

Posted: **08 Jul 2012, 17:52**

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.

Posted: **08 Jul 2012, 19:29**

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!!

Posted: **09 Jul 2012, 07:24**

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

Documentation updated to better describe this.

Xymph wrote: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?}

Xymph wrote: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.

Xymph wrote: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.

Electron wrote: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.

Electron wrote: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.

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

See my initial response to your first question.

Electron wrote: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.

Electron wrote: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.

Electron wrote: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.

Posted: **09 Jul 2012, 21:05**

fastforza wrote:
Electron wrote: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.

fastforza wrote: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.

Posted: **10 Jul 2012, 21:05**

fastforza wrote:
Xymph wrote: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.

fastforza wrote:
Xymph wrote: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'.

fastforza wrote:
Electron wrote: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.

fastforza wrote:
Electron wrote: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.

fastforza wrote: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.

fastforza wrote: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?

Posted: **11 Jul 2012, 12:41**

Xymph wrote: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.

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

Fixed.

Xymph wrote:but as long as it doesn't happen again this decade

Not likely.

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

Fixed. It's now 'maps'.

Xymph wrote: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).

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

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

Xymph wrote: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.

Posted: **12 Jul 2012, 18:53**

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

Posted: **12 Jul 2012, 21:21**

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}]

Posted: **13 Jul 2012, 05:13**

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

anvolcano wrote: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.

Maniaplanet Forum

Mania Exchange API (Controller Developers & Consumers)

Mania Exchange API (Controller Developers & Consumers)

Re: Mania Exchange API (Controller Developers)

Re: Mania Exchange API (Controller Developers)

Re: Mania Exchange API (Controller Developers & Consumers)

Re: Mania Exchange API (Controller Developers & Consumers)

Re: Mania Exchange API (Controller Developers & Consumers)

Re: Mania Exchange API (Controller Developers & Consumers)

Re: Mania Exchange API (Controller Developers & Consumers)

Re: Mania Exchange API (Controller Developers & Consumers)

Re: Mania Exchange API (Controller Developers & Consumers)