Overhaul tracker keys

[josecelano]

• Overhaul tracker keys: upload pre-generated keys #974. Relates to: qstion #771
• Overhaul tracker keys: allow permanent keys #979
• Overhaul tracker keys: option to disable auth key expiration #978
• Overhaul tracker keys: add more tests #989

Related issues

• Bug: tracker keys can contain any char not only alphanumeric chars #976

[josecelano]

What I'm going to do is to add a new endpoint and deprecate the current endpoint to generate keys POST /api/v1/key/:seconds_valid_or_key.

The new endpoint can be used for both tasks: generate a random key or upload a pre-existing key. The key field in the POSTed form is optional. If it's not provided the system will generate a new random key.

URL: POST /api/v1/keys

Upload Pre-existing Key

Request body:

{
  "key": "pre_existing_key",
  "seconds_valid": 3600
}

If seconds_valid is 0 the key is permanent.

Create New Random Key

Request body:

{
  "seconds_valid": 3600
}

• If seconds_valid is 0 the key is permanent.
• The key field is not provided.

cc @da2ce7

[josecelano]

In the end, I changed the contract. Instead of omitting fields when they are not needed, you have to set them to null, so we always use the same JSON object.

curl -X POST http://localhost:1212/api/v1/keys?token=MyAccessToken \
     -H "Content-Type: application/json" \
     -d '{
     	   "key": null,
           "seconds_valid": null
         }'

ChatpGTP pros and cons for both options:

1. Omission of the Field

Pros:

• Simplicity: The JSON object is smaller and less cluttered because it only includes fields with actual data.
• Efficiency: Reduces the size of the JSON payload, which can be important for large datasets or when transmitting data over a network.
• Implicit Optionality: The absence of the field inherently indicates that it is optional, so there's no need for additional checks or processing.

Cons:

• Ambiguity: The absence of a field might not be clear if the field is optional or if it was accidentally omitted. Consumers of the JSON must be aware of which fields are optional.
• Schema Validation: If you're using a strict JSON schema for validation, omitted fields might require specific handling in the schema definition.
• Default Handling: If the field is omitted, the application needs to provide a default value or handle the absence explicitly, which could complicate code logic.

2. Null Value

Pros:

• Explicit Representation: By including the field with a null value, you're explicitly indicating that the field is intentionally left empty, not omitted by mistake.
• Schema Compatibility: Easier to validate against a JSON schema since the field is present, even if it's null.
• Consistency: The structure of your JSON object remains consistent, which can simplify processing, especially in typed languages or systems expecting consistent keys.

Cons:

• Payload Size: The JSON payload is slightly larger because it includes fields with null values.
• Null Handling: Code consuming the JSON must handle null values explicitly, which might require additional checks and handling logic.
• Semantic Overload: Using null may sometimes lead to confusion over whether the field is optional, should be ignored, or represents some other state (like an unknown value).

When to Use Each Approach:

• Omission is generally preferred when you want to keep the JSON object as lean as possible and the consumer can easily infer that the field is optional or has a default behavior when absent.
• Null Value is preferred when you want to be explicit about the field's existence but indicate that it currently holds no value, especially when working with systems that enforce schema validation or where the structure needs to remain consistent.

In summary, the choice between omission and using null depends on the specific use case, the importance of payload size, the need for explicitness, and how the JSON is consumed and validated.