Initially I had a large code base to study, and get familiar with the basic concepts of what we had up to that point, how and why it was built, and how we wanted to extend it. It was by itself a difficult task. It took me a while to, firstly, comprehend the big picture, get an intuition of the architecture, and then dive into the details. It was months later that I understood everything. And even this point I keep exploring it and discovering things in retrospect.
The API was initially built using a couple of open source packages. The combination of these packages, was indeed a very stable API framework. However it suffered from a few things, the most important of which was that the responses were often unpredictable. A very common case was the following:
Imagine an HTTP method like DELETE, on an API handler that doesn't allow that method. Depending on the resource that the request would try to access, the handler would yield either a 405 Method Not Allowed, or a 410 Gone response.
Wait a minute... If the handler doesn't even allow the method, why don't we always get a 405 Method Not Allowed?
Well, It had to do with an implementation detail of one of the tools we used, which was initially checking the existence of a resource, and then whether the HTTP method was allowed on the handler. So if for example the resource was inaccessible, a 410 Gone response was returned. If the resource was accessible, then a 405 Method Not Allowed response was returned.And this is only a single example of this behavior.
I did try to modify the internals of the API framework, and get it to behave more like I wanted it to. But I found it very difficult. There was a lot of monkey patching in the code, and a lot of long methods with multiple nested levels. It was just too much. For this reason I eventually decided to develop my own API framework, django-icetea. I had studied the behavior of the API frameworks I was already using, I knew the weaknesses, and I had a vision of what I needed.
It was simple. I needed an API framework that would be predictable. I needed an API framework that given a certain API handler, and a certain HTTP method, would have a very clear, intuitive behavior, and hence response, that I could reason about. The framework should make it easy for anyone who disagrees with the default behavior, to extend or modify it and tailor it down to his preferences.
For this reason, the code should be maintainable, clear and easy to study.
Whether it's RESTful, RESTless, REST-kind-of-sort-of, I don't really care. What I care about is being able to predict its behavior and built my application with that in mind and no unpleasant surprises. A predictable piece of software can be tested and verified. I can't even stress how important this is for any task.
PS. django-icetea is still under development, but already rock solid.