Autonomous Underwater Vehicles : trex - ODSS web API This page last changed on Jun 05, 2013 by fpy. This working document is used to specify how T-REX will present a web API in order to easily be connected to ODSS (or any other software). The document will evolve as our work advance and start from a very high level specification at first down to much more precise API definition. Initial service calls considered. General services get short help TREX version Tick and date related services Current tick Next tick Initial tick Final tick tick info tick at a date tick rate/duration Wait for new tick Timelines and goals services List of trex existing timelines Contents of a timeline Post a new goal Modify an existing goal Cancel a goal Push services envisioned ## Initial service calls considered. As a first step we propose the following simple calls (To be refined as implementation is done):
| In this initial version neither the format of the web request or the data structure is defined. We plan to do so using a RESTful kind of approach with json as the basis of representation but nothing is fully settled nor implemented yet. Principle on request arguments: required parameters are always part of the path (e.g. /timeline/{name} indicate that the argument {name} need to be specified). Due to this format the position of each of these argument is significant optional parameters will be specified in the query part of the url (e.g /timeline/{name}?from=0&to=100) indicate that arguments from and to are optionals).
- ### General services #### get short help get short help format: GET http://<host>/rest/help GET http://<host>/rest/help/{cmd-path} Gets the list of services – under {cmd-path} if provided – along with a short help message output example: GET http://<host>/rest/help/help
      {
          "help":
          [
              {
                  "href": "\/rest\/help",
                  "info": "List REST commands availables.\nArgument restrict the help to command matching given path."
              }
          ]
      }
- #### TREX version TREX version format: GET http://<host>/rest/version Gets information of the currently running version of trex output:
      {
          "version_major": "0",
          "version_minor": "5",
          "version_release": "0",
          "version_rc": "1",
          "svn_root": "trunk",
          "svn_rev": "1450",
          "version_str": "0.5.0-rc1 (svn:trunk[1450])"
      }
- note svn_rev may not be a integer but is the output of the svnversion command. Which mean that ift can be a range of version (eg 1447:1450) and/or be postfixed by a modification flag letter (M for locally modified, S for a branch of tag instead of the trunk) ### Tick and date related services #### Current tick Current tick format: GET http://<host>/rest/tick Give information about the next tick of trex output: GET http:://<host>/rest/tick
      {
          "value": "2656",
          "date": "2013-06-04T15:29:04.923976"
      }
- value : the tick value as represented by trex date : the corresponding UTM date #### Next tick Next tick format: GET http://<host>/rest/tick/next Give information about the current tick of trex output: GET http:://<host>/rest/tick/next
      {
          "value": "2658",
          "date": "2013-06-04T15:31:04.923976"
      }
- value : the tick value as represented by trex date : the corresponding UTM date #### Initial tick Initial tick format: GET http://<host>/rest/tick/initial Give information about the first tick of trex (usually 0) output: GET http:://<host>/rest/tick/initial
      {
          "value": "0",
          "date": "2013-06-02T19:13:04.923976"
      }
- value : the tick value as represented by trex date : the corresponding UTM date #### Final tick Final tick format: GET http://<host>/rest/tick/final Give information about the last tick of trex. The last tick of trex is the date where it will quit. output: GET http:://<host>/rest/tick/final
      {
          "value": "1000000",
          "date": "2015-04-28T05:53:04.923976"
      }
- value : the tick value as represented by trex date : the corresponding UTM date #### tick info tick info format: GET http://<host>/rest/tick/{number} Give information about the tick {number} output example: GET http:://<host>/rest/tick/2658
      {
          "value": "2658",
          "date": "2013-06-04T15:31:04.923976"
      }
- value : the tick value as represented by trex date : the corresponding UTM date #### tick at a date tick at a date format: GET http://<host>/rest/tick/at/{date} Give information about the largest tick before or at the provide UTC {date} output example: GET http:://<host>/rest/tick/at/2014-01-01
      {
          "value": "305566",
          "date": "2013-12-31T23:59:04.923976"
      }
- value : the tick value as represented by trex date : the corresponding UTM date #### tick rate/duration tick rate/duration format: GET http://<host>/rest/tick/rate Give information about the duration of a tick output: GET http:://<host>/rest/tick/rate
      {
          "nanoseconds": "60000000000",
          "duration": "00:01:00"
      }
- - nanoseconds : the duration in ns duration : same duration as [H*]HH:MM:SS[.SUBSECOND] #### Wait for new tick Wait for new tick format: GET http://<host>/rest/tick/wait This request implements a long pull in order for the client to be notified when the next tick occurs. The request will not respond until the next tick occurs. output: similar to GET http://<host>/rest/tick ### Timelines and goals services #### List of trex existing timelines List of trex existing timelines format: GET http://<host>/rest/timelines GET http://<host>/rest/timelines/timline_a/timeline_b ... options: full=(0|1) set it to 1 in order to see all the timelines (including timelines with name starting with an underscore). Useful only when no timeline names are appended to the URL format=(tick|date) indicate whether data of from and to option are expressed as trex tick or ISO date. Default is date from=<tick_or_date> give a lower bound for the time window of interest. the value format depends on format option to=<tick_or_date> give a upper bound for the he time window of interest. the value format depends on format option example GET http://<host>/timelines?full=1&format=tick&from=10 input: none output: a list of all the timelines trex currently have as a json object with a format as given in this example
        {
            "timelines":
            [
                {
                    "name": "dorado_state",
                    "alive": "true",
                    "accept_goals": "false",
                    "latency":
                    {
                        "ticks": "0",
                        "duration": "00:00:00"
                    },
                    "look_ahead":
                    {
                        "ticks": "0",
                        "duration": "00:00:00"
                    },
                    "publish_plan": "false",
                    "href": "/rest/timeline/dorado_state"
                },
                {
                    "name": "dorado_survey",
                    "alive": "true",
                    "accept_goals": "true",
                    "latency":
                    {
                        "ticks": "0",
                        "duration": "00:00:00"
                    },
                    "look_ahead":
                    {
                        "ticks": "1",
                        "duration": "00:01:00"
                    },
                    "publish_plan": "false",
                    "href": "/rest/timeline/dorado_survey"
                },
                ...
            ]
        }
- - "timelines" is the table containing all the timelines descriptors A timeline descriptor have the following fields: "name" the symbolic name of the timeline "href" the URI pointing to the timeline (see "Content of timeline" below) "alive" a boolean indicating whether this timeline is still managed or "dead" (resulting on a Failed state) "accept_goals" a boolean indicating if this timeline accept goals or not (for example position updates on assets do not accept goals) "publish_plan" a boolean indicating if this timeline will publish its future when it has a plan or can only display its past and current state "latency" The expected maximum delay until a received goal on this timeline will be processed "look_ahead" How far ahead in the future this timeline is usually planned for "total_obs" Number of tokens for this token that overlaps from, to "obs_period" Average duration of tokens for this token that overlaps from, to booth look_ahead and latency are json object giving their value both in term of TREX tick and real-time duration notes: The set of timelines may be dynamic and can grow as time advance (e.g. A new asset is added dynamically). Similarly all the attached information (except for their name) can change as the mission advance (although we often avoid it). Only total_obs and obs_period are affected by the from and to options It is possible to restrict the set of timeline to a known subset by specifying them on the URI. For example get http://<host>/rest/a/b/c will give information of only a, b and c #### Contents of a timeline Contents of a timeline formats: GET http://<host>/rest/timeline/{name} GET http://<host>/rest/timeline/{name}?from={date} GET http://<host>/rest/timeline/{name}?from={date}&to={date} GET http://<host>/rest/timeline/{name}?to={date}&format=date GET http://<host>/rest/timeline/{name}?from={int}&to={int}&format=tick input: {name} the name of the timeline format the format used to specify from and to . Possible formats are: date : from and to are specified as date (eg 2013-06-03T16:04:57.330-07:00) tick : from and to are given as integer which are directly trex tick values If not specified the default format is date from lower bound of the time window of interest (optional) to upper bound of the time window of interest (optional) when to is not specified it is set to +infinity, when from is not specified it is set to the current tick of -infinity if the specified to is in the past. output: The list of all the tokens of this timeline that overlaps the given time interval. Meaning all the token which can end after from (ie their largest possible end time is >= to from) can start before to (ie their smallest possible start time is <= to to) While the json format id still underwork here's an example of what I have now : (the request: http://<host>/rest/timeline/dorado_survey?from=2013-06-03T16:04:57.330-07:00&to=2013-06-13T16:10:29.449-07:00)
        {
          "name": "dorado_survey"
          "requested_tick_range": {
            "int": {
              "max": "16077",
              "min": "1671"
            }
          },
          "tokens": [
            {
              "pred": "None",
              "on": "dorado_survey"
              "Variable": [
                {
                  "name": "start",
                  "type": "date",
                  "date": {
                    "value": "2013-06-02T19:13:04.923976"
                  }
                },
                {
                  "name": "end",
                  "type": "date",
                  "date": {
                    "min": "2013-06-04T15:36:04.923976"
                  }
                },
                {
                  "name": "duration",
                  "type": "duration",
                  "duration": {
                    "min": "44:23:00"
                  }
                }
              ]
            }
          ]
        }
- In this example the result has the following attributes : "name" : The name of the timeline "alive" : Indicates if this timeline is currently still managed "requested_tick_range" : an interval giving the range [from, to] into ticks "token" : A table with all the tokens that match this range. Tokens are sorted by occurrence order error: 400: invalid request. The timeline name is either missing or non existent 400: parsing error from the optionals fields example: GET http://<host>/rest/timeline/dorado?from=2013-05-23&to=2013-05-31T12:00:00 GET http://<host>/rest/timeline/dorado?from=0&to=100&format=tick #### Post a new goal Post a new goal format: POST http://<host>/rest/goal Associated data: the goal in json format (request header need to set Content-Type to application/json) example of a curl command:
      curl -X POST --header 'Content-Type:application/json' -d '
         {
              "on": "dorado_survey",
              "pred": "Track",
              "Variable": [
                  { "name": "drifter",
                    "type": "enum",
                    "enum": { "elem": [ { "value": "MBARI21" } ] }
                  },
                  { "name": "lagrangian",
                    "type": "bool",
                    "bool": { "value": "1" }
                  },
                  { "name": "path",
                    "enum": { "elem": [ { "value": "square" } ] }
                  },
                  { "name": "size",
                    "float": { "value": 1000.0 }
                  },
                  { "name": "start",
                    "type": "date",
                    "date": { "min": "2013-05-16T15:53:00" }
                  },
                  { "name": "duration"
                    "duration": { "max": "18:00:00" },
                    "type": "duration"
                  }
              ]
          }
         }' http://<host>/rest/goal
- output on success: A json structure with the following attributes: id : A unique identifier for the goal href: URL where this goal can be accessed (through GET or DELETE) Goal: The goal representation (should be fairly similar to what data was posted but with small tweaks such as updated start duration and end information) example output from the command above:
      {
          "id": "0xb0425cb0",
          "href": "/rest/goal/0xb0425cb0",
          "Goal":
          {
              "on": "dorado_survey",
              "pred": "Track",
              "Variable":
              [
                  {
                      "enum":
                      {
                          "elem":
                          [
                              {
                                  "value": "spotSim"
                              }
                          ]
                      },
                      "type": "enum",
                      "name": "drifter"
                  },
                  {
                      "bool":
                      {
                          "value": "1"
                      },
                      "type": "bool",
                      "name": "lagrangian"
                  },
                  {
                      "enum":
                      {
                          "elem":
                          [
                              {
                                  "value": "square"
                              }
                          ]
                      },
                      "type": "enum",
                      "name": "path"
                  },
                  {
                      "float":
                      {
                          "value": "1000.0000000000000000"
                      },
                      "type": "float",
                      "name": "size"
                  },
                  {
                      "date":
                      {
                          "min": "2013-05-16T16:16:01.566673"
                      },
                      "type": "date",
                      "name": "start"
                  },
                  {
                      "date":
                      {
                          "min": "2013-05-16T16:17:01.566673"
                      },
                      "type": "date",
                      "name": "end"
                  },
                  {
                      "duration":
                      {
                          "min": "00:01:00",
                          "max": "18:00:00"
                      },
                      "type": "duration",
                      "name": "duration"
                  }
              ]
          }
      }
- error: 400: invalid request the goal is not well formatted note: This feedback of this call only indicate whether the goal is properly formatted or not. An OK do not mean that the goal has been included in the plan yet (which is asynchronous and dynamic) but only that the reactors that manage the associated timeline has been notified of this new goal #### Modify an existing goal Modify an existing goal format: PUT http://<host>/rest/goal/{id} input: {id} the identifier of the goal as given by the response to a "Post new goal" command attachment: A json file describing the goal output: 200 OK error: 404: Goal not found (invalid goal id) 400: invalid request the goal is not well formatted note: An OK does not mean that the goal has been updated in the plan yet (which is asynchronous and dynamic) but only that the reactors that manage the associated timeline have been notified of this new goal
  | This operation will not be implemented initially. For any modification, first DELETE then (re)POST the goal.
#### Cancel a goal Cancel a goal format: DELETE http://<host>/rest/goal/{id} input: {id} the identifier of the goal as given by the feedback of "Post new goal" command output: none error: 400: unknown goal id effect: remove the goal with the associated id from the plan This 3 simple calls will be the first basis of interaction. We envision later on to add extra calls as we see fit. ## Push services envisioned new plan This service will notify the client whenever trex produced a new plan As trex is composed to multiple planners, each of them dealing with its specific set of timlines. It may be better for the user to specify which set of timelines it want to be notified on similarly the event should give the set of timelines that have been updated

Document generated by Confluence on Feb 04, 2026 08:05