Update device identification, fixes #60

Fixes #60

code/API_definitions/simple-edge-discovery.yaml

@@ -49,8 +49,8 @@ info:
 
   The API returns the closest Edge Cloud Zone to a given device, so that
   device needs to be identifiable by the network. This can be achieved either
-  by passing a device identifier in the request header, or, from the 3-legged
-  access token where implemented by the operator.
+  by passing a device identifier in the request header, or, from the 
+  three-legged access token where implemented by the operator.
 
   ## Passing a device identifier in the request header
 
@@ -112,50 +112,32 @@ info:
     Accept: application/json
   ```
 
-  ## Identifying a device from the access token
+  ## Identifying the device from the access token
 
-  This specification defines the `device` identifying headers as optional in
-  API requests, specifically in cases where the API is accessed using a
-  3-legged access token and the device can be uniquely identified by the token.
-  This approach simplifies API usage for API consumers by relying on the device
-  information associated with the access token used to invoke the API.
+  This API requires the API consumer to identify a device as the subject of 
+  the API as follows:
 
-  ### Handling of device information:
+  - When the API is invoked using a two-legged access token, the subject will be
+  identified from the optional [`device` object | `phoneNumber` field](*), which
+  therefore MUST be provided.
+  - When a three-legged access token is used however, this optional identifier 
+  MUST NOT be provided, as the subject will be uniquely identified from the access
+  token.
 
-  #### Optional device identifying headers for 3-legged tokens:
+  This approach simplifies API usage for API consumers using a three-legged access
+  token to invoke the API by relying on the information that is associated with the
+  access token and was identified during the authentication process.
 
-  - When using a 3-legged access token, the device associated with the access
-    token must be considered as the device for the API request. This means that
-    a device  identifying header  is not required in the request, and if
-    included it must identify the same device, therefore **it is recommended
-    NOT to include it in these scenarios** to simplify the API usage and avoid
-    additional validations.
+  ## Error handling:
 
-  #### Validation mechanism:
+  - If the subject cannot be identified from the access token and the optional `device`
+  object is not included in the request, then the server will return an error with the 
+  `422 MISSING_IDENTIFIER` error code.
 
-  - The server will extract the device identification from the access token, if
-    available.
-  - If the API request additionally includes a `device`  identifying header
-    when using a 3-legged access token, the API will validate that the device
-    identifier provided matches the one associated with the access token.
-  - If there is a mismatch, the API will respond with a
-    403 `INVALID_TOKEN_CONTEXT` error, indicating that the device information
-    in the request does not match the token.
-
-  #### Error handling for unidentifiable devices:
-
-  - If the `device`  identifying header is not included in the request and the
-    device information cannot be derived from the 3-legged access token, nor
-    inferred by the operator if the request is made directly from the client,
-    the server will return a 422 `UNIDENTIFIABLE_DEVICE` error.
-
-  #### Restrictions for tokens without an associated authenticated identifier:
-
-  - For scenarios which do not have a single device identifier associated to
-    the token during the authentication flow, e.g. 2-legged access tokens, a
-    `device` identifying header MUST be provided in the API request. This
-    ensures that the device identification is explicit and valid for each API
-    call made with these tokens.
+  - If the subject can be identified from the access token and the optional `device`
+  object is also included in the request, then the server will return an error with the
+  `422 UNNECESSARY_IDENTIFIER` error code. This will be the case even if the same device
+  is identified by these two methods, as the server is unable to make this comparison.
 
   # Responses