Skip to content

Home

Jump to bottom
Kristofer Rye edited this page Sep 1, 2015 · 5 revisions

The FReCon HTTP API

You can start the FReCon server like so:

$ frecon server -p 5964 -o 0.0.0.0

Once you've started the server, you should see something like this:

== Sinatra (v1.4.6) has taken the stage on 5964 for development with backup from Thin
Thin web server (v1.6.3 codename Protein Powder)
Maximum connections set to 1024
Listening on 0.0.0.0:5964, CTRL+C to stop

You can change the values for -p and -o as you wish to change which port and address you bind to.

Then, you can connect to this address (in the example, 0.0.0.0:5964) and use the HTTP API.

The API

FReCon uses all of the standard HTTP keywords to complete transactions, and all data is encoded as JSON.

There are six models:

  • Team
  • Robot
  • Participation
  • Competition
  • Record
  • Match

Here are some patterns to consider:

  • Teams have many Robots. (They create a new Robot every year)
  • Robots have many Participations. (Competitions have many Participations as well.)
  • Participations have many Records.
  • Competitions have many Matches.
  • Matches have many Records.

Each different model in the database has some way of reaching the other models in the database.

For example, a Team's Competitions can be determined by taking each of their Robots' Participations and collecting the Competition from each of them.

Model Routes

For each of the given models in the database, there is a very standardized way of interacting with them.

HTTP Verb Route Description Response JSON type
GET /<model>s Returns a list of instances of the <model> model. Array
GET /<model>s/<id> Returns the given instance of the <model> model. Object
POST /<model>s Creates an instance of the <model> model, and returns its JSON representation once it gets stored. Object
PUT /<model>s/<id> Updates the given instance of the <model> model, and returns its JSON representation once the changes are made. Object
DELETE /<model>s/<id> Deletes the given instance of the <model> model. N/A

HTTP POST and PUT requests require a JSON body to the request.

Relational Routes

In addition to being able to query a given model according to the standard, you can also explore different relationships of models.

For each model, general querying routes for all models excepting that model can be appended to a search for that model to obtain that model's related other models.

You can send a GET to any of the following routes.

Here's a basic list:

  • Team model

  • /teams/<id>/robots

  • /teams/<id>/participations

  • /teams/<id>/competitions

  • /teams/<id>/matches

  • /teams/<id>/records

  • Robot model

  • /robots/<id>/team

  • /robots/<id>/participations

  • /robots/<id>/records

  • /robots/<id>/matches

  • /robots/<id>/competitions

  • Participation model

  • /participations/<id>/robot

  • /participations/<id>/competition

  • /participations/<id>/records

  • /participations/<id>/matches

  • /participations/<id>/team

  • Record model

  • /records/<id>/participation

  • /records/<id>/match

  • /records/<id>/competition

  • /records/<id>/robot

  • /records/<id>/team

  • Match model

  • /matches/<id>/competition

  • /matches/<id>/records

  • /matches/<id>/participations

  • /matches/<id>/robots

  • /matches/<id>/teams

  • Competition model

  • /competitions/<id>/matches

  • /competitions/<id>/participations

  • /competitions/<id>/records

  • /competitions/<id>/robots

  • /competitions/<id>/teams

Fields

Each model can accept dynamic attributes. (Huge thanks to MongoDB!) If you want to encode more data into records that are taken for each match, just do that! Add those as custom-named fields for each record you take. We have come up with some basic fields that we think should be present in each model, so we've hardcoded these.

  • Team
    Field Description Required? Type
    number The Team's number. Yes. Integer
    name The Team's name. No. String
    location The Team's location (home). No. String
    logo_path A path to a Team's logo. No. String
  • Robot
    Field Description Required? Type
    team_id The Robot's parent Team's ID. Yes. String
    name The Robot's name. No. String
  • Participation
    Field Description Required? Type
    robot_id The Participation's parent Robot's ID. Yes. String
    competition_id The associated Competition's ID. Yes. String
  • Competition
    Field Description Required? Type
    name The Competition's name. Yes. String
    location The Competition's location. Yes. String
  • Match
    Field Description Required? Type
    number The Match number in TBA format (e.g. "qm67" for Qualification match #67). Yes. String
    competition_id The Match's parent Competition's ID. Yes. String
    blue_score Blue team's score (this could be edited later). No. Integer
    red_score Red team's score (this could be edited later). No. Integer
  • Record
    Field Description Required? Type
    participation_id The Record's parent Participation's ID. Yes. String
    match_id The Record's parent Match's ID. Yes. String
    position The Position of this record (Which position was the team playing? e.g. "r1" for Red 1). Yes. String
    notes Any notes taken in this match. No. String

IDs

MongoDB uses special ID's to store in the database. When you get an object from the database, its _id field will contain something somewhat like this: 507f191e810c19729de860ea. This can be substituted as a <id> field in any of the above routes if you want to get information for that object.

Clone this wiki locally