Sessions API - previously Session Restore API. Supports restoring currently open foreign windows an…

chrome/common/extensions/api/sessions.json

Index: chrome/common/extensions/api/sessions.json
diff --git a/chrome/common/extensions/api/session_restore.json b/chrome/common/extensions/api/sessions.json
similarity index 33%
rename from chrome/common/extensions/api/session_restore.json
rename to chrome/common/extensions/api/sessions.json
index e44a59cab9d0527c44cdabd6065c6482cde5cb8f..c664566662740ddf24d1cd1998ae3431c022fe29 100644
--- a/chrome/common/extensions/api/session_restore.json
+++ b/chrome/common/extensions/api/sessions.json
@@ -4,17 +4,24 @@
 
 [
   {
-    "namespace": "sessionRestore",
-    "description": "Use the <code>chrome.sessionRestore</code> API to query and restore tabs and windows from a browsing session.",
+    "namespace": "sessions",
+    "description": "Use the <code>chrome.sessions</code> API to query and restore tabs and windows from a browsing session.",
     "types": [
       {
-        "id": "ClosedEntry",
+        "id": "Session",
         "type": "object",
         "properties": {
-          "id": {"type": "integer", "minimum": 0, "description": "The ID of the browser session."},
-          "timestamp": {"type": "integer", "description": "The time when the window or tab was closed, represented in milliseconds since the epoch"},
-          "tab": {"$ref": "tabs.Tab", "optional": true, "description": "The closed $ref:tabs.Tab, if this entry describes a tab. Either this or $ref:ClosedEntry.window will be set."},
-          "window": {"$ref": "windows.Window", "optional": true, "description": "The closed $ref:windows.Window, if this entry describes a window. Either this or $ref:ClosedEntry.tab will be set."}
+          "lastModified": {"type": "integer", "description": "The time when the window or tab was closed, represented in milliseconds since the epoch"},
+          "tab": {"$ref": "tabs.Tab", "optional": true, "description": "The closed $ref:tabs.Tab, if this entry describes a tab. Either this or $ref:Session.window will be set."},
+          "window": {"$ref": "windows.Window", "optional": true, "description": "The closed $ref:windows.Window, if this entry describes a window. Either this or $ref:Session.tab will be set."}
+        }
+      },
+      {
+        "id": "Device",
+        "type": "object",
+        "properties": {
+          "info": {"type": "string", "description": "Represents all information about a foreign device."},
+          "sessions": {"type": "array", "items": {"$ref": "Session"}, "description": "A list of open window sessions for the foreign device, sorted in order from most recently to least recently modified session. The number of sessions is equivalent to the number of windows open on the foreign device."}

[not at google - send to devlin, 2013/08/12 23:51:34]

"sorted in order" is a tautology.

By "something about the number" I meant like, how many sessions can there be,
etc.

[Kristen Dwan, 2013/08/15 07:11:56]

so ... there is no limit on the number of sessions returned. we should probably
set one. i haven't seen any sort of cap in chrome backend - other than sessions
become stale after 14 days.

         }
       }
     ],
@@ -49,7 +56,37 @@
             "name": "callback",
             "parameters": [
               {
-                "name": "entries", "type": "array", "items": { "$ref": "ClosedEntry" }, "description": "The list of closed entries in reverse order that they were closed (the most recently closed tab or window will be at index <code>0</code>). If <code>entryType</code> is specified the entries will be only of that type, otherwise the entries may contain either tabs or windows.List of $ref:ClosedEntry representing the closed tab/window for the session."
+                "name": "sessions", "type": "array", "items": { "$ref": "Session" }, "description": "The list of closed entries in reverse order that they were closed (the most recently closed tab or window will be at index <code>0</code>). If <code>entryType</code> is specified the entries will be only of that type, otherwise the entries may contain either tabs or windows.List of $ref:Session representing the closed tab/window for the session."
+              }
+            ]
+          }
+        ]
+      },
+      {
+        "name": "getDevices",
+        "type": "function",
+        "description": "Retrieves all synced sessions and returns in sorted order from device with most recently modified session to device with least recently modified session, and within each device by most recent to least recently modified session.",
+        "parameters": [
+          {
+            "type": "object",
+            "name": "options",
+            "optional": true,
+            "properties": {
+              "maxResults": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 10,
+                "optional": true,
+                "description": "The maximum number of foreign devices to be fetched in the requested list. Omit to fetch the maximum number of devices (10)."

[not at google - send to devlin, 2013/08/12 23:51:34]

oh right. This comment confused me and it's because the API confuses me.

What does maximum mean here? Does it mean the maximum number of devices? The
maximum number of sessions per device? The total maximum number of sessions?

I presume it's the second of those, but the comment needs to make that clear.

And we need to make sure the implementation does that.

[Kristen Dwan, 2013/08/15 07:11:56]

nope, it's the maximum number of devices that can be returned -- as in the max
possible length of the Device[] devices. which .... basically no one has 10
synced devices.

but it gets weird since in the backend a "session" is what we call a
"sessions.Device" .. and each "sessions.Device.sessions" is a single window or
tab that is contained in the backend "session".. basically in the backend
session means full device but in the exposure of the api the term session means
a single "browsing session" as in a single window or tab.

[not at google - send to devlin, 2013/08/15 20:16:24]

Ok. Having a limit on the number of devices doesn't make sense since it's a
finite amount of data (even if chances are nobody has 10 devices).

The history of sessions isn't finite though; that's what I'd expect us to be
limiting. 14 days worth of history is going to be pretty pretty enormous, so,
I'd like to add something for that - in the same way that getRecentlyClosed
does.

In fact I think we may even want to define a general "filter" object and use
that for both here and getRecentlyClosed. Maximum results (defaulting to 25,
sure), type of session (for foreign presumably it'll just always be window?), in
the future if people request it we could also have a time limit rather than a
volume limit.

[Kristen Dwan, 2013/08/16 22:03:06]

it's 14 days but the tabs / windows also have to *currently* be open. so it's
saying they'll be pruned if you leave 80 tabs sitting open for over 14 days,
they'll no longer show up. Closed tabs / windows do not apply and will not be
returned. so it really shouldn't be that enormous... unless you leave tons and
tons of sessions open.

Having a general filter object sounds like a good plan to me. although, how will
we specify that when using the filter for getDevices it will always be window
even if the user specifies tab.. 

+              }
+            }
+          },
+          {
+            "type": "function",
+            "name": "callback",
+            "parameters": [
+              {
+                "name": "devices", "type": "array", "items": { "$ref": "Device" }, "description": "The list of $ref:Device objects for each synced session, sorted in order from device with most recently modified session to device with least recently modified session."
               }
             ]
           }
@@ -58,10 +95,26 @@
       {
         "name": "restore",
         "type": "function",
-        "description": "Reopens a $ref:ClosedEntry, with an optional callback to run when the entry has been restored.",
+        "description": "Reopens a $ref:Session, $ref:windows.Window, or $ref:tabs.Tab, with an optional callback to run when the entry has been restored.",
         "parameters": [
-          {"type": "integer", "name": "id", "optional": true, "description": "The id of the $ref:ClosedEntry to restore."},
-          {"type": "function", "name": "callback", "optional": true, "parameters": []}
+          {
+            "type": "string",
+            "name": "sessionId",
+            "optional": true,
+            "description": "The $ref:windows.Window.sessionId, or $ref:tabs.Tab.sessionId to restore."
+          },
+          {
+            "type": "function",
+            "name": "callback",
+            "optional": true,
+            "parameters": [
+              {
+                "$ref": "Session",
+                "name": "restoredSession",
+                "description": "A $ref:Session containing the restored $ref:windows.Window or $ref:tabs.Tab object."
+              }
+            ]
+          }
         ]
       }
     ]