[Accesses API] Documentation consistency with the API definition #151

Problem description

Five places where the documentation does not match the definition — four in
code/API_definitions/dedicated-network-accesses.yaml and one of them also in
documentation/API_documentation/DedicatedNetworks_GeneralDescription.md.

1. Adding and removing devices. info.description says:

When an access already exists, additional devices can be added by performing a POST operation on the /accesses/{accessId}/devices collection endpoint.

When an access already exists, devices can be removed from it by performing a DELETE operation on the /accesses/{accessId}/devices collection endpoint.

The API defines POST /accesses/{accessId}/devices/add and POST /accesses/{accessId}/devices/remove,
and /accesses/{accessId}/devices exists only for GET. The same two statements appear again in
documentation/API_documentation/DedicatedNetworks_GeneralDescription.md under "States of device's
access to the network", where the third line of the same list — querying with a GET — is correct.

2. Querying for a single device. info.description says:

All devices included in an access can be queried by performing a GET operation on the /accesses/{accessId}/devices endpoint. The query can be for a specific device or for devices with a specific status.

GET /accesses/{accessId}/devices accepts perPage, page and deviceStatus; there is no parameter
for a device. The operation's own summary and description say only "optionally filtered by device
status", so they already match the definition.

3. Supported device identifiers. Four statements in info.description do not agree with each
other:

• the opening paragraph says a device is identified by "either an MSIDSN or a Network Access
  Identifier" — two identifiers, and MSISDN is misspelled;
• a later paragraph says "at least one identifier … out of four options: IPv4 address, IPv6 address,
  Phone number, or Network Access Identifier";
• note 2 says the network access identifier "will not be supported with this version of the API";
• note 1 says an IP address is "not recommended when the IP address may change", without saying
  whether it is accepted.

The schema accepts all four, since device refers to Device in CAMARA_common.yaml. So an
implementer cannot tell from the specification which identifiers must be supported, and a consumer
cannot tell which are safe to send.

4. Whether an access can be created without devices. The error handling in info.description
says:

• If there is no device object, then the server will return an error with the 422 MISSING_IDENTIFIER error code.

The definition allows it, though: CreateAccessRequest requires only networkId, devices is
optional, and the 201 response of createAccess is described as "Successful creation of the access
for all devices (if any)". So a request creating an access with no devices is valid against the
schema and has a documented success response, while the error handling says it is rejected.

5. A note refers to a property that does not exist. AddDevicesPartialSuccess says:

NOTE: Both successful and failed devices are listed in results. A successful result for a device contains a deviceAccess.

The property on ResultForDevice is named accessDevice.

Expected action

1. Describe the two operations as they are defined — added with POST /accesses/{accessId}/devices/add,
   removed with POST /accesses/{accessId}/devices/remove — in both files.
2. Correct the sentence in 2 so that it describes only the filter by device status. If a query for a
   single device was intended on this endpoint, please say so and we will raise it separately.
3. State plainly which device identifiers this version supports, and make the opening paragraph agree
   with both the schema and that decision. Fix the spelling of MSISDN. How an unsupported identifier
   is reported is a separate question, raised in the issue on createAccess responses.
4. Decide which of the two statements in 4 is intended, and correct the other.
5. Change the note to refer to accessDevice.