Repository: ipython/ipython

Issue:
IPython 3.0 breaks compatibility with emacs-ipython-notebook
Some more details in millejoh/emacs-ipython-notebook#4, but essentially emacs-ipython-notebook currently supports the REST protocol described in IPEP 16 and not IPEP 27. My primary concern is in supporting both IPython 2.0 and 3.0 as 3.0 adoption probably won't be instantaneous.

Is there a cross-version API for querying the version of IPython notebook? I am probably missing something obvious. Any other suggestions on how to support two different REST APIs (actually three, but I'm not planning on supporting IPython versions earlier than 2.0) in emacs-ipython-notebook greatly welcomed.

Also please permit me some old man grumbling for a moment - you guys are going to stick with the API specified in IPEP27 from now on, right? Or at least try in the future to make sure any changes are backwards-compatible? Chasing API's is certainly helping me learn a fair amount about IPython and ein, but it isn't exactly the most productive use of time.



Discussion:
Sorry about breaking things. The way the notebook frontend talks to the server wasn't designed to be a public API. I think EIN is the only consumer of it. As for supporting both IPython 2 and 3, I think the difference for saving notebooks is pretty small:
- url: `/api/notebooks/:path` -> `/api/contents/:path`
- model: add `format: 'json', type: 'notebook'`

We might be able to put a 302 redirect for /api/notebooks -> /api/contents. I think IPython 2 will safely ignore the extra keys, so if you POST IPython 3 models to /api/notebooks it might work on both IPython 2 and 3.

I don't know of any plans to change the REST API in the immediate future, but we do plan to eventually implement incremental save, rather than saving the notebook document in its entirety every time. I expect this will be a new API, and not necessarily a breaking change. I wouldn't expect it to happen soon, though.


Resolving patch:
diff --git a/IPython/html/services/contents/handlers.py b/IPython/html/services/contents/handlers.py
--- a/IPython/html/services/contents/handlers.py
+++ b/IPython/html/services/contents/handlers.py
@@ -270,6 +270,22 @@ def delete(self, path, name, checkpoint_id):
         self.set_status(204)
         self.finish()
 
+
+class NotebooksRedirectHandler(IPythonHandler):
+    """Redirect /api/notebooks to /api/contents"""
+    SUPPORTED_METHODS = ('GET', 'PUT', 'PATCH', 'POST', 'DELETE')
+
+    def get(self, path):
+        self.log.warn("/api/notebooks is deprecated, use /api/contents")
+        self.redirect(url_path_join(
+            self.base_url,
+            'api/contents',
+            path
+        ))
+
+    put = patch = post = delete = get
+
+
 #-----------------------------------------------------------------------------
 # URL to handler mappings
 #-----------------------------------------------------------------------------
@@ -283,4 +299,5 @@ def delete(self, path, name, checkpoint_id):
         ModifyCheckpointsHandler),
     (r"/api/contents%s" % file_path_regex, ContentsHandler),
     (r"/api/contents%s" % path_regex, ContentsHandler),
+    (r"/api/notebooks/?(.*)", NotebooksRedirectHandler),
 ]


Test patch: