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.

No need to apologize! It's nothing more than the inevitable price of progress. Keeping the API stable will make maintaining EIN easier for me, but sometimes you have to break things before they can become more awesome.

From your comment and a quick perusal of IPEP 27 I think getting EIN to work with IPython 3 will be much easier than getting it to work with IPython 2. I don't see a need to add a redirect as you suggest, rather I would like to have a URL I can query to get the current 'version' of the REST API. Something like "api/version". That is probably simple enough that even I, enfeebled coder that I am, could probably great pull requests for IPython 2.x and 3.0 code bases. Good learning opportunity in any case.

Thanks for the response!

-----Original Message-----
From: "Min RK" notifications@github.com
Sent: ‎10/‎7/‎2014 11:59 PM
To: "ipython/ipython" ipython@noreply.github.com
Cc: "John Miller" millejoh@mac.com
Subject: Re: [ipython] IPython 3.0 breaks compatibility withemacs-ipython-notebook (#6647)

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.
—
Reply to this email directly or view it on GitHub.=


Resolving patch:
diff --git a/IPython/html/base/handlers.py b/IPython/html/base/handlers.py
--- a/IPython/html/base/handlers.py
+++ b/IPython/html/base/handlers.py
@@ -24,6 +24,8 @@
 except ImportError:
     app_log = logging.getLogger()
 
+import IPython
+
 from IPython.config import Application
 from IPython.utils.path import filefind
 from IPython.utils.py3compat import string_types
@@ -398,6 +400,13 @@ def validate_absolute_path(self, root, absolute_path):
         return super(FileFindHandler, self).validate_absolute_path(root, absolute_path)
 
 
+class ApiVersionHandler(IPythonHandler):
+
+    @json_errors
+    def get(self):
+        # not authenticated, so give as few info as possible
+        self.finish(json.dumps({"version":IPython.__version__}))
+
 class TrailingSlashHandler(web.RequestHandler):
     """Simple redirect handler that strips trailing slashes
     
@@ -456,5 +465,6 @@ def get(self, path=''):
 
 
 default_handlers = [
-    (r".*/", TrailingSlashHandler)
+    (r".*/", TrailingSlashHandler),
+    (r"api", ApiVersionHandler)
 ]


Test patch: