Christer
Joined: Aug 02, 2003
|
As a way to kick off this new forum, I'll give an outline of my plans for a new API for the site, which I'm hoping I'll have the time to flesh out more as time goes by. At this point, it's mostly an API framework with only a couple of initial API calls available.
The basic idea of the API is to unify how things are being processed on the site and externally. The origins are from me starting to work on custom league rulesets (which is evident from the early API calls available). At its core, it's set up with a framework which allows me to add an API method which can be directly called from my own internal code.
These methods all return an internal dictionary (hash set, associative array, whatever you want to call it) which isn't very useful for external access. So, the framework has an external publishing system which more or less automatically converts the API methods into either JSON or XML.
The intent here is that I'll push new functionality into this API system which will keep things consistent between the site and the API.
Basic overview
The base path for this new API is located at: https://fumbbl.com/api. Note that this should always be accessed through https. The generic API call follows the same format:
https://fumbbl.com/api/[endpoint]/[command][/parameters][/xml]
The optional /xml suffix will give you the result in XML format rather than the default (JSON).
There are currently only four API endpoints: Coach, Ruleset, Roster and Position.
Authentication
The API supports authentication through normal browser cookies or a planned OAUTH mechanism. HTTP cookies are generally speaking there for FUMBBL itself to communicate with the API and shouldn't be used by third parties. Currently, no external authentication is supported.
Coach http://fumbbl.com/api/coach
This is a fairly simple system as of yet, and allows searching the registered coaches.
Example: https://fumbbl.com/api/coach/search/Chri/xml
The resulting XML would look like this:
| Code: |
<coaches>
<coach id="3545">chris</coach>
<coach id="10236">Chriz</coach>
<coach id="35500">chrisr</coach>
<coach id="15452">Chrids</coach>
<coach id="20503">ChrisK</coach>
<coach id="71057">ChrisL</coach>
<coach id="23167">chri54</coach>
<coach id="129739">chriss</coach>
<coach id="55597">chris6</coach>
<coach id="91561">ChrisH</coach>
</coaches>
<!-- Processing 0.276ms, encoding 0.102ms -->
|
Note that the XML isn't necessarily formatted. The equivalent JSON query ( https://fumbbl.com/api/coach/search/Chri ) would give you this:
| Code: |
[{"id":"3545","value":"chris"},{"id":"10236","value":"Chriz"},{"id":"35500","value":"chrisr"},{"id":"15452","value":"Chrids"},{"id":"20503","value":"ChrisK"},{"id":"71057","value":"ChrisL"},{"id":"23167","value":"chri54"},{"id":"129739","value":"chriss"},{"id":"55597","value":"chris6"},{"id":"91561","value":"ChrisH"}]
|
While wildcards are not supported, the query will add an implicit wildcard at the end of the search string. The resulting list is sorted by increasing length (makes the exact match show up first).
Ruleset https://fumbbl.com/api/ruleset
This endpoint has three commands: list, get and create
list - https://fumbbl.com/api/ruleset/list/xml
Returns a list of current rulesets the user is a manager of. Note that this requires an active session or an OAUTH token to access. Example result:
| Code: |
<rulesets>
<ruleset id="1">LRB6</ruleset>
<ruleset id="2">Stunty</ruleset>
<ruleset id="3">FFB Test</ruleset>
<ruleset id="4">test ruleset</ruleset>
<ruleset id="6">League</ruleset>
</rulesets>
|
get - https://fumbbl.com/api/ruleset/get/1/xml
Returns detailed information about a ruleset. Example output:
| Code: |
<ruleset>
<id>1</id>
<name>LRB6</name>
<managers>
<manager id="3">Christer</manager>
</managers>
<rosters>
<roster id="41">Amazon</roster>
<roster id="42">Chaos</roster>
<roster id="43">Chaos Dwarf</roster>
<roster id="44">Dark Elf</roster>
<roster id="45">Dwarf</roster>
<roster id="46">Elf</roster>
<roster id="47">Goblin</roster>
<roster id="48">Halfling</roster>
<roster id="49">High Elf</roster>
<roster id="50">Human</roster>
<roster id="51">Khemri</roster>
<roster id="52">Lizardman</roster>
<roster id="53">Necromantic</roster><roster id="54">Norse</roster>
<roster id="55">Nurgle</roster><roster id="56">Ogre</roster>
<roster id="57">Orc</roster><roster id="58">Skaven</roster>
<roster id="59">Undead</roster><roster id="60">Vampire</roster>
<roster id="61">Wood Elf</roster>
<roster id="64">Chaos Pact</roster>
<roster id="65">Slann</roster>
<roster id="66">Underworld</roster>
</rosters>
</ruleset>
|
create - https://fumbbl.com/api/ruleset/create/xml
This creates a ruleset, and takes the name of the ruleset as a POST variable (name). Returns a ruleset ID (as a string).
Roster - https://fumbbl.com/api/roster
This endpoint allows getting roster information and allows creation of new rosters. There are two commands: get and create
get - https://fumbbl.com/api/roster/get/51/xml
Returns information about a roster. Not supplying example information as it's too verbose (although load the URL in your browser and you'll see it).
create - https://fumbbl.com/api/roster/create/xml
Creates a new roster. Takes two parameters (again, through HTTP POST):
- ruleset, a numeric RulesetId as provided by the ruleset/create call)
- name, a name for the new roster
Returns a numeric roster id (as a string).
Position - https://fumbbl.com/api/position
Positional information. Only one command at this point: get
get - https://fumbbl.com/api/position/get/2894/xml
Returns an informational view of a position
Ok, that's a quick and non-exhaustive overview of the current state of the new API. I'd happily get some input from you guys on how I could improve and/or extend this API for your use. My hope is that it will make things considerably easier for you to deal with.
Also, on a related note, documentation is incredibly tedious to write... Formatting things alone is a pain 
Edit:There's also an initial notes page I did a while back about this. I will likely not continue that work though as it's amazingly time-consuming to format in bbcode like that. |
|
|
the_Sage
Joined: Jan 13, 2011
|
 Posted:
Nov 17, 2014 - 17:19 |
 
|
Hooray! I wonder what marvellous plugins and scripts people will build with it. |
|
|
koadah
Joined: Mar 30, 2005
|
| Posted:
Nov 17, 2014 - 17:26 |
|
|
Balle2000
Joined: Sep 25, 2008
|
| Posted:
Nov 17, 2014 - 17:31 |
|
| the_Sage wrote: | | Hooray! I wonder what marvellous plugins and scripts people will build with it. |
you tell us, mr sage! 
anyway, fumbbl keeps going forward! great stuff |
|
|
Roland
Joined: May 12, 2004
|
| Posted:
Nov 17, 2014 - 17:35 |
|
Custom rosters! Finally!  
Great work! |
|
|
Roland
Joined: May 12, 2004
|
| Posted:
Nov 18, 2014 - 09:36 |
|
I'm not really a programmer, but have learned some xml parsing at work. However, I have no idea how to use the POST method, can someone point me to a good tutorial? (yes, I have searched).
How complicated is it? |
|
|
Garion
Joined: Aug 19, 2009
|
| Posted:
Nov 18, 2014 - 10:11 |
|
Roster Position - Just to clarify, is this just to show a player positional so we can see which positionals are listed as Thrall for example?
If so we will need the ability to create Position as well as having 'get'. So we can choose our own Thralls, or is this handled in Roster Create?
Rosters Create- in this section can we chose whether teams have access to an apothecary, necromancer (and which player is resurrected), igor, cheaper bribes (like goblin), cheaper chef (like flings)
Sorry this is too technical for me, so pardon my ignorance if I have completely missed the point in this |
_________________
 |
|
Christer
Joined: Aug 02, 2003
|
A POST is effectively a form submission. How you do that depends a bit on what library you're using for HTTP.
For jQuery (Javascript), you can use $.post, or $.ajax({ type: 'POST', ... })
For Java, you'd effectively use a DataOutputStream on a HttpsURLConnection (see http://www.mkyong.com/java/how-to-send-http-request-getpost-in-java/ for an example).
In C#, you'd use the UploadValues method of the WebClient class.
In Ruby, you'd use Net::HTTP.post_form()
In Python, you'd use you'd use the request() method of httplib.HTTPConnection.
In PHP, you'd use http_post_fields()
If neither of those are the language you use, you could always google [<whatever language you want> http post]. Plenty of examples. |
|
|
Roland
Joined: May 12, 2004
|
| Posted:
Nov 18, 2014 - 10:24 |
|
| Christer wrote: | | In Python, you'd use you'd use the request() method of httplib.HTTPConnection. |
brilliant thx
oh, missed this sentence. so no custom rosters yet then
when will we be able to create positionals?[/quote] |
|
|
Christer
Joined: Aug 02, 2003
|
A bit of clarification:
An API (expands to Application Programming Interface) is a way for two different applications to "talk" to each other. That means that this is absolutely not designed for end-users, but for people who like to develop applications that access FUMBBL data (for example the FFB Server, or Koadah's sprint website).
With this new API version I've started to work on, FUMBBL itself will use it as well (through javascript on the pages, ie AJAX) for new features (such as custom rulesets for the league division).
What it comes down to is that if this is too technical for you, it's likely not aimed at you
Also, this stuff is very very early in the development process, and will over time be extended to allow for more features (setting the thrall flag on positionals for example, or simply setting the stats in the first place) |
|
|
Garion
Joined: Aug 19, 2009
|
| Posted:
Nov 18, 2014 - 10:35 |
|
Ok cool. Thanks, it isn't for me as you say, though as you also know I have an interest in this because of SL, and will be getting someone to do the code stuff required to get it off the ground.
But it seems as though its too early to do things like setting player stats and so on. So will just sit quietly in the background for now keeping an eye on things until the Api allows what I need |
_________________
|
|
jamesfarrell129
Joined: Dec 23, 2009
|
| Posted:
Nov 18, 2014 - 10:47 |
|
| Christer wrote: | | Also, on a related note, documentation is incredibly tedious to write... Formatting things alone is a pain |
I've not used it, but I've heard good things about Swagger for documenting (REST) APIs... is that something you could use?
Any plans on adding BBCode tags for some of these, so data can be put into player/team bios? Or is that something that we could do? |
_________________
NAF name: sandwich |
|
koadah
Joined: Mar 30, 2005
|
| Posted:
Nov 18, 2014 - 11:10 |
|
| Christer wrote: | A POST is effectively a form submission. How you do that depends a bit on what library you're using for HTTP.
For jQuery (Javascript), you can use $.post, or $.ajax({ type: 'POST', ... })
For Java, you'd effectively use a DataOutputStream on a HttpsURLConnection (see http://www.mkyong.com/java/how-to-send-http-request-getpost-in-java/ for an example).
In C#, you'd use the UploadValues method of the WebClient class.
In Ruby, you'd use Net::HTTP.post_form()
In Python, you'd use you'd use the request() method of httplib.HTTPConnection.
In PHP, you'd use http_post_fields()
If neither of those are the language you use, you could always google [<whatever language you want> http post]. Plenty of examples. |
So, are we going to be allowed to update the server or is this a help build the interface kind of thing? |
_________________
Open [L]eague Tournaments - NOW recruiting!! Old/New style skill progression! - Secret League - All Stars! |
|
Christer
Joined: Aug 02, 2003
|
| koadah wrote: | | So, are we going to be allowed to update the server or is this a help build the interface kind of thing? |
My intent is to have feature parity between the website itself and the external API. This is mostly because it'll be the easiest way to do things (aside from me needing to add support for OAUTH in the API framework).
To begin with, though, the API will only cover things I am currently working on adding to the site (which initially will be custom rulesets/rosters for League), but it's relatively easy for me to add new components and methods for various parts of the FUMBBL data model (for example porting the old API queries).
As an example, the old roster api call (/xml:roster) has code like this:
| Code: |
$xml->simpleNode('name', $r->Fields('name'));
$xml->simpleNode('type', 'Regular');
$xml->simpleNode('reRollCost', $r->Fields('reroll_cost'));
$xml->simpleNode('maxReRolls', 8);
$xml->simpleNode('baseIconPath', 'http://fumbbl.com/');
$xml->simpleNode('raisedPositionId', $r->Fields('raise_position'));
$xml->simpleNode('apothecary', $r->Fields('apothecary') == 'Yes' ? 'true' : 'false');
$xml->simpleNode('necromancer', $r->Fields('wizard') == 'Necro' ? 'true' : 'false');
$xml->simpleNode('undead', $r->Fields('undead') == 'Yes' ? 'true' : 'false');
|
Essentially, this generates part of an XML document.
The new API code is a bit easier:
| Code: |
$positions[] = array(
'id' => $positionId,
'gender' => $res->Fields('gender'),
'title' => $res->Fields('name'),
'quantity' => $res->Fields('quantity'),
'iconLetter' => $res->Fields('shortname'),
'cost' => $res->Fields('cost'),
'stats' => array('MA'=>$res->Fields('movement'), 'ST'=>$res->Fields('strength'), 'AG'=>$res->Fields('agility'), 'AV'=>$res->Fields('armor')),
'portrait' => $res->Fields('image_id'),
'skill/skills' => $skills[$positionId],
'normalSkill/normalSkills' => $normalSkills[$positionId],
'doubleSkill/doubleSkills' => $doubleSkills[$positionId]
);
|
This generates an (associative) array with the data, which is then in the API wrapper converted into whatever form is needed (directly returned as a PHP object, converted to JSON or converted to XML as appropriate). It simplifies writing new methods on my end significantly as it properly separates data gathering from presentation. If needed, I could also add more output formats on top of XML and JSON fairly easily (for example, pushing into a comma separated values format for spreadsheet use) if needed.
Those, together with the fact that I wanted to make the custom roster stuff more responsive (ie, use AJAX) and nicer to use drove me into making the effort of building this API framework in the first place. And adding things like OAUTH and external support is mostly there to allow the developers out there among you to get a better, more solid feature set out of a unified system rather than the fragmented API calls I already implemented in the old system.
So to answer your question directly, it's a bit of both. If I don't add write support, but still have the website itself use the API (ie, using normal cookies), devs tend to find their way around it by processing the login form and parse HTML. This is less than ideal (and a waste of server resources), so I figured I may as well go ahead with will read/write access using standard secure technologies. Using OAUTH allows me to segment access to parts of the site (for example allow bio editing on teams, but no access to private messages) to third party tools. Pretty important stuff. |
|
|
Shraaaag
Joined: Feb 15, 2004
|
| Posted:
Nov 18, 2014 - 18:49 |
|
This looks promising Keep on the good work |
_________________
 |
|
|
|
| |
solution for weak ga...
Search
