-
Notifications
You must be signed in to change notification settings - Fork 0
RESTful protocol
This page specifies the RESTful protocol between the client and server applications of the CASSANDRA platform.
The conventions for writing the protocol will be:
[uri returned] | [RESTful route] | [action]
Users should be able to login (MD5 hash and https as minimum security requirements) and after successfully entering their credentials, they should be redirected to /{usrnm}/prj, where a list of their projects should be displayed.
/{usrnm}/prj | GET /{usrnm}/prj | index
Fetches the working projects of the user with {usrnm}.
Consumes: Route
Produces: JSON
{ projects : [ { {id: 1, name: "ProjectA"}, {id: 2, name: "ProjectB"} } ] }
--
/{usrnm}/prj/new | GET /{usrnm}/prj/new | new
Prepares for editing a new Project. Can be though as of loading an empty Project (empty form with name and description).
Consumes: Route
Produces: (JSON, if decide on default values)
--
/{usrnm}/prj/{prj-id}/edit | GET /{usrnm}/prj/{prj-id}/edit | edit
Edits the name and description of the specific Project.
Consumes: Route
Produces: JSON
{ projects : [ { {id: 1, name: "ProjectA", description: "Testing insentives"} } ] }
--
/{usrnm}/prj/{prj-id} | GET /{usrnm}/prj/{prj-id} | show
Show the properties of a Project.
Consumes: Route
Produces: JSON
{ projects : [ { {id: 1, name: "ProjectA", description: "Testing insentives"} } ] }
/{usrnm}/prj/{prj-id} | PUT /{usrnm}/prj/{prj-id} | update
Updates the properties of the Project after editing.
Consumes: Route, JSON
{ projects : [ { {id=2, name: "Project II", description: "Neighborhood demand response programme."} } ] }
Produces: Update status
/{usrnm}/prj | POST /{usrnm}/prj | create
Creates a new Project for the given User, based on the properties filled up.
Consumes: Route, JSON
{ projects : [ { {name: "Project C", description: "One more test!"} } ] }
Produces: JSON, Create status (if failed)
{ projects : [ { {id: 1, name: "ProjectA"}, {id: 2, name: "ProjectB"}, {id: 3, name: "Project C"} } ] }
/{usrnm}/prj | DELETE /{usrnm}/prj/{prj-id} | delete
Deletes the specific Project and returns to the list of Projects.
Consumes: Route
Produces: Delete status
/{username}/prj/{prj-id}/scn | GET /{username}/prj/{prj-id}/scn | index
Fetches the ids and names of all the Scenarios in the Project.
Consumes: Route
Produces: JSON
{ scenarios : [ { {id: 1, name: "Scenario A"}, {id: 2, name: "Scenario B"} } ] }
--
/{username}/prj/{prj-id}/scn/{scn-id} | GET /{username}/prj/{prj-id}/scn/{scn-id} | show
Fetches all the the names, types and ids of the entities included in the given scenario. The data returned are grouped accordingly by the client in a tree structure.
Consumes: Route
Produces: JSON
{ scenarios : [ { {id: 1, name: "Scenario A", description: "Scenario A description"} } ] }
/{usrnm}/prj/{prj-id}/scn/new | GET /{usrnm}/prj/{prj-id}/scn/new | new
Prepares for editing a new Scenario. Can be though as of loading an empty Scenario (empty form with name and description).
Consumes: Route
Produces: (JSON, if decide on default values)
--
/{usrnm}/prj/{prj-id}/scn/{scn-id}/edit | GET /{usrnm}/prj/{prj-id}/scn/{scn-id}/edit | edit
Edits the name and description of the specific Scenario.
Consumes: Route
Produces: JSON
{ scenarios : [ { {id: 2, name: "Scenario B", description: "Scenario B description"} } ] }
/{usrnm}/prj/{prj-id}/scn/{scn-id} | PUT /{usrnm}/prj/{prj-id}/scn/{scn-id} | update
Updates the properties of the Scenario after editing.
Consumes: Route, JSON
Produces: Update status
{ scenarios : [ { {id: 2, name: "Scenario II", description: "A new scenario B description"} } ] }
/{username}/prj/{prj-id}/scn/{scn-id} | DELETE /{username}/prj/{prj-id}/scn/{scn-id} | delete
Deletes the Scenario with the given id.
Consumes: Route
Produces: Delete status
/{usrnm}/prj/{prj-id}/scn | POST /{usrnm}/prj/{prj-id}/scn | create
Creates a new scenario. Alternatively, one can create a copy of a Scenario in the same project by passing the {scn-id} as parameters i.e.:
POST /{usrnm}/prj/{prj-id}/scn?scn-id=2
Consumes: Route, JSON
If from new scenario:
{ scenarios : [ { {name: "Scenario C", description: "C's description"} } ] }
If a new Scenario is created via copy then nothing needs to be passed in JSON. The Scenario id to be copied will be passed as a parameter and the application server will copy the all the entities of the Scenario internally to produce a new Scenario with a new id.
Produces: JSON, Create status (if failed)
{ scenarios : [ { {id: 1, name: "Scenario A"}, {id: 2, name: "Scenario B"}, {id: 3, name: "Scenario C"} } ] }
/{username}/prj/{prj-id}/scn/{scn-id}/inst | GET /{username}/prj/{prj-id}/scn/{scn-id}/inst | index
Retrieves the installations in the scenario (names, ids).
Consumes: Route
Produces: JSON
--
/{username}/prj/{prj-id}/scn/{scn-id}/inst/{inst-id} | GET /{username}/prj/{prj-id}/scn/{scn-id}/inst/{inst-id} | show
Fetches the properties of the installation and other included entities (names, ids) such as Appliances that are included in the installation.
Consumes: Route
Produces: JSON
--
/{usrnm}/prj/{prj-id}/scn/{scn-id}/inst/new | GET /{usrnm}/prj/{prj-id}/scn/{scn-id}/inst/new | new
Prepares for editing a new Installation. Can be though as of loading an empty Installation (empty form).
Consumes: Route
Produces: JSON
--
/{usrnm}/prj/{prj-id}/scn/{scn-id}/inst/{inst-id}/edit | GET /{usrnm}/prj/{prj-id}/scn/{scn-id}/inst/{inst-id}/edit | edit
Fetches the properties of the Installation for editing.
Consumes: Route
Produces: JSON
/{usrnm}/prj/{prj-id}/scn/{scn-id}/inst | POST /{usrnm}/prj/{prj-id}/scn/{scn-id}/inst | create
Creates a new Installation based on the things added in the form. Alternatively, one can create a new Installation by making a drag-n-drop action from the library and passing the {lib-id} and {inst-id} ids as parameters or by copying an existing Installation i.e.:
a) POST /{usrnm}/prj/{prj-id}/scn/{scn-id}/inst?lib-id=1&inst-id=4
b) POST /{usrnm}/prj/{prj-id}/scn/{scn-id}/inst?inst-id=7
Consumes: Route, JSON
Produces: Create status
/{usrnm}/prj/{prj-id}/scn/{scn-id}/inst/{inst-id} | PUT /{usrnm}/prj/{prj-id}/scn/{scn-id}/inst/{inst-id} | update
Updates the properties of the Installation after editing.
In addition one can update the installation by dragging and dropping Appliances and/or Agents:
c) PUT /{usrnm}/prj/{prj-id}/scn/{scn-id}/inst/{inst-id}?app-id=23
d) PUT /{usrnm}/prj/{prj-id}/scn/{scn-id}/inst/{inst-id}?agnt-id=5
Consumes: Route, JSON
Produces: Update status
/{usrnm}/prj/{prj-id}/scn/{scn-id}/inst | DELETE /{usrnm}/prj/{prj-id}/scn/{scn-id}/inst/{inst-id} | delete
Deletes the existing Installation. The Appliances are not deleted if they are referenced in other Installations.
Consumes: Route
Produces: Delete status
Activities can be found only under a certain {inst-id}. This is to avoid cluttering the tree with many activities that have the same name but belong to agents in different installations (for example activity cooking or entertainment for 4-5 installations).
/{username}/prj/{prj-id}/scn/{scn-id}/inst/{inst-id}/act | GET /{username}/prj/{prj-id}/scn/{scn-id}/inst/{inst-id}/act | index
Retrieves the Activities presented in the specific Agent type (names, ids).
Consumes: Route
Produces: JSON
--
/{username}/prj/{prj-id}/scn/{scn-id}/inst/{inst-id}/act/{act-id} | GET /{username}/prj/{prj-id}/scn/{scn-id}/inst/{inst-id}/act/{act-id} | show
Fetches the properties of the Activity and other included entities (names, ids) such as ActivityModels.
Consumes: Route
Produces: JSON
--
/{usrnm}/prj/{prj-id}/scn/{scn-id}/inst/{inst-id}/act/new | GET /{usrnm}/prj/{prj-id}/scn/{scn-id}/inst/{inst-id}/act/new | new
Prepares for editing a new Activity. Can be though as of loading an empty Activity (empty form).
Consumes: Route
Produces: JSON (deafult valutes?)
--
/{usrnm}/prj/{prj-id}/scn/{scn-id}/inst/{inst-id}/act/{act-id}/edit | GET /{usrnm}/prj/{prj-id}/scn/{scn-id}/inst/{inst-id}/act/{act-id}/edit | edit
Fetches the properties of the Activity for editing.
Consumes: Route
Produces: JSON
/{usrnm}/prj/{prj-id}/scn/{scn-id}/inst/{inst-id}/act | POST /{usrnm}/prj/{prj-id}/scn/{scn-id}/inst/{inst-id}/act | create
Creates a new Activity based on the things added in the form. Alternatively, one can create a new Activity by making a drag-n-drop action from the library and passing the {lib-id} and {act-id} ids as parameters or by copying an existing Activity i.e.:
a) POST /{usrnm}/prj/{prj-id}/scn/{scn-id}/inst/{inst-id}/act?lib-id=1&act-id=4
b) POST /{usrnm}/prj/{prj-id}/scn/{scn-id}/inst/{inst-id}/act?act-id=7
Consumes: Route, params, JSON
Produces: Create status
--
/{usrnm}/prj/{prj-id}/scn/{scn-id}/inst/{inst-id}/act/{act-id} | PUT /{usrnm}/prj/{prj-id}/scn/{scn-id}/inst/{inst-id}/act/{act-id} | update
Updates the properties of the Activity after editing.
Consumes: Route, JSON
Produces: Update status
--
/{usrnm}/prj/{prj-id}/scn/{scn-id}/inst/{inst-id}/act | DELETE /{usrnm}/prj/{prj-id}/scn/{scn-id}/inst/{inst-id}/act/{act-id} | delete
Deletes the existing Activity. The Activity is deleted from other Agents referencing it.
Consumes: Route
Produces: Delete status
Each Activity has ActivityModels. For example we could have weekday cooking and weekend cooking.
/{usrnm}/prj/{prj-id}/scn/{scn-id}/agnt/{agnt-id}/act/{act-id}/actmod | GET /{usrnm}/prj/{prj-id}/scn/{scn-id}/agnt/{agnt-id}/act/{act-id}/actmod | index
Fetches all the ActivityModels inside the given Activity.
Consumes: Route
Produces: JSON
--
/{usrnm}/prj/{prj-id}/scn/{scn-id}/agnt/{agnt-id}/act/{act-id}/actmod/{actmod-id} | GET /{usrnm}/prj/{prj-id}/scn/{scn-id}/agnt/{agnt-id}/act/{act-id}/actmod/{actmod-id} | show
Fetches the properties of an ActivityModel and other included entities (names and ids) i.e. Distribution.
Consumes: Route
Produces: JSON
--
/{usrnm}/prj/{prj-id}/scn/{scn-id}/agnt/{agnt-id}/act/{act-id}/actmod/new | GET /{usrnm}/prj/{prj-id}/scn/{scn-id}/agnt/{agnt-id}/act/{act-id}/actmod/new | new
Prepares for editing a new ActivityModel. Can be though as of loading an empty ActivityModel (empty form).
Consumes: Route
Produces: JSON (default values?)
--
/{usrnm}/prj/{prj-id}/scn/{scn-id}/agnt/{agnt-id}/act/{act-id}/actmod/{actmod-id}/edit | GET /{usrnm}/prj/{prj-id}/scn/{scn-id}/agnt/{agnt-id}/act/{act-id}/actmod/{actmod-id}/edit | edit
Fetches the properties of the ActivityModel for editing.
Consumes: Route
Produces: JSON
/{usrnm}/prj/{prj-id}/scn/{scn-id}/agnt/{agnt-id}/act/{act-id}/actmod | POST /{usrnm}/prj/{prj-id}/scn/{scn-id}/agnt/{agnt-id}/act/{act-id}/actmod | create
Creates a new ActivityModel for the given Activity, based on the properties filled up by the user.
Consumes: Route, JSON
Produces: Create status
/{usrnm}/prj/{prj-id}/scn/{scn-id}/agnt/{agnt-id}/act/{act-id}/actmod/{actmod-id} | PUT /{usrnm}/prj/{prj-id}/scn/{scn-id}/agnt/{agnt-id}/act/{act-id}/actmod/{actmod-id} | update
Updates the properties of the ActivityModel after editing.
Consumes: Route, JSON
Produces: Update status
/{usrnm}/prj/{prj-id}/scn/{scn-id}/agnt/{agnt-id}/act/{act-id}/actmod | DELETE /{usrnm}/prj/{prj-id}/scn/{scn-id}/agnt/{agnt-id}/act/{act-id}/actmod/{actmod-id} | delete
Deletes the existing ActivityModel.
Consumes: Route, JSON
Produces: Delete status
/{usrnm}/prj/{prj-id}/scn/{scn-id}/app | GET /{usrnm}/prj/{prj-id}/scn/{scn-id}/app | index
Fetches all the Appliances inside the scenario.
Consumes: Route
Produces: JSON
--
/{usrnm}/prj/{prj-id}/scn/{scn-id}/app/{app-id} | GET /{usrnm}/prj/{prj-id}/scn/{scn-id}/app/{app-id} | show
Fetches the properties of an appliance and other included entities (names and ids) i.e. ConsumptionModel. Using this route the user can edit directly an appliance presented in the installation(s) without browsing specifically for it through the Installations path.
Consumes: Route
Produces: JSON
--
/{usrnm}/prj/{prj-id}/scn/{scn-id}/app/new | GET /{usrnm}/prj/{prj-id}/scn/{scn-id}/app/new | new
Prepares for editing a new Appliance. Can be though as of loading an empty Appliance (empty form).
Consumes: Route
Produces: JSON (default values?)
--
/{usrnm}/prj/{prj-id}/scn/{scn-id}/app/{app-id}/edit | GET /{usrnm}/prj/{prj-id}/scn/{scn-id}/app/{app-id}/edit | edit
Fetches the properties of the Appliance for editing.
Consumes: Route
Produces: JSON
/{usrnm}/prj/{prj-id}/scn/{scn-id}/app | POST /{usrnm}/prj/{prj-id}/scn/{scn-id}/app | create
Creates a new consumption model for the given Appliance, based on the properties filled up by the user when creating a new ConsumptionModel. Alternatively, one can create a new appliance by making a drag-n-drop action from the library and passing the {lib-id} and {app-id} ids as parameters i.e.:
POST /{usrnm}/prj/{prj-id}/scn/{scn-id}/app?lib-id=1&app-id=4
Consumes: Route, JSON, params
Produces: Create status
/{usrnm}/prj/{prj-id}/scn/{scn-id}/app/{app-id} | PUT /{usrnm}/prj/{prj-id}/scn/{scn-id}/app/{app-id} | update
Updates the properties of the Appliance after editing.
Consumes: Route, JSON
Produces: Update status
/{usrnm}/prj/{prj-id}/scn/{scn-id}/app | DELETE /{usrnm}/prj/{prj-id}/scn/{scn-id}/app/{app-id} | delete
Deletes the existing Appliance. The Appliance is deleted from all the Installations referencing it as well.
Consumes: Route
Produces: Delete status
There is no id in the RESTful routes for the ConsumptionModel since there is a 1 to 1 relationship between the ConsumptionModel and the Appliance.
/{usrnm}/prj/{prj-id}/scn/{scn-id}/app/{app-id}/cnsmod | GET /{usrnm}/prj/{prj-id}/scn/{scn-id}/app/{app-id}/cnsmod | show
Fetches the properties of the ConsumptionModel for visualization purposes.
/{usrnm}/prj/{prj-id}/scn/{scn-id}/app/{app-id}/cnsmod/new | GET /{usrnm}/prj/{prj-id}/scn/{scn-id}/app/{app-id}/cnsmod/new | new
Prepares for editing a new ConsumptionModel. Can be though as of loading an empty ConsumptionModel (empty form).
/{usrnm}/prj/{prj-id}/scn/{scn-id}/app/{app-id}/cnsmod/edit | GET /{usrnm}/prj/{prj-id}/scn/{scn-id}/app/{app-id}/cnsmod/edit | edit
Fetches the properties of the ConsumptionModel for editing.
All read ops:
Consumes: Route
Produces: JSON
/{usrnm}/prj/{prj-id}/scn/{scn-id}/app/{app-id}/cnsmod | POST /{usrnm}/prj/{prj-id}/scn/{scn-id}/app/{app-id}/cnsmod | create
Creates a new consumption model for the given Appliance, based on the properties filled up by the user when creating a new ConsumptionModel.
Consumes: Route, JSON
Produces: Create status
/{usrnm}/prj/{prj-id}/scn/{scn-id}/app/{app-id}/cnsmod | PUT /{usrnm}/prj/{prj-id}/scn/{scn-id}/app/{app-id}/cnsmod | update
Updates the properties of the ConsumptionModel after editing.
Consumes: Route, JSON
Produces: Update status
/{usrnm}/prj/{prj-id}/scn/{scn-id}/app/{app-id}/cnsmod | DELETE /{usrnm}/prj/{prj-id}/scn/{scn-id}/app/{app-id}/cnsmod | delete
Deletes the existing ConsumptionModel.
Consumes: Route
Produces: Delete status
Entity containing the simulation parameters of the scenario i.e. Calendar, location information, number of runs etc. Each scenario can have many Simulations.
/{usrnm}/prj/{prj-id}/scn/{scn-id}/sim | GET /{usrnm}/prj/{prj-id}/scn/{scn-id}/sim | index
Fetches all the Simulations inside the scenario.
Consumes: Route
Produces: JSON
--
/{usrnm}/prj/{prj-id}/scn/{scn-id}/sim/{sim-id} | GET /{usrnm}/prj/{prj-id}/scn/{scn-id}/sim/{sim-id} | show
Fetches the properties (simulation parameters) of a Simulation.
Consumes: Route
Produces: JSON
--
/{usrnm}/prj/{prj-id}/scn/{scn-id}/sim/new | GET /{usrnm}/prj/{prj-id}/scn/{scn-id}/sim/new | new
Prepares for editing a new Simulation. Can be though as of loading an empty Simulation (empty form).
Consumes: Route
Produces: JSON
--
/{usrnm}/prj/{prj-id}/scn/{scn-id}/sim/{sim-id}/edit | GET /{usrnm}/prj/{prj-id}/scn/{scn-id}/sim/{sim-id}/edit | edit
Fetches the properties of the Simulation for editing.
Consumes: Route
Produces: JSON
/{usrnm}/prj/{prj-id}/scn/{scn-id}/sim | POST /{usrnm}/prj/{prj-id}/scn/{scn-id}/sim | create
Creates a new _Simulation for the given Scenario, based on the properties filled up by the user when creating a new Simulation.
Consumes: Route, JSON
Produces: Create status
/{usrnm}/prj/{prj-id}/scn/{scn-id}/sim/{sim-id} | PUT /{usrnm}/prj/{prj-id}/scn/{scn-id}/sim/{sim-id} | update
Updates the properties of the Simulation after editing.
Consumes: Route, JSON
Produces: Update status
/{usrnm}/prj/{prj-id}/scn/{scn-id}/sim | DELETE /{usrnm}/prj/{prj-id}/scn/{scn-id}/sim/{sim-id} | delete
Deletes the existing Simulation.
Consumes: Route
Produces: Delete status
A run is created when a user decides to execute a scenario given some simulation parameters.
/{usrnm}/prj/{prj-id}/runs | GET /{usrnm}/prj/{prj-id}/runs | index
Displays a list with all the runs (queued, completed, running) under the given project.
Consumes: Route
Produces: JSON
--
/{usrnm}/prj/{prj-id}/runs/{run-id} | GET /{usrnm}/prj/{prj-id}/runs/{run-id} | show
Displays the status and/or the results of the given run.
Consumes: Route
Produces: JSON
/{usrnm}/prj/{prj-id}/sims | POST /{usrnm}/prj/{prj-id}/sims | create
Creates a new run by posting the entire scenario.
Consumes: Route, JSON
Produces: Create status
/{usrnm}/prj/{prj-id}/sims | DELETE /{usrnm}/prj/{prj-id}/sims/{sim-id} | delete
Deletes the run along with the results.
Consumes: Route
Produces: Delete status
/{usrnm}/prj/{prj-id}/sims/{sim-id} | PUT /{usrnm}/prj/{prj-id}/sims/{sim-id}/{pause|resume} | update status
Based on what is passed in the http request the run can be paused or resumed.
Consumes: Route
Produces: Update status
We assume for now that the libraries are read-only (R ops). There is no functionality in the protocol (yet) to make CUD operations. Also Demographics and CSNs to be added in the library.
/libs | GET /libs | index
Returns a list of libs along with their ids.
--
/libs/{lib-id} | GET /libs/{lib-id} | index
For the given {lib-id} a list of contained entities is returned along with their name, type and id. These entities are structured in a tree according to their type. For now four top level types will be available: Installation, Appliance, Activity and DemandSideManagement.
--
/libs/{lib-id}/inst | GET /libs/{lib-id}/inst | index
Returns a list of Installations available in the library.
--
/libs/{lib-id}/app | GET /libs/{lib-id}/app | index
Returns a list of Appliances available in the library.
--
/libs/{lib-id}/act | GET /libs/{lib-id}/act | index
Returns a list of Activities available in the library.
--
/libs/{lib-id}/dsm | GET /libs/{lib-id}/dsm | index
Returns a list of DemandSideManagement schemes available in the library.
--
/libs/{lib-id}/inst/{inst-id} | GET /libs/{lib-id}/inst/{inst-id} | show
Displays the properties of the Installation with that {inst-id}.
--
/libs/{lib-id}/inst/{inst-id}/app | GET /libs/{lib-id}/inst/{inst-id}/app | index
Displays the Appliances of the Installation with that {inst-id}.
--
/libs/{lib-id}/inst/{inst-id}/app/{app-id} | GET /libs/{lib-id}/inst/{inst-id}/app/{app-id} | show
Displays the properties of the {app-id} Appliance of the Installation with that {inst-id}.
--
/libs/{lib-id}/inst/{inst-id}/app/{app-id}/consmod | GET /libs/{lib-id}/inst/{inst-id}/app/{app-id}/consmod | show
Displays the ConsumptionModel of the {app-id} Appliance of the Installation with that {inst-id}.
--
/libs/{lib-id}/app/{app-id} | GET /libs/{lib-id}/app/{app-id} | show
Displays the properties of the Appliance with that {app-id}.
--
/libs/{lib-id}/app/{app-id}/consmod | GET /libs/{lib-id}/app/{app-id}/consmod | show
Displays the ConsumptionModel of the given Appliance.
Under development.
Under development.