[Bug 2213] New: [STORY] Rework Web API

[bugzilla-daemon at icedtea.classpath.org]

http://icedtea.classpath.org/bugzilla/show_bug.cgi?id=2213

            Bug ID: 2213
           Summary: [STORY] Rework Web API
           Product: Thermostat
           Version: hg
          Hardware: x86_64
                OS: Linux
            Status: NEW
          Severity: enhancement
          Priority: P5
         Component: Thermostat
          Assignee: unassigned at icedtea.classpath.org
          Reporter: sgehwolf at redhat.com
                CC: thermostat at icedtea.classpath.org

The Web or HTTP API exposed by the web-endpoint in Thermostat 1.x series is
rather convoluted. It also makes performing authorization checks difficult.

Here is how the current API (roughly) works:

1. The web endpoint exposes an URL where WebStorage client post request to.
   For example http://host.example.com/thermostat/storage
   1.1. The following sub-paths are recognized:
          /prepare-statement
          /query-execute
          /write-execute
          /register-category
          /save-file
          /load-file
          /purge
          /ping
          /generate-token
          /verify-token
          /get-more
   1.2. Note that *all* queries enter via /query-execute and *all* writes enter
        via /write-execute
2. Some of the sub-URLs expect parameters in plain URL encoding only. Some
   sub-URLs expect parameter values to be in JSON serialized form and some use
   both variants, JSON serialized form and URL encoded text values.
3. What gets returned as a response is sometimes a JSON string and sometimes a
   plain URL encoded value.
4. Some sub-URLs add state to the end-point.

There are a couple of problems with this.

1. Query- and write-authorization is difficult, since there is no "path-based"
   access to resources. It would be easier if write/query endpoints are
   structured by a "path info" to the resource. This would allow for Servlet
   filter based authorization checks.
2. It's pretty verbose since only POST requests are recognized. By also using
   GET, DELETE and PUT, requests can be further segmented without extra
   path-info. See [1].
3. The format returned as a response isn't uniform. It should rather be
   in a format requested by the user (specified via a suffix or request
   attribute).
4. Authorization checks for save-file/load-file is difficult because no
   extra path-info is provided. This is somewhat similar to 1.

Possible solution(s):

Most (all?) thermostat resources are associated with (a) an agent or (b) a JVM
or (c) a host name (in a DNS A record sense). Since both, JVMs and Thermostat
agents can be identified uniquely it would make sense to segment resources by
either one of these. Everything that precedes an agent ID or JVM ID in
persistent storage is segmented by host name. Note that this might mean to have
a way to efficiently look-up more information about a JVM ID and/or an agent
ID. Other properties which can be derived from JVM IDs might be:
- *nix user name the JVM runs as
- PID of the JVM process
- some human-recognizable tag, such as "Apache-Tomcat-7",
  identifying a JVM or a group of JVMs
Similarly, properties which can be derived from agent IDs might be:
- host name where the agent runs (DNS A record)
- some human-recognizable tag, such as "Cloud-X-agents"

Examples. Consider a main storage URL of
http://new-thermostat-storage.example.com/storage. Then the API could look like
this:

POST /storage/<hostname>/numa (writes new numa record(s) to storage)
POST /storage/<hostname>/agents (writes new agent record(s) to storage)
GET  /storage/<hostname>/agents.json (gets all agents for his host name as
JSON)
PUT  /storage/<hostname>/agents/<agentId> (updates an existing agent record)
POST /storage/<agentID>/vms (writes new JVM record(s) to storage)
PUT  /storage/<agentID>/vms/<vmID> (updates an existing JVM record)
GET  /storage/<agentID>/vms.txt (get all JVMs for this agent as text)
POST /storage/<vmID>/threads (writes new thread record(s) for this JVM)
PUT  /storage/<vmID>/threads/<tid> (update a thread record for this JVM)
GET  /storage/<vmID>/files/<filename> (get the requested file for the JVM)

[1] https://en.wikipedia.org/wiki/Representational_state_transfer#Example

-- 
You are receiving this mail because:
You are the assignee for the bug.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/distro-pkg-dev/attachments/20150205/f520b03f/attachment-0001.html>