Kohsuke Kawaguchi
created JENKINS-24052
REST API for manipulating collection of labels assigned on a node
Issue Type:
Improvement
Assignee:
Unassigned
Components:
core
Created:
30/Jul/14 9:02 PM
Description:
This was requested in IRC.
It'd be nice to expose individual labels of a computer in the REST API, for example so that "GET /computer/foo/labels/xyz" can be used to test if the computer "foo" has the label "xyz" (200 or 404), "PUT /computer/foo/labels/xyz" can be used to assign a new label to the computer, and "DELETE /computer/foo/labels/xyz" can be used to remove a label from a computer.
The stapler-bound object tree for "../labels/..." should be reusable for other collection property manipulation elsewhere, and this will improve general REST-fulness of the API.
The full conversation below for a record:
(01:46:07 PM) sxiao: kohsuke: hey, a design question for you, why do we expect to download the entire `config.xml` and send it back if we want to change anything. Each `config.xml` has different definition , it's hard to really define what's in `config.xml` as we are writing some API
(01:46:47 PM) sxiao: kohsuke: I want to said update/add/remove a label from an existing running node (/computer/node) and I couldn't do that with /api/json
(01:47:06 PM) sxiao: so I want to know why some of these common API calls aren't expose via a REST endpoint
(01:47:15 PM) kohsuke: sxiao: not sure if I follow, but you want like PATCH support to be able to update the fragment?
(01:47:28 PM) kohsuke: ... because you are worried about other people updating it concurrently?
(01:47:37 PM) sxiao: yeah
(01:47:46 PM) sxiao: i would like to update the fragment
(01:48:08 PM) sxiao: or i was looking for something like /computer/node/api/json?label=abc,def
(01:49:11 PM) sxiao: kohsuke: instead of taking a node offline using "/toggleOffline" , we actually want the node to stay online for other labels, but we want to remove labels for a short period, run some maintenance task, and re-add the labels back
(01:49:14 PM) sxiao: kohsuke: ^^
(01:49:48 PM) kohsuke: OK, then it's not really a PATCH method on .../config.xml URL, but you probably want the usual REST handling for a collection (labels of a computer)
(01:50:09 PM) kohsuke: That' be nice to have
(01:51:09 PM) kohsuke: "PUT /computer/foo/labels/xyz" to add a new label, "DELETE /computer/foo/labels/xyz" to delete, etc, right?
(01:51:52 PM) sxiao: kohsuke: yeah
(01:52:10 PM) sxiao: kohsuke: or if we can find a way to update a segment of config.xml
(01:52:15 PM) sxiao: instead of downloading the entire config.xml
(01:52:21 PM) sxiao: making 1 change on 1 field
(01:52:23 PM) sxiao: and push it back
(01:52:36 PM) sxiao: that's actually ok if we run some `grep|sed` on that config.xml
(01:52:45 PM) sxiao: but the definition in each config.xml is different
(01:52:56 PM) kohsuke: so that would be like "PATCH config.xml?xpath=..." ?
(01:53:03 PM) kohsuke: where xpath points to the element to be replaced?
(01:53:07 PM) sxiao: like /computer/node_a/config.xml could have different fields from /computer/node_b/config.xml
(01:53:14 PM) sxiao: kohsuke: yeah
(01:53:24 PM) sxiao: kohsuke: either way is something to think about
(01:53:30 PM) kohsuke: Does that really help you though? It doesn't sound too different to do that xpath replacement on the client side
(01:53:30 PM) sxiao: IMHO json is the way to go
(01:53:45 PM) sxiao: i can try that
(01:54:05 PM) sxiao: but i still think something like /api/json?label=XXX PUT/DELETE/ is better
(01:54:07 PM) kohsuke: ... unless you are really worried about concurrent updates, but I just have hard time imagining someone updating computer labels in any high frequency
(01:54:36 PM) sxiao: kohsuke: concurrency will be a problem, but in my case, it's not an issue
(01:54:46 PM) kohsuke: sxiao: I don't follow the semantics of "PUT /computer/foo/api/json?label=XXX"
(01:55:04 PM) sxiao: kohsuke: modifying the existing label
(01:56:38 PM) kohsuke: Put differently, that URL implies that the Api class does something generic to every property of every model object, and I don't know how to
