v1 REST API - Part 1 - Introduction

cancel
Showing results for 
Search instead for 
Did you mean: 

v1 REST API - Part 1 - Introduction

gavincornwell
Senior Member
17 7 6,761

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.

api-explorer.png

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.

7 Comments
mitpatoliya
Established Member II

This is great Gavin Cornwell​. I have been using Swagger in one of my recent project and I could say based on my experience that it  will bring in lot of value. It will help a lot during integrations where back-end team can first create those API specification and once both teams agreed upon  specifications they could quickly generate skeleton for that API using swagger code gen.

gavincornwell
Senior Member

Thanks. Yes, it really helps drive the "API First" approach, which we're trying to adopt internally too.

davidcognite
Senior Member

"API First" is certainly the approach we're taking with new RM functionality. We're defining the Public v1 API in Swagger first, with discussions between UI and Server side engineers, then creating the model based on that. Should hopefully result in a thinner API layer that makes more sense to the UI and is easier for others to consume on it's own.

jego
Established Member

Is it possible to change the REST services implementation? Can you give some insight how the new REST API is implemented?

Thanks

Jens

gavincornwell
Senior Member

Hi Jens,

We have built an annotation based layer on top of webscripts to implement the new REST APIs. As such it is all Java based and currently does not provide any explicit public/supported extension points for APIs we're implementing. However, being annotation based it's definitely possible and fairly easy to add your own REST API implementations but that's not something we have documented yet.

We do understand that people have their favourite REST framework so we are working towards a set of "helper/utility" classes that can be leveraged from any backend to produce the consistently formatted responses we are returning.

I'm planning on doing another Tech Talk Live early next year so I'll be sure to try and cover a bit more about the annotations and extension approach.

Hope that answers your questions.

jego
Established Member

Thanks Gavin for the information.

M‌y guess is that a REST API of an ECM platform is only really helpful if it can be extended in a soft way, so e.g. including additional information into the response without overwriting internal implementations (to have no upgrade pain)

Thanks

Jens

gavincornwell
Senior Member

Yes, having a stable, consistent, backwards compatible REST API is very important to us.

We're more than happy to hear requirements of the sort of things you'd like to be able to do.