Strange response formats from /profileparameters

[ocket8888]

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:

{
	"alerts": [
		{
			"text": "profileParameters were created.",
			"level": "success"
		}
	],
	"response": null
}

When creating a single association, the response looks like:

{
	"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:

{
	"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 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.