[GitHub] [trafficcontrol] ocket8888 opened a new issue, #6943: Strange response formats from /profileparameters

[GitBox <gi...@apache.org>]

ocket8888 opened a new issue, #6943:
URL: https://github.com/apache/trafficcontrol/issues/6943

   ## This Improvement request (usability, performance, tech debt, etc.) affects these Traffic Control components:
   - Traffic Ops
   
   ## Current behavior:
   The type of the `response` properties of response bodies from POST requests to `/profileparameters` (in all API versions) are odd. If the array request format is used and multiple associations between Profiles and Parameters are created, then the response will be:
   ```json
   {
   	"alerts": [
   		{
   			"text": "profileParameters were created.",
   			"level": "success"
   		}
   	],
   	"response": null
   }
   ```
   
   When creating a single association, the response looks like:
   
   ```json
   {
   	"alerts": [
   		{
   			"text": "profileParameter was created.",
   			"level": "success"
   		}
   	],
   	"response": {
   		"lastUpdated": null,
   		"profile": null,
   		"profileId": 14,
   		"parameter": null,
   		"parameterId": 1
   	}
   }
   ```
   
   where presumably `lastUpdated` is meant to be the time of the association's creation, `profile` is probably meant to be the Name of the Profile identified by `profileId`, and `parameter` could possibly be the Name of the Parameter identified by `parameterId` (although that's not enough information to identify a Parameter). However, all of these properties are always `null`.
   
   GET requests return different representations of the associations, in the form:
   ```json
   {
   	"response": [
   		{
   			"lastUpdated": "2022-07-06 16:07:45+00",
   			"profile": "GLOBAL",
   			"parameter": 1
   		}
           ]
   }
   ```
   
   So Profiles are identified by Name and never ID - however the filtering query parameters offered by that endpoint do not allow filtering by Profile Name, only ID. Parameters, on the other hand are only presented as IDs, but use the property name `parameter` whereas the POST response uses the property name `parameterId` to represent the same information - and the query parameter offered by the endpoint to filter by Parameter ID is likewise `parameterId`. Note that in GET requests, `lastUpdated` is, properly, never `null`.
   
   ## New behavior:
   The representation used for an object should not vary so wildly between requests and responses and between request methods of the same endpoint. A single representation format must be chosen and used for all representations.
   
   According to the API guidelines, the response should be a representation of the created object(s). Therefore when something is created, `null` is always an unacceptable `response`.
   
   Likewise `null` is not a valid date/time value, so it is always unacceptable as a value for `lastUpdated`, and similarly there is no point in always returning `null` for pieces of information that are redundant (other identifiers exist; useless fields) and/or the information is knowable at the time of the request (which it is, in the case of POST requests as described above).
   
   Finally, though, the [API guidelines](https://traffic-control-cdn.readthedocs.io/en/latest/development/api_guidelines.html#relationships-as-objects) also state:
   
   > Relationships SHOULD NOT be represented through the API as objects in their own right.
   
   So this endpoint really should not exist at all, which would be a totally acceptable solution to this issue. Even if such an endpoint is desirable, I would hesitate to say that being able to make assignments of more than one distinct Parameter to more than one distinct Profile is an unintuitive UX at best, and is typically better accomplished using `/profiles/{{ID}}/parameters` and/or `/parameters/{{ID}}/profiles` instead. In the case of "bootstrapping" an environment e.g. for testing, the Profiles and Parameters must be created first anyway, so using Profile importing would be much easier and faster than using this method. Furthermore, for manipulating associations between Parameters and Profiles, we have
   
   - `/parameterprofile`
   - `/profileparameter`
   - `/profileparameters`
   - `/profileparameters/{{Profile ID}}/{{Parameter ID}}`
   - `/profiles/{{ID}}/parameters`
   - `/profiles/import` (kinda)
   - `/profiles/name/{{name}}/parameters`
   
   and I refuse to believe that all of these are necessary to accomplish whatever obscure task a user requires.
   
   This bug may be a regression, but at this point I'm not going to go back to Perl days to find out.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@trafficcontrol.apache.org.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org