Hex Server API - What it is and how to access it

    • Hex Server API - What it is and how to access it

      This is a mere copy-paste of what I consider to be a very important post by Chris Woods from the previous forums, where he introduces the Hex Server API that saw the day with Herofall.


      Hey all,

      With the release of Herofall we've added in a server side API for people to poke around with. I think this is awesome, but I could see people being concerned, so I wanted to make a thread here to ensure everyone knows what it's all about. I'm going to start by explaining the top level stuff that everyone probably wants to know, then I get into the more technical bits at the end.

      So, to everyone regardless of if you develop 3rd party apps or even care these API's even exist:

      • What information does the server API provide?
        • Currently, it provides the result of every tournament that runs on the server. That means every pack and card picked (when appropriate; eg - draft, sealed), every deck built, and every match result.
      • Does this mean people can use the API to see my tournament record?
        • No. The player names are anonymized per tournament. The API sends out random numbers to represent each player.
      • Are there any non-anonymous tournaments?
        • Any tournament type can be marked as public, making the player names display instead of the numbers. Currently, only Five Shards tournaments use this feature, but if other community tournaments wanted to publicly display the names of everyone involved we're happy to oblige.
      • When does the API broadcast tournament results?
        • Tournament results are broadcast after the tournament has completely concluded, which includes sending out prizes, etc. You couldn't listen to the server feed and snipe your opponents or see what they drafted or anything like that.
      • When does a "Ladder" conclude? What about EVO Gauntlet?
        • Ladder matches send data as soon as the match has ended. Gauntlet runs send data per player as soon as that player has either gone 5-X or X-3.
      • What sort of things is this good for?
        • What immediately comes to mind is something to help me the community get better at drafting. With this feed people could aggregate hundreds of drafts and talk about what deck archetypes are winning, what cards are really first picks, etc. Anyone with sufficient data mining skills can probably yank out all sorts of amazing information.
        • It also does a pretty good job of letting people understand what decks are getting played in various metas, what those decks win rates are verses other deck, and stuff like that. It's basically "all the data on tournaments ever", which has got to be full of interesting things to know in the right hands.
      • So, it's just for tournament players?
        • For now that's true. Like the client API, as time goes on I intend to keep expanding this. Giving people a real-time feed into Auction House immediately pops into my head, maybe something broadcasting all mulligans/keeps and if that game was won would be interesting? I'm sure there's a lot of cool things we can do with this.

      Okay, so that's really all I can think to talk about for the average player on this. If I missed something, feel free to ask here in the thread and I'll try to check back regularly. Now onto people who actually want to implement things for this.

      • How can I setup a listener to the server API feed?
        • Send an email to chris.woods@hextcg.com with the http address you want to listen from and I'll set it up. It can take a few days, as I have to clear each entry with other folks, poke a hole in the firewall, and make double sure you don't get to talk back to the server, just listen.
      • I just saw this post after a year/my listener was down while I was on vacation/I missed data somehow.
        • I archive the entire feed since the launch of Herofall. Just let me know (chris.woods@hextcg.com) and I'll host a link with every message the API has ever sent. They're keyed by timestamp/tournament_id which creates a unique set per entry in case you're comparing against your database to prevent double entries.
      • Will my listener ever be removed from the list?
        • If the server times out trying to tell you a message for 24 hours it gives your server a "strike". After the server successfully communicates with your listener for 24 hours it removes all strikes from your server. If the API server ever gives your server three strikes (you're down for 72 hours) it will automatically remove you from the list and you'll have to email me again to get put back on.
      • What do the messages look like?
        • They're pretty complicated JSON messages but the key names are pretty good. It would be really long to list here, but I'll include the basics in a response to your email to get setup.

      That's all I can think of off the top of my head, but like I said feel free to ask anything in this thread and I'll try to keep up to date. I can't wait to see the cool things people make of this!

      Chris Woods