new rest2 webapp

As we transition to the new Hyland Community, some post links may be temporarily disrupted as we finalize redirects. We apologize for the inconvenience and are working to resolve this as quickly as possible. Details.

tombaeyens

Huh, what is the rest2 webapp?

we're trying out a new rest style.  one that gives us better control.  we're not that happy with the indirect steps of the template rendering.  lot of things need to be right in order for it to work and we believe it could be done simpler.
so we're now trying out a simple servlet approach and building JSONObjects in the servlet that get streamed to the client.

the api should be fairly stable now.  rest api is not yet as there is already legacy in the original rest api.  so we want to combine 2 steps in one:
1) make the rest impl simpler
2) review the rest calls and sync them with the api as it is stable now.

but there is no final decision on this servlet strategy yet.   we're still in try-out mode.

frederikherema1

There are 2 REST approaches we consider instead of using ftl-templates:

1) Using the existing spring surf webscripts, but replace the freemarker-templates with rendering done by a JSONObject, based on the model created in the existing ActivitiWebScript implementation which use the API.

Pros:
• Leveraging the rest-posibilities built in into spring surf to map url’s to java code
• Since we populate JSONObjects based on activiti domain model, it’s more easy to see where they are used (a simple Cmd+G will show where data is used), instead of templates which contain only text-references to these properties.
• Using existing WebScript implementations with some tweaks here and there.
• JSONObject generates valid JSON and escapes accordingly.

Cons:
• Dependency on spring-surf just to use rest-functionality


2) Create a custom REST servlet which handles the rest calls by delegating to the appropriate handlers, using JSONObject to create valid JSON output and stream it back to client. Large part of existing Webscript java code can be reused which calls activiti API.

Pros:
• No dependency at all, just plain old servlet spec
• Same advantages mentioned in 1) thanks to JSONObject (escaping + using domain model)

Cons:
• Creating parsing/delegating mechanism from scratch, which can takes a couple of days of development
•
________________________________________________________________________________________

Another thing we want to tackle is splitting up the REST-api in the folowing parts:

1) UI-independent REST, containing calls that map right onto the activiti java API, eg: Get list of deployments.

2) A single rest api for each of the UI’s we have (explorer, cycle, probe,…), since some rest methods are created for those. Examples:

• Get tasks summary. Returns number of tasks for all groups the user belongs to, assigned to him/her and unnasigned. This call is absolutely needed ion explorer to prevent calling a bunch of seperate rest-methods that contain too much data anyway. This is a valid usecase from a task/user oriented point of view, but isn’t really generic engine api stuff.

• Cycle-related rest calls, which also use cycle-related services/data which isn’t nessesairy always deployed alongside the activiti-rest-webapp.

The webapps (explorer, probe, cycle) will expose extra REST-services (if needed) in their own war. The spring surf services used in the components will use 2 rest-endpoints: the core api-rest and their own custom REST-services.

Only downside of this is that if other apps want to use the specific REST-services exposed this way by UI’s is that the UI webapp should be deployed to make use of the included rest-services. Offcourse, we can create seperate war for the UI-secific REST (eg. activiti-wabapp-cycle-rest), but we want to avoid a million war’s being deployed

When the custom REST is included in the cycle/explorer/probe the 'dependency on spring-surf' stated in the 'cons' of the first solution proposed in 'replace freemarker templates' are a non-issue.

___________________________________________________________

We want this change to be implemented in 3-4 months so we can provide the same backward-compatibility/stability guarantees on core rest api, as we do on the engine API.

To facillitate this, unit-tests should be added to test the rest api to signal that any engine refactorings may have broken rest API behaviour.

Major changes to rest-api after it’s marked “stable” (now it’s still marked as experimental) will use a deprecation-strategy. Depending whether or not the (deprecated) old rest service calls still work in future versions, they can be removed after being marked as deprecated after a certain amount of time.


Quite some material to read through above, some good lecture for a rainy sunday afternoon Please share any remarks, thoughts, suggestions or other solutions!!