ETag support for the REST API #419

New Issue

MrUnknownDE · 2026-04-05T16:31:20+02:00

MrUnknownDE commented

2026-04-05 16:31:20 +02:00

Originally created by @jeremystretch on 2/4/2026

NetBox version

v4.5.2

Feature type

New functionality

Proposed functionality

Add support for ETags to the REST API. This entails two functions:

Include an ETag header on the response to a REST API request for an individual object. (It's not clear whether ETags could be supported on list views.)
Recognize and respect the If-Match header if included on a PUT/PATCH request. If the ETag specified by the If-Match header is outdated, return a 412 (precondition failed) response.

The mechanism for generating an ETag is not specified by the standard. It probably makes sense to use the last_updated (or, if not set, created) timestamp for the object being retrieved. This obviates the need to generate a hash for the object.

It's worth noting that we're pursuing ETag support specifically as opposed to e.g. support for the If-Modified-Since header as it and the Last-Modified header are limited to second precision: This is insufficient to guard against competing writes from multiple clients. Our native timestamps support millisecond precision.

(This functionality was originally proposed in #4917 but did not capture a sufficient use case.)

Use case

The primary benefit of this functionality is to protect against conflicting updates to an object from multiple clients. A simple scenario (using serialized ETags):

Client A requests site 1 (ETag = 100).
Client B requests site 1 (ETag = 100).
Client A updates the status of site 1 with If-Match: 100. The update succeeds, and the site's ETag is now 200.
Client B updates the status of site 1 with If-Match: 100. The update fails, and NetBox returns a 412 response informing the client that its cached copy of the object is no longer valid.
Client B requests site 1 again (ETag = 200) and determines whether an update is still needed.

A secondary benefit is potentially recognized using the If-None-Match header, which directs the API to return the object only if its ETag has been modified from the one given. However, since the server must first fetch the object from the database to retrieve its ETag (timestamp) for comparison anyway, this may be of little practical value without some external caching in place.

Database changes

None expected, unless we decide to store ETag values in the database for some reason.

External dependencies

N/A

*Originally created by @jeremystretch on 2/4/2026* ### NetBox version v4.5.2 ### Feature type New functionality ### Proposed functionality Add support for ETags to the REST API. This entails two functions: * Include an [`ETag`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/ETag) header on the response to a REST API request for an individual object. (It's not clear whether ETags could be supported on list views.) * Recognize and respect the [`If-Match`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/If-Match) header if included on a PUT/PATCH request. If the ETag specified by the `If-Match` header is outdated, return a [412 (precondition failed)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/412) response. The mechanism for generating an ETag is not specified by the standard. It probably makes sense to use the `last_updated` (or, if not set, `created`) timestamp for the object being retrieved. This obviates the need to generate a hash for the object. It's worth noting that we're pursuing ETag support specifically as opposed to e.g. support for the [`If-Modified-Since`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/If-Modified-Since) header as it and the `Last-Modified` header are limited to second precision: This is insufficient to guard against competing writes from multiple clients. Our native timestamps support millisecond precision. (This functionality was originally proposed in #4917 but did not capture a sufficient use case.) ### Use case The primary benefit of this functionality is to protect against conflicting updates to an object from multiple clients. A simple scenario (using serialized ETags): 1. Client A requests site 1 (ETag = 100). 2. Client B requests site 1 (ETag = 100). 3. Client A updates the status of site 1 with `If-Match: 100`. The update succeeds, and the site's ETag is now 200. 4. Client B updates the status of site 1 with `If-Match: 100`. The update fails, and NetBox returns a 412 response informing the client that its cached copy of the object is no longer valid. 5. Client B requests site 1 again (ETag = 200) and determines whether an update is still needed. A secondary benefit is potentially recognized using the [`If-None-Match`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/If-None-Match) header, which directs the API to return the object only if its ETag has been modified from the one given. However, since the server must first fetch the object from the database to retrieve its ETag (timestamp) for comparison anyway, this may be of little practical value without some external caching in place. ### Database changes None expected, unless we decide to store ETag values in the database for some reason. ### External dependencies N/A

MrUnknownDE closed this issue

2026-04-05 16:31:20 +02:00

Sign in to join this conversation.

Branches Tags

main

21455-sql-indexes-audit

21357-register-model-actions

feature

20924-plugin-ui-components

21766-improve-test-coverage-for-sortable-table-columns

21157-export-template-public-models

21025-pre-render-config-contexts

21364-swagger

feature-ip-prefix-link

20911-dropdown-3

fix_module_substitution

21160-filterset

20911-dropdown-2

20044-elevation-stuck-lightmode

7604-filter-modifiers-v3

20660-script-load

19724-graphql

14884-script

19720-macaddress-interface-generic-relation

fix-19669-api-image-download

7604-filter-modifiers

19275-fixes-interface-bulk-edit

fix-17794-get_field_value_return_list

11507-show-aggregate-and-rir-on-api

9583-add_column_specific_search_field_to_tables

No Label complexity: medium complexity: medium complexity: medium complexity: medium complexity: medium complexity: medium complexity: medium complexity: medium complexity: medium complexity: medium complexity: medium complexity: medium complexity: medium complexity: medium complexity: medium complexity: medium netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github/netbox#419