REST: modify variables - POST or PATCH?

[thorben.lindhauer]

Hi everyone,

soon I am going to start work on the modfication and deletion of process instance variables via REST (see https://app.camunda.com/jira/browse/CAM-642)
The exciting question is now: How would we map that to URLs?

Option 1 - POST:
Requests would be POST /process-instance/{id}/variables/modify (some json body) and POST /process-instance/{id}/variables/delete (note that this cannot be a DELETE request, because we do not delete all variables).
However, this is less RESTful as modify and delete are no resources on their own, but actions to be executed.

Option 2 - PATCH:
HTTP PATCH was introduced after the standard verbs with exactly the intent to allow partial updates of a resource (PUT always exchanges an entire resource). See http://tools.ietf.org/html/rfc5789
The request would look like PATCH /process-instance/{id}/variables with a JSON request body containing deletions and modifications of variables.
This is in my opinion more RESTful, as variables is a resource. Of course, PATCH is not a "standard" HTTP verb, which is the crucial point for me in making this decision. I assume that it is no problem though for web servers we use, yet this would have to be tested.
Of course, existing URLs like /task/{id}/claim are also more RPC-like (and not RESTful), but claiming has way more side effects while updating instance variables is really an action bound to a single resource.

By the way, the Ruby on Rails people have decided to go with PATCH: http://weblog.rubyonrails.org/edge/
Salesforce API uses PATCH (http://www.salesforce.com/us/developer/docs/api_rest/Content/resources_sobject_retrieve.htm)

If you have any opinion, please let me know.

Thanks,
Thorben

[Rafael Cordones]

Hi Thorben,

soon I am going to start work on the modfication and deletion of process instance variables via REST (see https://app.camunda.com/jira/browse/CAM-642)
The exciting question is now: How would we map that to URLs?

My 2 cents:

IMHO, from a REST perspective, process variables should themselves be modelled as resources of a given process instance.

NOTE: the process instance has id fd04c6d5-c25a-11e2-b914-00236c89aee9 in the examples below.

List all process variables for a given process (already implemented):

Request: 

GET /engine-rest/process-instance/fd04c6d5-c25a-11e2-b914-00236c89aee9/variables

Response: 

HTTP/1.1 200 OK

{

   "variables":[

      {

         "name":"amount",

         "value":"30$",

         "type":"String"

      },

      {

         "name":"invoiceNumber",

         "value":"GPFE-23232323",

         "type":"String"

      },

      {

         "name":"creditor",

         "value":"Great Pizzas for Everyone Inc.",

         "type":"String"

      }

   ]

}

QUESTION: maybe it could be worth to add a "location" field to each of the entries above?

Like this:

{

   "variables":[

      {

         "name":"amount",

         "value":"30$",

         "type":"String",

         "location":"/engine-rest/process-instance/fd04c6d5-c25a-11e2-b914-00236c89aee9/variables/amount"

      },

      {

         "name":"invoiceNumber",

         "value":"GPFE-23232323",

         "type":"String",

         "location":"/engine-rest/process-instance/fd04c6d5-c25a-11e2-b914-00236c89aee9/variables/invoiceNumber"

      },

      {

         "name":"creditor",

         "value":"Great Pizzas for Everyone Inc.",

         "type":"String",

         "location":"/engine-rest/process-instance/fd04c6d5-c25a-11e2-b914-00236c89aee9/variables/creditor"

      }

   ]

}

Add a one process variable:

Request URL:

POST /engine-rest/process-instance/fd04c6d5-c25a-11e2-b914-00236c89aee9/variables

Request Body:

 {

    "name":"foo",

    "value":"42",

    "type":"String"

 }

Response:

HTTP/1.1 201 Created

...

Location /engine-rest/process-instance/fd04c6d5-c25a-11e2-b914-00236c89aee9/variables/foo

...

 {

    "name":"foo",

    "value":"42",

    "type":"String"

 }

Add a several process variables in one go:

QUESTION: is this even necessary?

Request URL:

POST /engine-rest/process-instance/fd04c6d5-c25a-11e2-b914-00236c89aee9/variables

Request Body:

{

   [

      {

         "name":"foo",

         "value":"42",

         "type":"String"

      },

      {

         "name":"bar",

         "value":"24",

         "type":"String"

      }

   ]

}

Get the value of a process variable:

Request URL:

GET /engine-rest/process-instance/fd04c6d5-c25a-11e2-b914-00236c89aee9/variables/amount

Response:

HTTP/1.1 200 OK

{

   "value":"30$",

   "type":"String"

}

Modify an existing process variable:

Request URL:

PUT /engine-rest/process-instance/fd04c6d5-c25a-11e2-b914-00236c89aee9/variables/amount

Request Body:

{

   "name":"amount",

   "value":"USD 30",

   "type":"String"

}

Response:

HTTP/1.1 200 OK

{

   "name":"amount",

   "value":"USD 30",

   "type":"String"

}

Delete an existing process variable:

Request URL:

DELETE /engine-rest/process-instance/fd04c6d5-c25a-11e2-b914-00236c89aee9/variables/amount

Response:

HTTP/1.1 204 No Content

Greetings from Vienna,

/rafa

--
You received this message because you are subscribed to the Google Groups "camunda BPM platform internal" group.
To unsubscribe from this group and stop receiving emails from it, send an email to camunda-bpm-d...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

--

http://plexiti.com

[Falko Menge]

@Thorben:
Do you have an overview of how far PATCH is adopted by the client
technologies that could be used with the REST API? If it is a verb that
only a few browsers or HTTP client libraries support, I would stick to
the standard verbs. I'd prefer maximum compatibility over proper naming.

@Rafael:
I like your proposal. We should just make sure that it doesn't become
too fine-grained, i.e., there should be batch operations for working
with multiple process variables in a single HTTP request.

[Christian Lipphardt]

I like your approach Rafael, maybe we should also return the old variable value when issuing a modifying put request? Like the java.util.Map.put() behaviour?

[Stefan Hentschel]

+1 for using a process variable as a resource and then using delete method
from rafa :)

Cheers,

Stefan

-- Java + BPM = http://www.camunda.org
-- Blog: http://www.bpm-guide.de <http://www.bpm-guide.de/>
---------------------------------------------
camunda services GmbH - The Business Process Company
Zossener Stra锟絜 55-58 - 10961 Berlin
www.camunda.com - in...@camunda.com
---------------------------------------------
Stefan Hentschel
Administrator
Telefon +49 30 664040 900
Mobil +49 176 32701090
stefan.h...@camunda.com
---------------------------------------------
Amtsgericht Charlottenburg: HRB 113230 B
Gesch锟絝tsf锟絟rer: Jakob Freund, Bernd R锟絚ker
---------------------------------------------
BPMN-2.0-Buch:
http://www.hanser-fachbuch.de/buch/Praxishandbuch+BPMN+20/9783446429864

EJB-3-Buch: http://www.ejbbuch.de/


-----Urspr锟絥gliche Nachricht-----
Von: camunda...@googlegroups.com
[mailto:camunda...@googlegroups.com] Im Auftrag von Falko Menge
Gesendet: Mittwoch, 22. Mai 2013 11:11
An: camunda...@googlegroups.com
Betreff: Re: REST: modify variables - POST or PATCH?

[thorben.lindhauer]

Hi,

thanks for your feedback!
@Rafael: I like your proposal and for interacting with single variables I would build it this way (one remark: adding a new variable and modifying a variable could be the same PUT-method).
The crucial question is, as you point out, is "bulk" update and delete needed? I'll talk to Robert as Product Owner about that tomorrow. If yes, deleting multiple variables would be the most interesting case for me, as DELETE is not suitable.

@Falko: Regarding compatibility of PATCH, you are right. We would have to check that before implementing.
From a very quick search I already found some problems with PATCH in a jQuery + IE8 setup.

@Christian: That's an interesting remark. Do you guys think there are use cases for this?

Best regards,
Thorben

[Daniel Meyer]

It should be possible to update or delete multiple process variables in a single, atomic request.

 

Daniel Meyer

Project Lead

www.camunda.org/community/team.html

[Bernd Rücker (camunda)]

I see the need at least for update. For deletion I think we even do not have it in the Java API – but for completeness it would be nice indeed :-)

--

[Bernd Rücker (camunda)]

Just checked the client i always used for demos and testing - no PATCH there – so maybe a bit risky (but agreed – that not an empiric proof ;-))?

 

 

-----Ursprüngliche Nachricht-----
Von: camunda...@googlegroups.com [mailto:camunda...@googlegroups.com] Im Auftrag von Falko Menge

Gesendet: Mittwoch, 22. Mai 2013 11:11
An: camunda...@googlegroups.com

Betreff: Re: REST: modify variables - POST or PATCH?

--

[thorben.lindhauer]

Hi,

I have been discussing this issue with Daniel this morning. We came to the conclusion that the PATCH-solution is nicer from a REST point of view (together with Rafa's proposal for interacting with single variables).
So PATCH /process-instance/{id}/variables would be the corresponding URL.

We were also thinking about adding a POST request later on that does the exact same thing, in case users should have problems with PATCH. URL could then be POST /process-instance/{id}/modifyVariables

Regarding compatibility: I have just written a very simple JAX-RS application with Resteasy and Maven Tomcat Plugin that exposes a PATCH method.
Client side is plain jquery. Find the sources here: https://github.com/ThorbenLindhauer/http_patch_check
Results: No problems in Firefox and IE9, IE 7 and 8 won't work. Daniel and I agreed on IE support from 9 onwards, so this should be fine.

On client side, PATCH should also be fine with angular.js, as they state PATCH support in their changelogs: https://github.com/angular/angular.js/blob/master/CHANGELOG.md#v100rc6-runny-nose-2012-04-20

Best regards,
Thorben

[Thorben Lindhauer]

Quick follow-up: Here are the docs for the new method: https://github.com/camunda/docs.camunda.org/blob/e21758b6f1343ffbc84b15ad2bc7db0a6f7a0b35/site/src/documents/api-references/rest/process-instance/patch-variables.html.md

----- Ursprüngliche Mail -----
Von: "thorben.lindhauer" <thorben....@camunda.com>
An: camunda...@googlegroups.com
CC: "Falko Menge" <falko...@camunda.com>
Gesendet: Donnerstag, 23. Mai 2013 14:47:39

Betreff: Re: REST: modify variables - POST or PATCH?

[Rafael Cordones]

Hi Thorben,

Please, read my below comments as coming from someone in the camunda BPM community who cares about the future of the camunda BPM platform.

On Thursday, May 23, 2013 at 2:47 PM, thorben.lindhauer wrote:

Hi,

I have been discussing this issue with Daniel this morning. We came to the conclusion that the PATCH-solution is nicer from a REST point of view (together with Rafa's proposal for interacting with single variables).
So PATCH /process-instance/{id}/variables would be the corresponding URL.

When I read "the PATCH-solution is nicer from a REST point of view" my software developer alarm goes off. 

As a developer, I prefer solutions that are nicer from my point of view! 

We were also thinking about adding a POST request later on that does the exact same thing, in case users should have problems with PATCH. URL could then be POST /process-instance/{id}/modifyVariables

Don't get me wrong, I'm not trying to put up a fight here but I had to google for the "PATCH" verb since it was the first time I heard about it.

I expect this to be the case for many developers who want to develop a client to the camunda BPM REST API. So the question here is whether we support the way most developers are used to 'talk' to a REST API or not. IMHO, supporting PATCH should be a nice surprise and not the other way around.

Regarding compatibility: I have just written a very simple JAX-RS application with Resteasy and Maven Tomcat Plugin that exposes a PATCH method.
Client side is plain jquery. Find the sources here: https://github.com/ThorbenLindhauer/http_patch_check
Results: No problems in Firefox and IE9, IE 7 and 8 won't work. Daniel and I agreed on IE support from 9 onwards, so this should be fine.

If my current (limited) understanding of PATCH is correct, in a more real-world scenario, to use PATCH, as a developer I would have to build a diff document to send to the camunda BPM REST API as the body of the PATCH request, am I right?

The http_patch_check only checks whether a request can be made:

https://github.com/ThorbenLindhauer/http_patch_check/blob/master/src/main/webapp/js/test-patch.js

On client side, PATCH should also be fine with angular.js, as they state PATCH support in their changelogs: https://github.com/angular/angular.js/blob/master/CHANGELOG.md#v100rc6-runny-nose-2012-04-20

IMHO using jQuery to see whether PATCH is supported is too low level. I would rather check which level of support for PATCH is provided out-of-the-box by higher level frameworks and starting at which version: AngularJS, Spring's RestTemplate, …, PHP-client libraries, ...

And in order to check for support I would not look at release notes or CHANGELOGs, I would check the actual developer documentation available to a developer that she will use to get her work done: http://docs.angularjs.org/api/ngResource.$resource

How do other projects that need to provide similar functionality via REST do what we want to do?

Greetings from Vienna,

/rafa

[Daniel Meyer]

Hi,

Just to make sure everyone is up to date with the current state of affairs:

already, you can GET/PUT/DELETE individual process variables:

http://stage.docs.camunda.org/api-references/rest/#!/process-instance/get-single-variable

http://stage.docs.camunda.org/api-references/rest/#!/process-instance/put-single-variable

http://stage.docs.camunda.org/api-references/rest/#!/process-instance/delete-single-variable

If you want to do a composite operation including multiple variables you have to use PATCH.

http://stage.docs.camunda.org/api-references/rest/#!/process-instance/patch-variables

Now the question is whether to additionally include a POST-based operation for composite operations on multiple variables.

Cheers,

Daniel

[Andreas Drobisch]

Hi all,
generally agree with Raphael here. My 2 cents:

The original "POST less RESTful" was a bit blurry because the OP "Option
1" was a bad proposal in the first place, as you were encoding the
meaning of HTTP verbs into the URI.

Assuming variables is the resource:

GETing /process-instance/{id}/variables means were are getting the
variables resource representation. Changing it (in this case the JSON
representation) and PUTing it back means were are updating the resource,
so variable entries that are not in the changed representation anymore
should be deleted (matches the idempotent semantic). POSTing to same url
means we are changing its state in some way, so imho posting a partial
update is inline with the definition:

"POST is designed to allow a uniform method to cover the following
functions:
- Annotation of existing resources;
- Posting a message to a bulletin board, newsgroup, mailing list,
or similar group of articles;
- Providing a block of data, such as the result of submitting a
form, to a data-handling process;
- Extending a database through an append operation."

(http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html)

A custom media type could specify in detail "what" is changing. But you
can make the JSON assumption here as well.

So what I miss in this discussion is WHY POST is "less restful". Sounds
a bit sketchy to me, especially with the client support issues.

Best Regards,
Andreas

On 27.05.2013 08:27, Rafael Cordones wrote:
> Hi Thorben,
>
> Please, read my below comments as coming from someone in the camunda BPM
> community who cares about the future of the camunda BPM platform.
>
> On Thursday, May 23, 2013 at 2:47 PM, thorben.lindhauer wrote:
>
>> Hi,
>>
>> I have been discussing this issue with Daniel this morning. We came to

>> the conclusion that *the PATCH-solution is nicer from a REST point of
>> view* (together with Rafa's proposal for interacting with single

>> variables).
>> So PATCH /process-instance/{id}/variables would be the corresponding URL.

> When I read /"the PATCH-solution is nicer from a REST point of view"/ my

> software developer alarm goes off.
> As a developer, I prefer solutions that are nicer from my point of view!
>> We were also thinking about adding a POST request later on that does

>> the exact same thing, *in case users should have problems with PATCH*.

> *out-of-the-box* by higher level frameworks *and starting at which
> version:* AngularJS
> <http://docs.angularjs.org/api/ngResource.$resource>, Spring's
> RestTemplate
> <http://blog.springsource.org/2009/03/27/rest-in-spring-3-resttemplate/>, �,

> PHP-client libraries, ...
> And in order to check for support I would not look at release notes or
> CHANGELOGs, I would check the actual developer documentation available
> to a developer that she will use to get her work done:
> http://docs.angularjs.org/api/ngResource.$resource
>
> How do other projects that need to provide similar functionality via
> REST do what we want to do?
>
> Greetings from Vienna,
>
> /rafa
>

> --
> You received this message because you are subscribed to the Google
> Groups "camunda BPM platform internal" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to camunda-bpm-d...@googlegroups.com.
> For more options, visit https://groups.google.com/groups/opt_out.
>
>

--
---------------------------------------------
BPM with Java: camunda bpm
www.camunda.org

---------------------------------------------
camunda services GmbH - The Business Process Company

Zossener Str. 55-58 � 10961 Berlin

www.camunda.com - in...@camunda.com

---------------------------------------------

Andreas Drobisch

Technical Consultant

Telefon: +49 30 664 04 09 - 00
Fax: +49 30 664 04 09 - 29

andreas....@camunda.com

---------------------------------------------

Amtsgericht Charlottenburg: HRB 113230 B

Gesch�ftsf�hrer: Jakob Freund, Bernd R�cker

[Thorben Lindhauer]

Hi Andreas,

the issue I have with POST from a REST perspective are the sentences surrounding your quote from the HTTP spec, namely:

"The POST method is used to request that the origin server accept the entity enclosed in the request as a new subordinate of the resource identified by the Request-URI in the Request-Line."

and

"The posted entity is subordinate to that URI in the same way that a file is subordinate to a directory containing it, a news article is subordinate to a newsgroup to which it is posted, or a record is subordinate to a database."

So I would expect a POST to /instance/{id}/variables to create a new (single) variable and not just change "some" state of variables.

However, the PATCH RFC says:

"A comparison to POST is even more difficult, because POST is used in widely varying ways and can encompass PUT and PATCH-like operations if the server chooses."

So it seems ok to use POST, but it is less clear.
I believe that we should not stick to PATCH only and perhaps offer the same request also as POST.

Cheers,
Thorben

----- Ursprüngliche Mail -----
Von: "Andreas Drobisch" <andreas....@camunda.com>
An: "Rafael Cordones" <rafael....@plexiti.com>
CC: "thorben.lindhauer" <thorben....@camunda.com>, camunda...@googlegroups.com, "Falko Menge" <falko...@camunda.com>
Gesendet: Montag, 27. Mai 2013 12:16:51

Betreff: Re: REST: modify variables - POST or PATCH?

> <http://blog.springsource.org/2009/03/27/rest-in-spring-3-resttemplate/>, …,

> PHP-client libraries, ...
> And in order to check for support I would not look at release notes or
> CHANGELOGs, I would check the actual developer documentation available
> to a developer that she will use to get her work done:
> http://docs.angularjs.org/api/ngResource.$resource
>
> How do other projects that need to provide similar functionality via
> REST do what we want to do?
>
> Greetings from Vienna,
>
> /rafa
>
> --
> You received this message because you are subscribed to the Google
> Groups "camunda BPM platform internal" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to camunda-bpm-d...@googlegroups.com.
> For more options, visit https://groups.google.com/groups/opt_out.
>
>

--
---------------------------------------------
BPM with Java: camunda bpm
www.camunda.org

---------------------------------------------
camunda services GmbH - The Business Process Company

Zossener Str. 55-58 – 10961 Berlin

www.camunda.com - in...@camunda.com

---------------------------------------------

Andreas Drobisch

Technical Consultant

Telefon: +49 30 664 04 09 - 00
Fax: +49 30 664 04 09 - 29

andreas....@camunda.com

---------------------------------------------

Amtsgericht Charlottenburg: HRB 113230 B

Geschäftsführer: Jakob Freund, Bernd Rücker

[Andreas Drobisch]

On 27.05.2013 13:16, Thorben Lindhauer wrote:
> Hi Andreas,
>
> the issue I have with POST from a REST perspective are the sentences surrounding your quote from the HTTP spec, namely:
>
> "The POST method is used to request that the origin server accept the entity enclosed in the request as a new subordinate of the resource identified by the Request-URI in the Request-Line."
>
> and
>
> "The posted entity is subordinate to that URI in the same way that a file is subordinate to a directory containing it, a news article is subordinate to a newsgroup to which it is posted, or a record is subordinate to a database."
>
> So I would expect a POST to /instance/{id}/variables to create a new (single) variable and not just change "some" state of variables.

As we already have the variable as sub-resource, posting a list of
variables to the variables(-list) resource matches the "subordinate"
definition very well. Imho POST = CREATE is a very CRUD based view on
the API.

There is a nice article on that:
http://jcalcote.wordpress.com/2008/10/16/put-or-post-the-rest-of-the-story/

Cheers,
Andreas

[Daniel Meyer]

Hi Guys (Andreas, Thorben, Rafa ...),

I wrote:

If you want to do a composite operation including multiple variables you have to use PATCH.

http://stage.docs.camunda.org/api-references/rest/#!/process-instance/patch-variables

Now the question is whether to additionally include a POST-based operation for composite operations on multiple variables.

Based on the discussion: would you now answer this question with "YES"?

If true: 

- Whould it include both ADDING and DELETING multiple variables in a single Request?

- What would that method look like and which Verb does it use?

Remember: you can already do all this for single variables, one variable at a time.

Cheers,

Daniel

[thorben.lindhauer]

Ok, so if I get this right, we could replace PATCH with POST and keep the current request body format.
In case we also wanted to provide a "POST create single resource method" that returns a nice Location header etc. (which we don't need here; just for my understanding) we would differentiate the two methods by the media type, right?
Sounds fine for me. I would then update this accordingly before the next alpha release.

Best regards,
Thorben