We've been discussing REST APIs at Alfresco for a while now. If you haven't already seen Gavin Cornwell's Tech Talk Live session 'The Future of REST APIs' I highly recommend you check it out now.
It's hard to sum up Gavin's presentation, but the gist is that we are working on a new set of REST APIs that all follow a common set of guidelines. They are consistent, well tested, versioned which makes them extremely easy to consume. We call these 'the v1 REST APIs', however this concept is not new. We introduced the foundation for these APIs back in 4.2 along with our Cloud offering. The idea back then was to fill the missing features of CMIS so a combination of these APIs + CMIS would give you everything you need. These APIs have been documented in our official docs, however they were a bit hard to navigate and hard to consume.
This raises the question of how do we do API documentation in an efficient way. OpenAPI Specification (formerly known as Swagger) seems to do the trick in terms of describing our APIs. The cherry on the top is Swagger UI - a cool project that generates interactive documentation from an OpenAPI Specification - that even allows you to test out the APIs directly from the API Explorer.
We've put a lot of work into documenting our existing API's, which is what we're releasing today. The new 'v1 APIs' are now marked up with OpenAPI Specification (you can find the source here). We do realise that these API's don't look like much - but as mentioned above, the scope of the existing APIs was to fill the gap.
As we're adopting an 'API First' approach, we're also moving to a 'contract first' approach. This means that before we start coding any APIs we mock them up in OpenAPI Specifications, then have a review. Once the review is complete and we have ensured it conforms to our standards and guidelines we will start the work. We hope to see proposals for new APIs following this approach in the future.
We've made much progress on additional APIs, and we're continuing to invest heavily in stable, rich and powerful REST APIs this year. We already have a great set of APIs that cover file and folder operations, trashcan, renditions, live search, ticket authentication and site creation. We're adding new APIs every week and we're hoping to release a great set of APIs to community edition over the next couple of months.
We are working on a 'bleeding edge' version of the REST API Explorer - this will be a snapshot of the latest development. We hope this will be a great tool for our developer ecosystem to test the API's and provide feedback. We don't currently have a fixed date for the 'bleeding edge' version, but we will make sure to make some noise when it's ready. In case you can’t wait, you can clone the REST API Explorer source on GitHub and check out the “develop” branch. Run “mvn tomcat7:run-war” to get it up and running, however you will not be able to interact with the APIs.
You can find the online version of the REST API Explorer here: https://api-explorer.alfresco.com. It also comes bundled with the Alfresco SDK 2.2, be sure to check it out!
To report a bug please open an issue in the ALF project over at http://issues.alfresco.com, please set the “REST API” component if possible.
