HTTP PATCH

HTTP PATCH

Type: http-patch  ·  Package: HTTP Activities v1.0.5  ·  Output: ZoanHttpResponse

Sends a PATCH request to partially update a resource: you send only the fields that change, not the whole object. It is the most convenient way to change a single value — a status, a phone number — without resending the entire record.

How it works

Same as PUT, but body carries only the fields to change. The API updates those fields and leaves the rest untouched. Returns a ZoanHttpResponse.

• Body: with the default contentType (application/json), body is converted to JSON; with another contentType (for example application/merge-patch+json or application/json-patch+json, if the API requires it) it is sent as text, so pass it already serialized with toJson(changes). See body and Content-Type.
• Status codes: 2xx succeeds; any other code makes the activity fail — see what makes the activity fail.
• Timeouts: 30 s to connect and, by default, 5 min for the whole request (timeout parameter). When they run out, the activity fails with a normal error that Try / Catch and Retry catch — see timeouts.

Required parameters

Parameter	Type	Default	Description
url	string	—	Absolute URL of the resource to update.
body	object	—	Only the fields that change: dictionary (→ JSON) or text (for other contentType values). With a JSON contentType, a text is sent as a JSON string; if you have JSON in a text, use parseJson(text).

Optional parameters

Parameter	Type	Default	Description
contentType	string	"application/json"	Media type of the body, without parameters. Only values containing application/json convert body to JSON. charset=utf-8 is added for you.
headers	Dictionary	—	Extra headers (name → value), in the JSON editor. Content headers are ignored. See headers.
authorization	Dictionary	—	Authentication in the JSON editor: bearer, basic or apikey. See authentication.
timeout	int	300	Seconds to wait for the whole request (connection, sending and answer); maximum 3600, decimals allowed (0.5). Since version 1.0.5. See timeouts.

Output

Returns a ZoanHttpResponse with .StatusCode (2xx, typically 200 or 204), .Ok (always true in an output you receive), .Body (many APIs return the updated resource; JSON → dictionary/list, anything else → text, empty → "") and .Headers.

Common errors

Message	Cause and fix
The server answered HTTP 422 (Unprocessable Entity) to the PATCH request.	The server answered with a non-2xx code (422/400 invalid data, 404, 405 if the API does not support PATCH, 5xx). Handle the expected ones with Try / Catch.
The format of value 'application/json; charset=utf-8' is invalid.	contentType has parameters. Keep only the media type.
No such host is known. (or another system network error)	There was no response. error.Type is "HttpRequestException".
The PATCH request to api.example.com did not finish within 300 s (timeout). Raise 'timeout' if the service takes longer.	The server did not answer within timeout. error.Type is \"TimeoutException\": catch it with Try / Catch or retry with Retry; if the API is slow by nature, raise timeout. If connecting fails, the message says Could not connect to … within 30 s.
An invalid request URI was provided. Either the request URI must be an absolute URI or BaseAddress must be set.	url is not absolute. Include https://.
'url' is required.	The url expression evaluated to null.

Example

Change only the status of an order and read the status the API confirms:

HTTP PATCH
  url  = "https://api.erp.com/orders/" + orderId
  body = new Dictionary<string, object> { ["status"] = "shipped" }
  authorization = { "type": "bearer", "token": credential("erp-api")["value"] }
  → output: resp

Log   message = "Order " + orderId + " is now: " + resp.Body["status"]

PATCH vs PUT

Use PATCH when you change only some fields (simpler and safer). Use PUT when you replace the whole resource.

Related activities

• HTTP PUT — full replacement.
• HTTP GET — read the updated resource.