Prefer Header

Prefer Header

The OData specification defines the Prefer HTTP header to customize the behavior of certain operations.
The PROLIN Power Server REST API supports three categories of Prefer header values:

  • Return preferences (for data-altering operations)
  • Conflict-resolution preferences (for attachment uploads)
  • Paging preferences (for collections)

Return Preferences

Used with POST (create, attachment upload) and PATCH operations to define how the server should respond after altering data.

Preference Description
return=minimal The response should not include the modified object. Returns HTTP 204 (No Content) on success.
return=representation The response should include the altered object. Returns HTTP 200 (OK) or HTTP 201 (Created).

Without a Prefer header, POST returns the created object (HTTP 201) and PATCH returns HTTP 204 (No Content).

A HTTP 204 response to a POST still identifies the created object: its Location and OData-EntityId headers carry the object’s URL.

Requests that create or remove a reference ($ref) ignore return preferences. They always return HTTP 204 (No Content); see Relating Resources.

Example

PATCH http://myserver:5181/odata/ServiceRequests(139239)
Prefer: return=representation
Content-Type: application/json

{
  "Description": "Printer cleaned and tested successfully."
}

⚠️ Note:
Database rules (DB Rules) run in the background after a POST or PATCH is saved.
The returned object, and a GET issued immediately afterwards, may not yet include the changes those rules make.
How long the rules take depends on the rules themselves and on the server load.

Conflict-Resolution Preferences

⚠️ Currently supported only for attachment uploads.

When uploading attachments, naming conflicts may occur if a file with the same name already exists.
The conflict-resolution preference controls how the API handles these conflicts.

Preference Description
conflict-resolution=replace Replaces the existing file with the new one. Responds with HTTP 200 (OK) if replaced, or HTTP 201 (Created) if new.
conflict-resolution=rename Automatically renames the new file by adding a sequence suffix (e.g., _1). Always returns HTTP 201 (Created).
conflict-resolution=none No conflict resolution. If a name conflict occurs, responds with HTTP 409 (Conflict). (Default behavior)

Example (Attachment Upload with Conflict Resolution)

POST http://myserver:5181/odata/Problems(7403319703)/Attachments
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: multipart/form-data; boundary=-------------------------acebdf13572468
Prefer: conflict-resolution=replace

---------------------------acebdf13572468
Content-Disposition: form-data; name="file"; filename="myfile.txt"
Content-Type: text/plain

<File Content Here>
---------------------------acebdf13572468--

Paging Preferences

Used with GET on a collection to choose the page size.

Preference Description
odata.maxpagesize=n A response holds at most n entries, and never more than 250. The response confirms the page size in a Preference-Applied header.

See Paging for how it combines with $top.

💡 Tip:
Use return=representation during development for easier debugging,
and return=minimal in production for faster performance and smaller payloads.

Back to top