A RESTCONF PUT to the ietf-interfaces entry interface=eth0%2F1 carries a body whose name is eth0/2; what does the specification say, and how do you move that configuration?
answer
- the key is the address
- URI key and body key must agree
- keys are never edited in place
- delete one entry, create another
basics
~20 sRFC 8040 requires the body's key values to equal the URI's and forbids PUT or PATCH from changing a key, so this is no rename. Moving the configuration means deleting eth0/1 and creating eth0/2, atomically in one YANG Patch when that matters.
solid answer
~50 sIn RESTCONF the key values in a list-entry URI are the entry's identity. RFC 8040 §4.5 says that when a PUT targets a list instance, the key leaf values in the message body MUST be the same as those in the request URI, and that PUT MUST NOT be used to change key values; §4.6.1 says the same of plain PATCH. A body naming `eth0/2` sent to `interface=eth0%2F1` is therefore an invalid request, not a rename. To move the configuration you remove the old entry and create a new one: DELETE the old URI and PUT the new one, or send both edits in one YANG Patch (RFC 8072), whose edit targets use the same path encoding and which the server applies atomically. Check first whether the name can change at all: for a system-controlled interface, RFC 8343 makes `name` the device's own name.
go deeper
Remember that a list entry's key is part of its URI and that a key value is never edited in place.
Quote the rule: body keys must equal URI keys under PUT and plain PATCH, so a rename is a delete plus a create.
Plan configuration moves between entries: an atomic YANG Patch against two requests, keyless state lists, and system-controlled names that cannot be renamed.
Consider how a model's key choice, a human-readable name or a stable identifier, shapes renames and migrations for every client of the API.
## The key is the address In YANG a list's **key** leaves identify each entry. RESTCONF carries that identity into the URI: RFC 8040 §3.5.3 writes a list entry as one segment, `name=key`, so `.../ietf-interfaces:interfaces/interface=eth0%2F1` **is** the entry whose `name` is `eth0/1`. Everything below it, the description, `ietf-ip:ipv4/mtu`, the addresses, hangs off that address. Because the key and the address are the same thing, the key cannot change while the entry keeps its address. Three consequences follow: - a different key is a different entry, with its own URI and its own subtree; - a client finds an entry only by its key values, never by its position or by any other leaf; - configuration elsewhere that refers to the entry by its key still holds the old value after a move: RFC 8343's `interface-ref` type is a `leafref` to the interface `name`, so references to `eth0/1` must be edited in the same change. ## What RFC 8040 says about keys in a body The same two rules appear for both methods that edit an existing data resource in place: - **PUT (§4.5):** if the target is a list instance, the key leaf values in the message body MUST be the same as the key leaf values in the request URI, and PUT MUST NOT be used to change the key leaf values of a data resource instance. - **Plain PATCH (§4.6.1):** the same two sentences, with PATCH in place of PUT. So a PUT to `interface=eth0%2F1` whose body says `"name": "eth0/2"` is outside the protocol. It is neither a rename of `eth0/1` nor a create of `eth0/2`. Note also that the body writes the name plainly, `eth0/2`; percent-encoding belongs only to the URI. ## Moving configuration to a new key | Approach | Requests | What happens | |---|---|---| | DELETE the old entry, then PUT the new one | two | simple, but for a moment the configuration exists under neither name, and if the PUT fails the old entry is already gone | | one YANG Patch (RFC 8072) with a `delete` edit and a `create` edit | one | RFC 8072 encodes each edit's `target` by the same rules as a RESTCONF data resource identifier and requires the patch to be applied atomically: if it cannot be completed, no configuration changes are made | | PUT on the parent `interfaces` container with the new list contents | one | PUT replaces the whole container, so the body must restate every other interface or they are removed; rarely practical | For the YANG Patch, the request URI is the parent, `.../ietf-interfaces:interfaces`, and the edit targets are relative to it: `/interface=eth0%2F1` for the delete and `/interface=eth0%2F2` for the create, the second carrying the new entry with `name` set to `eth0/2`. ## Keys that limit what you can address - **Keyless state lists.** RFC 8040 notes that non-configuration lists are not required to define keys, and that a single instance of such a list cannot be accessed. The client retrieves the whole list, or its parent container, and picks the entry itself. - **More than one instance in one reply.** When a retrieval of a list or leaf-list identifies more than one instance, the XML encoding cannot carry it and the server MUST answer `400 Bad Request` with error-tag `invalid-value`; in JSON the instances are returned as an array. - **System-controlled names.** RFC 8343 says that for a system-controlled interface, `name` is the device-specific name of the interface, so renaming a physical port is not a meaningful edit; moving its configuration to another port is. ## Let the server tell you the key When a POST creates a list entry under its parent, RFC 8040 §4.4.1 requires a `Location` header that identifies the created child. In the RFC's example that header ends in the new entry's percent-encoded key, with a space in the key written `%20`. A client that keeps the `Location` value, instead of re-encoding the key itself, cannot drift from the server's idea of the entry's address. ## Checklist 1. Treat a list entry's URI as its identity, and never vary the key in the body. 2. Build the URI key and the body key from the same value, percent-encoding it only for the URI. 3. Move configuration with a delete plus a create, in one YANG Patch when a partial failure would hurt. 4. Before renaming, check whether the model lets the key change at all.
- Why is a RESTCONF DELETE followed by a PUT riskier than one YANG Patch for this move?They are two independent requests. Between them the configuration exists under neither name, and if the PUT fails the old entry is already gone. RFC 8072 requires a YANG Patch to be applied atomically: if the whole patch cannot be completed, no configuration change is made, so the move happens entirely or not at all.
- How does a RESTCONF client read one entry of a state list that defines no key?It cannot address that entry. RFC 8040 notes that non-configuration lists need not define keys and that a single instance of such a list cannot be accessed. The client retrieves the list, in JSON as an array, or its parent container, and picks the entry itself; in XML, a retrieval of the list that identifies more than one instance must fail with 400 Bad Request.
saying these in an interview costs you the question
- A PUT with a new key in the body renames the list entry.
- Plain PATCH, unlike PUT, may change a list entry's key.
- The key in the body must be percent-encoded like the one in the URI.
- Any state list entry can be fetched by its position in the URI.
- DELETE then PUT is as safe as one YANG Patch for a move.