v1 REST API - Part 1 - Introduction

[gavincornwell]

Alfresco has had a REST API for a long time but it organically grew over time as new services and capabilities were added. There were no guidelines defined which culminated in an inconsistent hard to use API.

This journey was covered in a Tech Talk Live earlier this year and in a presentation at BeeCon but there hasn't been much coverage of how to use the API, this is the first part of a series of blog posts that aim to introduce you to and provide hands-on experience of using the v1 REST API.

We believe a key requirement for a modern day REST API is an OpenAPI Specification (formerly known as Swagger). To provide as much value as possible we decided to manually generate the specification based on the endpoints available in 5.1. Given these hadn't changed since 4.2, customers would have a full specification of the v1 REST API independent of the Alfresco One product. Furthermore, this provides us with a strong API contract that we can use against the next release to ensure no regressions have crept into the product.

One benefit you gain from having an OpenAPI Specification for your API is the tooling support, most notably the Swagger UI. We used this to provide customers with the API Explorer​, an environment to allow you to experiment with APIs without having to install anything. A majority of the manually written reference documentation on docs.alfresco.com has also been replaced by the API Explorer.

At the moment the underlying repository is 5.1 so the live API Explorer does not show any of the new APIs added in the recent 5.2.b Early Access Community Release, providing access to all versions is something we're currently discussing. We are also contemplating how to release an API Explorer at the end of every sprint so you can keep track of progress in between releases.

In order to follow along with the forthcoming blog posts you'll need an environment to do so, firstly download and install the 5.2.b Early Access Community Release. We'll also be using the Postman client to execute the requests and providing them as a collection. Finally, to setup the API Explorer locally, download the WAR​, rename it to api-explorer.war and copy it to $ALF_HOME/tomcat/webapps.

Login to Share, go to the Manage Users page and create a user named "test" with a password "test".

In the https://community.alfresco.com/community/ecm/blog/2016/10/17/v1-rest-api-part-2-navigation we'll get started by looking at navigating the repository, in the meantime, start your server and have a look through the REST API documentation at http://localhost:8080/api-explorer.