multi-point-vpn: naming, modelling, and editorial corrections

[hdamker]

Problem description

Review of code/API_definitions/multi-point-vpn.yaml (version 0.1.0-alpha.1) found naming/modelling deviations from the CAMARA API Design Guide (r3.4) and editorial issues. These do not block validation under the r3.4 ruleset. Line numbers refer to the file as released on the r1.1 snapshot.

Naming and modelling

1. Property naming (camelCase, Design Guide §5): cloudGatewayIP (line 422) and waitdays (line 275) would be cloudGatewayIp and waitDays.
2. Resource vocabulary is inconsistent. The resource is /network with a Network schema, but the GET operationId is getVpnConnection (line 131) and there is a separate Connection schema (line 288). "Network", "VpnConnection", and "Connection" are used for related concepts.
3. Connection (lines 288–300) is an allOf with a single inline member (no composition effect), and its description is "Another Characteristic that is related to the current Characteristic;" (line 292), which does not describe the connection entity.
4. updateNetwork (line 87) uses PATCH with application/json (line 99). The Design Guide convention for partial updates is application/merge-patch+json. The operation description "Update a new multipoint virtual private network" (line 91) reads as create rather than update.
5. The three /network/{serviceId} operations (getVpnConnection lines 126–155, updateNetwork lines 87–125, deleteNetwork lines 156–178) do not document a 404 response. For operations addressing a resource by id, the Design Guide lists 404 as a response to document based on the API design (§3.1). (Note: multi-point-vpn.feature already includes a 404 scenario for GET.)
6. Units and value types: guaranteeBandwidth description uses "Mps" (lines 267, 412, etc.), presumably "Mbps"; Amount.currency (lines 250–252) is an unconstrained string with no currency-code format; Duration.unit (lines 310–312) is a free string ("days" in examples). Amount.amount and Duration.value declare default: 1 (lines 248, 308).
7. createNetwork 201 response (lines 66–77) does not include a Location header for the created resource.
8. deleteNetwork returns 202 with no body (lines 166–170); there is no resource to track the asynchronous deletion state. This is a design decision to confirm.

Editorial

9. Example summaries: "Assesment Sample 1" (lines 473, 493) and "Create Connection Sampl 1" (line 522) contain typos.
10. info.description spacing: "IPv4 addressand/or" (line 12), "application server(AS)IPv4" (line 16), "NOTE-" (line 25).

Expected behavior

Align property names with camelCase, settle on a single resource vocabulary, replace the placeholder Connection description and remove the single-member allOf if not needed, confirm the PATCH media type and description, decide on documenting 404 for resource-id operations, constrain units/currency where applicable, and correct the editorial items.

Additional context

Tracked separately from the mandatory security and definition-correctness items. Property-name and schema changes affect the API contract once r1.1 is tagged.