Consider create_*_and_fetch helpers; keep the int-returning primitives

[baraline]

Current state

Every write surfaces an id or nothing: 12 create_* methods return int,
link_ticket_timeline_document returns int, upload_document returns dict[str, object], and all 13
update_* plus 11 delete_* return None.

Correcting a common justification

-> int reflects what the client keeps, not what GLPI sends. _resource_create parses the entire
JSON body and returns one integer from it (_transport.py:426-480), discarding the rest silently.
Demonstrated with httpx.MockTransport under the real client: a POST answering 201 with a complete
16-field ticket record still yields bare 4242, and a PATCH answering 200 with the full updated record
yields None.

So the current signature cannot be cited as evidence about server behaviour. Open question worth one
preprod probe: does the v2 POST body carry only id, or a fuller record? Live runs prove an integer id
is present (four create_* ids are round-tripped in integration_tests/); nobody has recorded the full
body.

Likewise, "re-reading would hide a second HTTP call behind a write" is not an invariant this codebase
holds -- create_kb_article already makes a v2 POST plus a v1 PUT behind one create-shaped name
(_article.py:89-121).

Recommendation: keep the primitives

The load-bearing reasons are:

• 19 of GetTicket's 44 fields are server-assigned, so the fetch is real work a caller may not want
• the read-back can fail independently of the write and destroy the id
• callers already write the two-line composition in the docs

Costs if adopted

• 12-13 methods, not one, and it cannot be made uniform -- create_item_plugin_field_row has no get_
  counterpart
• _and_ appears in zero of 85 current method names, against a verb_noun house style
• testing/tests/test_skill_references.py forces every new name into a SKILL.md
• the composed helper has a failure mode the primitive lacks (write succeeds, read-back raises, id lost) --
  it would need create_kb_article's discipline of naming the new id in the error

Mechanically it is safe: a plain token rewrite for unasync, no mypy ignore needed, and
test_method_invocation.py:265-302 parametrises over every public name so coverage is automatic. Sphinx
needs no edit (api_reference.rst uses :members: :inherited-members:).

Filed for a decision, low priority.

[baraline]

Decision: measure before designing. Nobody has recorded the full v2 POST body, and the answer changes what the right fix is.

integration_tests/probe_wire_format.py (commit 128b5a3) records it:

python integration_tests/probe_wire_format.py

Probe 2 creates one ticket, prints the status, the Location header, the body size and every key, then deletes the ticket in a finally. It prints a verdict:

• {"id": N} only → a fetch is genuinely a second round trip, and the choice is between create_*_and_fetch (12–13 methods, non-uniform) and leaving callers the two-line composition.
• A fuller record → the client is discarding it in require_response_int, and the fix is to stop doing that. No new API, no second request.

Adjacent work already landed: #26 (9f594eb) widened require_response_int to accept a numeric string, an id nested under data, and a Location-header fallback — so if the probe shows any of those shapes, that part is handled.

Holding this open pending the probe output.

[baraline]

Measured against live GLPI 11 preprod — the POST body carries the id and nothing else

status      : 201
Location    : /Assistance/Ticket/65024
body bytes  : 49
body keys   : ['href', 'id']
body        : {"id": 65024, "href": "/Assistance/Ticket/65024"}

So the -> int signature is not discarding a fuller record. The client keeps everything of substance the server sent; href is the only field dropped, and it is derivable from the id.

That settles the open question and removes the cheap option: obtaining the created record genuinely costs a second round trip. The choice is the one originally framed — create_*_and_fetch helpers versus leaving callers the two-line composition — with none of the "just stop throwing it away" shortcut available.

My recommendation is unchanged: keep the primitives, for the reasons in the issue body (12–13 methods, non-uniform because create_item_plugin_field_row has no get_ twin, _and_ in zero of 85 current names, and a composed helper can lose the id when the read-back fails where the primitive cannot).

One correction to the issue body while I am here: "it reflects what the client keeps, not what GLPI sends" was the right caution to raise, but the measurement shows the two coincide here. The signature is honest after all.

Confirmed as a side effect

A Location header is present on create (/Assistance/Ticket/65024). The fallback added in #26 (9f594eb) is therefore wired to something real, not a hypothetical — though since the body also carries the id, it is defence rather than a fix for a live break.

Probe output produced by integration_tests/probe_wire_format.py. Both probe runs cleaned up after themselves; the ticket left behind by the first crashed run (65023) was verified by name and force-deleted.