Lightning talk about the Alfresco Process Services REST API presented in 5 minutes at Alfresco DevCon 2018 in Lisbon

1. Alfresco Process Services
REST API
Dennis Koch

2. Learn. Connect. Collaborate.
Questions to be (hopefully) answered in 5 minutes
• Which REST APIs exist for APS?
• Why is the REST API so important?
• Who can access the REST API?
• Where can I get an overview of all available API calls?
• How do I use the API Explorer?
• How can I extend the REST API?

3. Learn. Connect. Collaborate.
Questions to be (hopefully) answered in 5 minutes
• Which REST APIs exist for APS?
• Why is the REST API so important?
• Who can access the REST API?
• Where can I get an overview of all available API calls?
• How do I use the API Explorer?
• How can I extend the REST API?

4. Learn. Connect. Collaborate.
Which REST APIs exist for APS?
• Activiti Engine REST API
• This API is part of the core Activiti engine used in APS
• API can be used temporary for migrations from Activiti Community to APS
• As APS has a slightly different permission concept than Activiti Community,
not all API calls will work with APS
• Documentation: https://www.activiti.org/userguide/index.html#_rest_api

5. Learn. Connect. Collaborate.
Which REST APIs exist for APS?
• Activiti Engine REST API
• This API is part of the core Activiti engine used in APS
• API can be used temporary for migrations from Activiti Community to APS
• As APS has a slightly different permission concept than Activiti Community,
not all API calls will work with APS
• Documentation: https://www.activiti.org/userguide/index.html#_rest_api
1

6. Learn. Connect. Collaborate.
Which REST APIs exist for APS?
• APS Internal REST API used for UI functions in activiti-app
• Calls are running under context /activiti-app/app/rest/
• As API calls are used in the UI, they require additional cookies, like CSRF
or ACTIVITI_REMEMBER_ME token that are stored server side per user
session
• Those API calls are undocumented as they are mainly used internally.
• One can activate the browsers network console and would see the calls
while browsing through the activiti-app UI

7. Learn. Connect. Collaborate.
Which REST APIs exist for APS?
• APS Internal REST API used for UI functions in activiti-app
• Calls are running under context /activiti-app/app/rest/
• As API calls are used in the UI, they require additional cookies, like CSRF
or ACTIVITI_REMEMBER_ME token that are stored server side per user
session
• Those API calls are undocumented as they are mainly used internally.
• One can activate the browsers network console and would see the calls
while browsing through the activiti-app UI

8. Learn. Connect. Collaborate.
Which REST APIs exist for APS?
• APS Public REST API as enterprise pendant to the engine API
• Recommended API to use when integrating APS with external systems
• Calls are running under context /activiti-app/api/enterprise/
• Documentation: https://docs.alfresco.com/process-
services1.7/topics/rest_api.html

9. Learn. Connect. Collaborate.
Why is the APS REST API so important?
• Integrate APS with existing systems using the REST API
• REST API can be used to build a customized UI on top of APS
• There are certain functionalities in APS that can only be reached via REST
API
2

10. Learn. Connect. Collaborate.
Why is the REST API so important?
• Alfresco Application Development Framework (ADF) makes use of the
REST API
Alfresco ADF Web Application
REST API REST API
APS ACS
ServiceLayer

11. Learn. Connect. Collaborate.
Who can access the REST API?
• Access to REST API is controlled on a per user/group base and so called
capabilities
• An Administrator can add users/groups to the “REST Access” capability.

12. Learn. Connect. Collaborate.
Who can access the REST API?
• Obviously, the REST API is enforcing the APS permission model
• i.e. a calling user will only see and can modify data he/she is allowed to
access
• If permissions are not correct, the REST response is giving 401 status
code with ACCESS_DENIED
• Administrators can impersonate other users if needed by using
Authorization header in the REST API call

13. Learn. Connect. Collaborate.
Where can I get an overview of all available calls?
• APS comes with an API Explorer as known from ACS
• API Explorer is based on swagger resources
• Available public REST API calls are grouped logically/functionally
• Per API call we list optional and required parameters, response codes,
sample responses and the response content type
• Accessed via http://host:port/activiti-app/api-explorer.html
3

14. Learn. Connect. Collaborate.
Where can I get an overview of all available calls?
• APS comes with an API Explorer as known from ACS
• API Explorer is based on swagger resources
• Available public REST API calls are grouped logically/functionally
• Per API call we list optional and required parameters, response codes,
sample responses and the response content type
• Accessed via http://host:port/activiti-app/api-explorer.html

15. Learn. Connect. Collaborate.
How to use the API-Explorer?
• Call the API Explorer and inspect the sections
Credentials
API Group

16. Learn. Connect. Collaborate.
How to use the API-Explorer?
• Simply click on a group to list all relevant API calls, e.g. expand the Admin
Tenants logical group
HTTP method URL Description

17. Learn. Connect. Collaborate.
How to use the API-Explorer?
• Select any call to review further details and hit the “Try it out”” button to
test the API call against your local APS deployment
• As a result you will see
– Produced curl command
– Request URL
– Request headers
– Response Body
– Response Code
– Response headers
4

18. Learn. Connect. Collaborate.
How can I extend the REST API?
• Internal API (using Cookies) and public API (using basic authentication)
can be extented
• Documentation: https://docs.alfresco.com/process-
services1.7/topics/custom_rest_endpoints.html
• To build against the REST logic of Process Services and its specific
dependencies, add following dependency to your Maven pom.xml file:

19. Learn. Connect. Collaborate.
How can I extend the internal REST API?
• A bean needs to be added to the com.activiti.extension.rest package

20. Learn. Connect. Collaborate.
How can I extend the public REST API?
• A bean needs to be added to the com.activiti.extension.api package

21. Learn. Connect. Collaborate.
How can I extend the REST API?
• Having added your custom logic, all you need to do is building an APS
extension library and placing it under activiti-app/WEB-INF/lib
• After a server restart, the custom API endpoint will be available and can
be called as defined
• For further information on how to build extensions using an APS extension
project, I recommend reviewing the slides to my lightning talk “APS
Extension Project”

22. Alfresco Process Services
REST API
Thank you!