There's not really any documentation about the plugin API and I have read that it is somewhat unstable. But I wanted to know what all limitations are there to the API, what should not be done using the API and what parts of the code are not exposed to it. I've also read that from 5.0 several improvements have been made, does that mean that the API will be able to do more in the recent future or are is it about making the existing features more stable ?
It is about making the existing features more stable. In 2.x you build stuff with guice so you can do just about anything but it isn't clear what you should do. There are lots of things you could do that would make things unstable.
In 5.0 it is getting better. We're switching from guice based registration to Elasticsearch calling the plugin to build the various customizations and providing arguments that make sense. In lots of cases that is no arguments at all. So, for example, if you implement a new analyzer you implement AnalysisPlugin and getAnalyzers and return a map of name -> factory.
As to the question in your title, what is it you want to do? In 5.0 that are ingest pipelines which make changes to the source. There is also mappers and the analysis stuff which changes how the source is indexed and stored.
I made some changes to SearchPhaseController and the QueryPhase classes and now if the rest end point that I have defined is called, I want my overriden methods to be called while the rest of the search process stays the same. Is this something that would be possible through the plugin API in 2.x or even 5.0 ?