View source for Documentation:OCLOperators RestPatch

You can use HTTP PATCH to update selected fields of an object exposed through an MDriven ViewModel REST endpoint; this page is for developers calling or designing that endpoint.
== RestPatch is not an OCL operator ==
Despite this page's placement among OCL operator pages, '''RestPatch''' is not a standard [[Documentation:Learn OCL|OCL]] or [[Documentation:EAL|Executable Action Language]] (EAL) command. It describes the REST convention of sending an HTTP <code>PATCH</code> request to change part of an existing resource.

For example, a client can change a profile's phone number without resending its name and email address. The fields omitted from the PATCH request remain unchanged.

For the general REST PATCH concept and an HTTP request example, see [[Documentation:Rest Patch]].
== How partial updates work ==
A PATCH request identifies an existing object and sends only the field values that should change.

{| class="wikitable"
! Request content
! Result
|-
| <code>phoneNumber = "555-1234"</code>
| Updates the phone number only.
|-
| Name, email, and other fields are not included
| Those fields are left unchanged.
|}

This differs from a complete-representation update. Use [[Documentation:OCLOperators RestPut|RestPut]] when you need to send a complete data structure to a remote URL.
== Expose a ViewModel for REST access ==
MDriven exposes REST access through a [[Documentation:ViewModel|ViewModel]]. Configure the ViewModel that represents the data you intend to expose.

# Open the ViewModel in MDriven Designer.
# Set the ViewModel's class to the domain class whose instances the endpoint will work with. For example, an <code>ArticleViewModel</code> can be rooted in an <code>Articles1</code> domain class.
# Add the attributes that clients must be able to read or update. Use direct expressions for fields intended for straightforward updates. For example, use <code>self.title</code> for a title field.
# Open '''Tagged values''' in the ViewModel Editor.
# Add the <code>Eco.RestAllowed</code> tagged value and set it to <code>True</code>.
# Run the application and call the ViewModel's REST URL.

The <code>RestAllowed</code> tagged value is required to allow REST access to a ViewModel. Without it, REST operations are not available for that ViewModel. For the wider REST-service setup and calls made from within a ViewModel, see [[Documentation:Rest Services In MDriven]].

Once the app is running, your endpoint becomes available at the REST path.
Once the app is running, your endpoint is available at:
 <code>http://<host>/Rest/<ViewModelName>/</code>
For the <code>ArticleViewModel</code> example:
 <code><nowiki>http://localhost:8182/Rest/ArticleViewModel/</nowiki></code>
From here you can perform REST operations  see the '''RestPatch''' section above for how to update objects via this endpoint.
=== Choose direct field expressions ===
A ViewModel field can be based on a calculated expression, but the REST response represents the ViewModel field value rather than necessarily exposing the raw stored attribute.

For example:

<syntaxhighlight lang="ocl">
title      : self.title
authorText : 'By ' + self.author
</syntaxhighlight>

If a client updates <code>title</code>, a direct expression such as <code>self.title</code> provides a clear mapping to the underlying attribute. A calculated field such as <code>authorText</code> returns its calculated display value, <code>By ...</code>. Design the ViewModel fields deliberately so that the values clients send and receive have the meaning you expect.
== Endpoint and object identification ==
A REST-enabled ViewModel is available under the REST path for its ViewModel name. A PATCH call targets a specific existing object by its MDriven object ID.

<syntaxhighlight lang="text">
http://<host>/Rest/<ViewModelName>/Patch?id=<objectId>
</syntaxhighlight>

For example:

<syntaxhighlight lang="text">
http://localhost:8182/Rest/ArticleViewModel/Patch?id=3!396
</syntaxhighlight>

The object ID <code>3!396</code> consists of the class ID and instance ID. The current endpoint form may also place the object ID in the path:

<syntaxhighlight lang="text">
http://localhost:8182/Rest/ArticleViewModel/Patch/3!396
</syntaxhighlight>
== Send the fields to change ==
Send the fields to update as key-value pairs in the request body. Include multiple pairs when you need to update multiple fields in one request.

For example, to change an article title, send a <code>title</code> value of <code>Updated Title</code>. To change both title and content, send both <code>title</code> and <code>content</code>. Do not include fields that must remain unchanged.
== Response ==
A successful PATCH request returns <code>200 OK</code> and the updated ViewModel object as JSON.

The response reflects the value defined by the ViewModel expression. For example, when a field uses a calculated expression, the response contains the calculated value rather than an unformatted stored value. This is expected: the ViewModel controls the representation returned to the client.

'''Example response:'''
[[File:Documentation OCLOperators RestPatch 1772275417875.png|thumb|753x753px]]
== Calling other REST services from MDriven ==
When your requirement is to call an external REST service from a ViewModel action, use the REST-related EAL commands on <code>selfVM</code>, not a RestPatch operator. For example, [[Documentation:OCLOperators RestGet|RestGet]] performs a GET request, while [[Documentation:OCLOperators RestPut|RestPut]] sends a complete representation to a remote URL. See [[Documentation:Rest Services In MDriven]] for the available REST service operations and their ViewModel context.
=== Step 3: Add Your Fields ===

Example ViewModel configuration exposing article fields:
Add the attributes you want to expose as columns inside the ViewModel. For example:
[[File:Documentation OCLOperators RestPatch 1772276363022.png|thumb|300x300px]]
 <title       : self.title
 publishedAt : self.publishedAt
 content     : self.content
 author      : 'By ' + self.author
 urlToImage  : self.urlToImage
 source      : 'From: ' + self.source.name</code>
<blockquote>'''Note:''' If a field uses a computed OCL expression like <code>'By ' + self.author</code>, the REST response will return the computed value, not the raw stored value. Keep fields as direct mappings like <code>self.title</code> if you want clean PATCH behaviour.

=== Step 4: Enable Eco.RestAllowed via Tagged Values ===

Enable REST access by adding required tagged values to the ViewModel.
# Click '''Tagged values''' in the top-right of the ViewModel Editor
# In the '''Tagged Values''' dialog, you will see a '''Value Store''' at the bottom listing all available tags
# Add the following tags by selecting them and clicking '''Add This''':[[File:Documentation OCLOperators RestPatch 1772276305223.png|thumb|339x339px]]

== See also ==
* [[Documentation:Rest Patch]]
* [[Documentation:Rest Services In MDriven]]
* [[Documentation:OCLOperators RestGet]]
* [[Documentation:OCLOperators RestPut]]

[[Category:EAL (Executable Action Language)]]
[[Category:External communication]]
[[Category:Exposing REST from the model (overview)]]
[[Category:EAL (Executable Action Language)]]
[[Category:External communication]]
[[Category:Exposing REST from the model (overview)]]
[[Category:EAL (Executable Action Language)]]
[[Category:External communication]]
[[Category:Exposing REST from the model (overview)]]