starred/netbox
1
0
Fork 0
mirror of https://github.com/netbox-community/netbox.git synced 2026-01-11 21:10:29 +01:00
Code Issues 273 Packages Projects Releases 10 Wiki Activity

Maintain backward compatibility with previous releases in REST API #5661

New Issue
Closed
opened 2025-12-29 19:30:47 +01:00 by adam · 5 comments
adam commented 2025-12-29 19:30:47 +01:00
Owner
Copy Link

Originally created by @jeremystretch on GitHub (Nov 15, 2021).

NetBox version

v3.1-beta1

Feature type

New functionality

Proposed functionality

Although NetBox's REST API supports versioning, it is limited to the current minor release at the time (e.g. API-Version: 3.0 under NetBox v3.0); there is no backward compatibility with prior releases. I'd like to propose that, starting with v3.0, NetBox begin maintaining backward compatibility with prior REST API versions.

There are two DRF settings which control versioning support:

REST_FRAMEWORK_VERSION = VERSION.rsplit('.', 1)[0]  # E.g. "v3.0"
REST_FRAMEWORK = {
    'ALLOWED_VERSIONS': [REST_FRAMEWORK_VERSION],
    ...
}

Under NetBox v3.1, ALLOWED_VERSIONS would become:

['3.0', REST_FRAMEWORK_VERSION]

And under v3.2:

['3.0', '3.1', REST_FRAMEWORK_VERSION]

Of course, it would be infeasible to support such backward compatibility indefinitely. Regarding how far back we should maintain compatibility, I'm open to suggestions, but two minor releases seems like a reasonable goal. (E.g. backward compatibility for v3.0 would be dropped in v3.3.) Backward compatibility would not be provided across major releases (e.g. from v3.0 to v2.11).

In order to actually effect this support, we would need to retain a compatible version of each serializer for which a breaking change has been introduced. For example, in v3.1 the cable_peer field of InterfaceSerializer has been renamed to link_peer. If an API client requests v3.0, NetBox will return a serializer referencing this field by its old name.

The DRF documentation provides a rough idea how this should work, though we'll still need to figure out the ideal implementation.

Use case

Enabling support for prior REST API versions will make it easier for users to upgrade NetBox. For example, NetBox can be upgraded from v3.0 to v3.1 while still serving clients which support only v3.0 of the REST API. These clients can specify the desired API version, and NetBox will return compatible data.

Database changes

No response

External dependencies

No response

Originally created by @jeremystretch on GitHub (Nov 15, 2021). ### NetBox version v3.1-beta1 ### Feature type New functionality ### Proposed functionality Although NetBox's REST API supports versioning, it is limited to the current minor release at the time (e.g. `API-Version: 3.0` under NetBox v3.0); there is no backward compatibility with prior releases. I'd like to propose that, starting with v3.0, NetBox begin maintaining backward compatibility with prior REST API versions. There are two DRF settings which control versioning support: ```python REST_FRAMEWORK_VERSION = VERSION.rsplit('.', 1)[0] # E.g. "v3.0" REST_FRAMEWORK = { 'ALLOWED_VERSIONS': [REST_FRAMEWORK_VERSION], ... } ``` Under NetBox v3.1, `ALLOWED_VERSIONS` would become: ```python ['3.0', REST_FRAMEWORK_VERSION] ``` And under v3.2: ```python ['3.0', '3.1', REST_FRAMEWORK_VERSION] ``` Of course, it would be infeasible to support such backward compatibility indefinitely. Regarding how far back we should maintain compatibility, I'm open to suggestions, but two minor releases seems like a reasonable goal. (E.g. backward compatibility for v3.0 would be dropped in v3.3.) Backward compatibility would _not_ be provided across major releases (e.g. from v3.0 to v2.11). In order to actually effect this support, we would need to retain a compatible version of each serializer for which a breaking change has been introduced. For example, in v3.1 the `cable_peer` field of InterfaceSerializer has been renamed to `link_peer`. If an API client requests v3.0, NetBox will return a serializer referencing this field by its old name. The [DRF documentation](https://www.django-rest-framework.org/api-guide/versioning/#versioning-with-rest-framework) provides a rough idea how this should work, though we'll still need to figure out the ideal implementation. ### Use case Enabling support for prior REST API versions will make it easier for users to upgrade NetBox. For example, NetBox can be upgraded from v3.0 to v3.1 while still serving clients which support only v3.0 of the REST API. These clients can [specify the desired API version](https://www.django-rest-framework.org/api-guide/versioning/#acceptheaderversioning), and NetBox will return compatible data. ### Database changes _No response_ ### External dependencies _No response_
adam added the type: featurepending closurestatus: under review labels 2025-12-29 19:30:47 +01:00
adam closed this issue 2025-12-29 19:30:47 +01:00
adam commented 2025-12-29 19:30:48 +01:00
Author
Owner
Copy Link

@sdktr commented on GitHub (Nov 16, 2021):

Sound like a huge benefit to get users to upgrade sooner, allowing old clients to upgrade gradually.

When this was raised earlier you were concerned about the amount of work it would imply on the maintainers. What changed your mind? Is the ns1 offering changing perspectives?

@sdktr commented on GitHub (Nov 16, 2021): Sound like a huge benefit to get users to upgrade sooner, allowing old clients to upgrade gradually. When this was raised earlier you were concerned about the amount of work it would imply on the maintainers. What changed your mind? Is the ns1 offering changing perspectives?
adam commented 2025-12-29 19:30:48 +01:00
Author
Owner
Copy Link

@jeremystretch commented on GitHub (Nov 16, 2021):

I just think (hope?) we're in a much more stable place now than in the past, and better able to plan out API changes.

@jeremystretch commented on GitHub (Nov 16, 2021): I just think (hope?) we're in a much more stable place now than in the past, and better able to plan out API changes.
adam commented 2025-12-29 19:30:48 +01:00
Author
Owner
Copy Link

@jeremystretch commented on GitHub (Nov 18, 2021):

The more I dig into this the more is seems like we would need to migrate to a versioned URL structure, unfortunately. It doesn't look like DRF has any mechanism to exclude new endpoints from old versions using AcceptHeaderVersioning. I'll need to spend some more time coming up with a solution for this. We won't be able to implement it for v3.1, but hopefully at some point in the future.

@jeremystretch commented on GitHub (Nov 18, 2021): The more I dig into this the more is seems like we would need to migrate to a versioned URL structure, unfortunately. It doesn't look like DRF has any mechanism to exclude new endpoints from old versions using `AcceptHeaderVersioning`. I'll need to spend some more time coming up with a solution for this. We won't be able to implement it for v3.1, but hopefully at some point in the future.
adam commented 2025-12-29 19:30:49 +01:00
Author
Owner
Copy Link

@github-actions[bot] commented on GitHub (Jan 18, 2022):

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. NetBox is governed by a small group of core maintainers which means not all opened issues may receive direct feedback. Please see our contributing guide.

@github-actions[bot] commented on GitHub (Jan 18, 2022): This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. NetBox is governed by a small group of core maintainers which means not all opened issues may receive direct feedback. Please see our [contributing guide](https://github.com/netbox-community/netbox/blob/develop/CONTRIBUTING.md).
adam commented 2025-12-29 19:30:49 +01:00
Author
Owner
Copy Link

@github-actions[bot] commented on GitHub (Feb 18, 2022):

This issue has been automatically closed due to lack of activity. In an effort to reduce noise, please do not comment any further. Note that the core maintainers may elect to reopen this issue at a later date if deemed necessary.

@github-actions[bot] commented on GitHub (Feb 18, 2022): This issue has been automatically closed due to lack of activity. In an effort to reduce noise, please do not comment any further. Note that the core maintainers may elect to reopen this issue at a later date if deemed necessary.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
beta
breaking change
complexity: high
complexity: low
complexity: medium
needs milestone
netbox
pending closure
plugin candidate
pull-request
Mirrored from GitHub Pull Request
 severity: high
severity: low
severity: medium
status: accepted
status: backlog
status: blocked
status: duplicate
status: needs owner
status: needs triage
status: revisions needed
status: under review
topic: GraphQL
topic: Internationalization
topic: OpenAPI
topic: UI/UX
topic: cabling
topic: event rules
topic: htmx navigation
topic: industrialization
topic: migrations
topic: plugins
topic: scripts
topic: templating
topic: testing
type: bug
type: deprecation
type: documentation
type: feature
type: housekeeping
type: translation
No Label pending closure status: under review type: feature
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
adam
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/netbox#5661
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?