API: Duplication of endpoints / Missing documentation

[Tinggaard]

Deployment Type

Self-hosted

NetBox Version

v4.0.2

Python Version

3.11

Steps to Reproduce

Observe identical example output and parameters of GET, PUT and PATCH on endpoint /api/extras/scripts/{id}/ from the Swagger UI: https://demo.netbox.dev/api/schema/swagger-ui/#/extras/extras_scripts_update

Expected Behavior

I would assume that I could upload a new script, by PUTing on the endpoint shown in the documentation or updating an existing script by PATCHing.

I don't know if this is derived by #16670 or someplace else (or even the intended behaviour), but it seems poorly documented.

Observed Behavior

The parameters for all three request types are identical, and produce (as far as I can tell) the same output, making them redundant.

Example output from swagger for PUT /api/extras/scripts/{id}/:

{
  "id": 0,
  "url": "string",
  "module": 0,
  "name": "string",
  "description": "string",
  "vars": "string",
  "result": {
    "id": 0,
    "url": "string",
    "display": "string",
    "object_type": "string",
    "object_id": 9223372036854776000,
    "name": "string",
    "status": {
      "value": "pending",
      "label": "Pending"
    },
    "created": "2024-08-07T12:20:52.887Z",
    "scheduled": "2024-08-07T12:20:52.887Z",
    "interval": 2147483647,
    "started": "2024-08-07T12:20:52.887Z",
    "completed": "2024-08-07T12:20:52.888Z",
    "user": {
      "id": 0,
      "url": "string",
      "display": "string",
      "username": "5qXgC14X8.guRiZVw7rDR73dt_z@yIR3WER55p+ZGY8RqH+GgW-aUt+MJtWpwCHnUNsxUjCmgi67dh2O2ZafSn4S1zi4FYSE"
    },
    "data": "string",
    "error": "string",
    "job_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "display": "string",
  "is_executable": true
}

Example output from swagger for GET /api/extras/scripts/{id}/:

{
  "id": 0,
  "url": "string",
  "module": 0,
  "name": "string",
  "description": "string",
  "vars": "string",
  "result": {
    "id": 0,
    "url": "string",
    "display": "string",
    "object_type": "string",
    "object_id": 9223372036854776000,
    "name": "string",
    "status": {
      "value": "pending",
      "label": "Pending"
    },
    "created": "2024-08-07T13:02:34.059Z",
    "scheduled": "2024-08-07T13:02:34.059Z",
    "interval": 2147483647,
    "started": "2024-08-07T13:02:34.059Z",
    "completed": "2024-08-07T13:02:34.059Z",
    "user": {
      "id": 0,
      "url": "string",
      "display": "string",
      "username": "5IYLJeGJeYewpKWUyJGK8Ixnat_JfhhIWQJUsZxMB_b1Lr7fJN6MQAJnEi5V6D7oxzatwPxVLzR"
    },
    "data": "string",
    "error": "string",
    "job_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "display": "string",
  "is_executable": true
}

The diff between the two seems negligible:

19,20c19,20
<     "created": "2024-08-07T13:03:44.911Z",
<     "scheduled": "2024-08-07T13:03:44.911Z",
---
>     "created": "2024-08-07T13:04:50.877Z",
>     "scheduled": "2024-08-07T13:04:50.877Z",
22,23c22,23
<     "started": "2024-08-07T13:03:44.911Z",
<     "completed": "2024-08-07T13:03:44.911Z",
---
>     "started": "2024-08-07T13:04:50.877Z",
>     "completed": "2024-08-07T13:04:50.877Z",
28c28
<       "username": "2NL9ZGefb"
---
>       "username": "mZgtcPCANqo1cd3fvytqaFIh6bQTQQ7gmNzDLZW3"

I was looking for an endpoint to upload custom scripts without using the GUI but got stuck here hoping for some clarification.

TL;DR I cannot tell what the POST and PATCH endpoints are used for (/api/extras/scripts/{id}/), as both the parameters, as well as the return object, seem identical with GET.
I would expect that PUT should take a request body, where I can include a script that I wish to upload, like the request bodies required for PUTing on the other endpoints in the API.

[jeremystretch]

@Tinggaard please revise your post above to include the specific output in question, as well as what you believe to be the corrected form.

[Tinggaard]

@jeremystretch I have now clarified the issue