Skip to content

REST api design

Jump to bottom
Theo van Hoesel edited this page Jan 25, 2015 · 9 revisions

Top level resources

Contrary of we have been used to, the cont_id as for example "yn2015' will no longer be used, but /YAPCNA/2015... which reflects the future structure of a 'region authority' and a specific occurrence of that event. They will be internally mapped until such thing will be realised. This will also help setting up Act for local Perl Monger meetings like /AmsterdamX/2015_01/ or /AmsterdamX/JAN_2015/

  • /api/conferences - Fetches information about all conferences

    • GET - returns a list of all conferences as HREFs .../api/{authority}/{instance}/, this will NOT return a list of api/conferences/{conference_id}

  • /api/conferences/{conference_id}

    This should not really give any info, most will go through /api/{authority}/{instance}/... and possibly result in an 404 Not Found error or a reroute to the previous mentioned.

  • /api/{authority}/{instance}/ - Specific conference or event

    • /api/{authority}/{instance}/news/
      • POST - Post a new news item
      • GET
    • /api/{authority}/news/
    • /api/{authority}/{instance}/attendees/
      • GET
    • /api/{authority}/{instance}/attendees/{user_id}
      • PUT - Attend the conference
      • DELETE - Delete the participation
    • /api/{authority}/{instance}/talks/
      • POST - Suggest a talk for the conference
    • /api/{authority}/{instance}/events/
      • POST - Add an event to the conference
      • GET - Gets the events of the conference
    • /api/{authority}/{instance}/rooms/
    • /api/{authority}/{instance}/rooms/{room_id}/schedule
      • GET - Get the schedule for the specific room

  • /api/news/

    • GET - Not quit convinced to return 'all' the news, this is related to a 'authority' or 'instance'.

  • /api/news/{news_item_id}

    • GET - Retrieve the news_item
    • DELETE - Remove it

  • /api/users/

    • GET - Why would we return a list of all users in the database?

  • /api/users/{user_id}

    • GET /api/users?login=sjn
    • DELETE - remove permanently
    • PUT - update entirely
    • POST - Create a new user

  • /api/users/{user_id}/schedule ????

    • GET - Get the user specific schedule.
    • PUT - Update the users schedule. Must provide a talk_id

  • /api/talks/

  • /api/talks/{talk_id}

    • PUT - Updates the talk

  • /api/talks/{talk_id}/attendees

    • GET - Get all people attending the talk

  • /api/events ???? what is this?

  • /api/events/{event_id} ???? or this?

For the time being, the REST api will return simple JSON structure, application/json MIME-types.

Every plural resources, like filters and related objects by their path, returns:

[
  {
    href :  "",
    label : ""
  }
  ...
]

Every request for specific resources returns a simple flat JSON object

{
  attribute1 : "value 1",
  attributew : "value 2",
  ...
}

For more complex things in a later stage, we'll use content negotiation to provide more complex responds in application/HAL+json.

Remark: Schedule is a 'complex' thing, it's more than just a list of talks, it does need to represent also the other events that are happening. It would probably look like a list of 'calendar items', however iCal is a pretty heave format.

Questions: Did we come to a decision about versioning? Whats next?

Clone this wiki locally