Joomla needs a RESTful web services API.
It needs it badly because there is ever-increasing demand for content to be consumed across platforms and across devices. It is no longer enough to just publish content on a website and expect people to use a web browser to access it. Nowadays people want to consume content on smartphones, tablets and other devices, and they want to be able to connect information systems together to break out of the old content silos. Joomla as a content management system (CMS) needs to be more open to new methods of publishing content and we need to think beyond the traditional web CMS to embrace the full extent of our mission "to provide a flexible platform for digital publishing and collaboration".
But this isn't going to happen overnight. Since November 2012 I have been closely involved in the effort to add full web services support to Joomla. It wasn't until I had written the first draft of a specification for a Joomla web API that I began to realise the enormity of the undertaking. But it also served to underline for me the importance of building web services support into Joomla as soon as possible.
I want to see full web services support available in the Joomla 3.x series. With purely volunteer effort I think that might just be achieved in time for the Joomla 3.5 release in March 2014. Maybe. But I want to do it sooner. If this project is successfully funded I will work on this project full-time with the aim of getting comprehensive web services support into the Joomla 3.2 release in September this year.
Any funding beyond the target will go towards the stretch goals of making equivalent support available for Joomla 2.5 (with some caveats: it won't work on PHP 5.2 and it will need to be a separate download as it can't be included in the core distribution for 2.5) and whatever comes after Joomla 3.5 (Joomla 4.0 or "Jooma Next"). A common API across three series of the Joomla CMS; now that would be something!
Err, what is Joomla?
Joomla is one of the top 3 most popular web content management systems on the planet and it currently powers almost 3% of all the world's websites. It is an entirely community-driven project and does not employ any paid staff to work on its development. It is mostly written in PHP and is available for free under the GNU/GPL v2 or later license. You can find out more here: www.joomla.org.
What is an "API" and what are "web services"?
An API is an interface between one system and another; in this context it is a precisely defined way in which external systems, such as mobile devices and other data-processing systems, can read, create, update and even delete information in a Joomla site (subject to appropriate authorisation of course). The primary purpose of a web services API is to expose data and the functionality associated with that data as a collection of discrete services in such a way that client code does not need to know or care about how each service is implemented. Changes to a service implementation due to, say, architectural changes in the platform or the CMS, should not affect client code because of the isolation provided by the API.
Joomla has a well-established and vibrant community of extension developers, many of whom earn their living by writing and supporting code that extends Joomla's basic functionality. The web services implementation I want to build ensures that these third-party extension developers will be able to add web services support to their products with the minimum of effort and disruption. The architecture has been specifically designed to make this possible and I will work with the developer community to help them add web services support that is compliant with the standards brought forward by the Web Services Working Group. Silver Supporters and above will also get some dedicated consultancy time with me where they can pick my brains and I can help them with their particular projects in more detail.
Web Services Working Group
The WSWG is one of the Production Working Groups formed to act as focal points and to help organise development in particular areas of the Joomla project. The WSWG held an inaugural meeting at J and Beyond 2012 and has been building momentum ever since. You can find out more about the WSWG and keep abreast of its work here.
What has been done so far?
The WSWG has produced two drafts of a specification for web services in the Joomla CMS (links to the specification documents can be found on the WSWG page). Since then I have produced a proof-of-concept implementation of some of the important parts of the specification and published it on GitHub. You can download and test it at any time. Please read the README.md for instructions on how to get started with it. Feedback and especially pull requests are welcome!
You can also play with an online demonstration of the API. The entry point to the API is here. I would recommend browsing the API using the HAL Browser by starting here.
What about documentation?
The project will be fully and comprehensively documented, starting with the detailed API specifications which were mostly written by me anyway. I will add documentation specifically aimed at helping third-party developers understand how to add web services support to their extensions. I will also ensure that all DocBlocks within the code are completed and accurate.
The experience gained in developing the code for this project will also be fed back into making improvements to the web services API specification documents themselves.
I will be producing a comprehensive set of unit tests for all of the core code and indeed I want this project to become much more test-driven than it is right now. To help third-party extension developers I will also be building an online automated web API test tool that will check that each service end-point is in full compliance with the WSWG specifications. This tool will also be used to check the compliance of the core Joomla web services code that I will be developing for this project and it will ensure that regressions are spotted quickly during and after the project development period.
I will set up a dedicated website (running on Joomla of course!) for this project that will include news and continuous updates, together with special places and mentions for all sponsors. It will also include an online testing facility to allow third-party developers to test their software against the specification at any time. Access to this facility will be restricted to Bronze level or above sponsors of this project.
Since November 2012 I have been closely involved in the effort to add full web services support to the Joomla CMS. This was never going to be an easy or quick project to complete and I'll admit to having my doubts about whether it would see the light of day before the Joomla 4 cycle begins. But over the last year or so I have gradually come to the conclusion that web services is seriously important, not just for the future of Joomla, but for the web in general. So I set about learning as much as I could about web APIs and I began drawing up a specification of what I thought a web API should look like in Joomla.
The first draft of that specification was published on 24 December 2012 and was greeted with enthusiasm and much useful feedback. This resulted in an expanded second draft being published on 10 February 2013, after which I turned my attention to working out how it might actually be implemented in the Joomla 3.x series. I committed the first code to GitHub on 12 March 2013 and I've been gradually improving it ever since.
I find myself oddly well-placed to get this job done. Now all I need is time and since mortgages don't pay themselves and food does not magically appear whenever I, or my family need it, that means that I need money. And that's where you come in...
Help me to get web services support into Joomla 3.2 by pledging money now. Thank you.