Resources

[This page is temporary — once I have the code, it will be replaced by an executable file. (Therefore the API documentation will always be up to date!)]

These are the resources the web service/webpage will expose.

Note: Why the URLs are Important

These URLs have multiple purposes:

• humans will see them when browsing our webpage/using the interface
• crawlers such as Google will see them when indexing the website
• since this is a RESTful service, this is the API — any clients will have to work with these URLs
• they will be used internally — access will be granted or refused based on the URL, so we need them to have a logical hierarchy (so that the access rules are short & sweet — who wants to manage long lists?)

Note for Sysel

No, there is no 'admin interface'. My view of this is a nice web service (which happens to have a pretty web interface, too), which means everybody is free to access and work with the public data — no restrictions.

My Humble Proposal

General Pattern

/{what}/{where}/{id if viewing single}

E.g.:

/MPQ12/teams/Slovakia/Bratislava/30 is team #30 in Bratislava, Slovakia in the MPcharge 2012 contest (what: MPQ12/teams, where: Bratislava/Slovakia, id: 30)
/current/results/ are the global results in the currently running contest (only what is set)
/current/results/Slovakia are the country-wide results for Slovakia in the currently running contest (id is empty)
/MPQ12/problems/2 is problem #2 in MPcharge 2012 (where is not set => globally)

Note: This is also how access will be granted: the "where" part corresponds to Location and the "what" part to Realm, as described on the access rules page.

Further parameters (such as searching/filtering) go into the query.

All Resources

Please add what is missing and correct what is wrong! I will use this as the specification of what the system is supposed to do.

Note: in the following, contest can have the special value of current or all where it makes sense.

Homepage

• /
  the home page / general info + links to previous and next contest (and list of the top-level URLs as below — the top menu for the webpage, part of the representation for the web service)

Contests

• /{contest}/ /{contest}/info /{contest}/info/{state} /{contest}/info/{state}/{city}
  general information about the contest (where, when, etc.) + links to teams, results, problems etc. if available

• /{contest}/teams /{contest}/teams/{state} /{contest}/teams/{state}/{city} /{contest}/teams/{state}/{city}/{id}
  list of teams or detailed info about a team

• /{contest}/teams/{state}/{city}/{id}/submits
  the submits of the given team: a GET will show a list; it is possible to use all as id for GET requests; a POST is for submitting a task - this will save the submit (creates a resource with timestamp-based ID) and update results

• /{contest}/problems /{contest}/problems/{id}
  problems in the given contest

  • for a past contest: the problems used in the contest; id is the problem number
  • for a future contest: admin interface for proposing, editing and voting for problems; id is based on the user who submitted the problem and a counter
  • for a running contest these resources are inaccessible for unprivileged users and same as for past contests for orgs

• /{contest}/orgs /{contest}/orgs/{state} /{contest}/orgs/{state}/{city}
  list of organizers responsible for the given contest

Users (incl. organizers)

• /users/{id}
  the user's profile; id is the unique OAuth ident (e.g. Gmail address if using Google OAuth, username.myopenid.com for MyOpenID, etc.

• /users/{id}/access
  the access permissions for this user

  • this is mainly relevant for organizers, but to have a consistent implementation, unprivileged users will inherit the default permission to (1) register a team if they are not part of one yet, or (2) edit the team that they are part of

(Semi-)Static Content

Interesting for the Public

• /info
  basic info

• /why
  ideas behind MPcharge

• /rules
  how the contest works

• /join
  how to help

• /contact
  contact the organizers

• /who
  who we are

For the Orgs

• /how
  manuals (global)

• /how/{country}
  manuals (country-specific, managed by country-wide organizers)

• /when
  important dates (global)

• /when/{country}
  important dates (country-specific, managed by country-wide organizers)

• /email/ /email/{country} manage e-mail redirection from *@mpcharge.org accounts

• /translate
  entry point for adding translations

Country-Specific Websites

If a country wishes so, we can allow them to use a .mpcharge.org subdomain (e.g. sk.mpcharge.org) for their own website (but we will not provide hosting nor take responsibility for the content).