Describe validation API response

[praseodym]

No description provided.

[praseodym]

Example response for /api/polling_stations/{id}/data_entries/{entry_number}:

{
  "saved": true,
  "message": "Data entry saved successfully",
  "validation_results": {
    "errors": [
      {
        "field_name": "data.voters_counts.poll_card_count",
        "code": "OutOfRange"
      },
      {
        "field_name": "data.voters_counts.total_admitted_voters_count",
        "code": "IncorrectTotal"
      }
    ],
    "warnings": []
  }
}

Open questions:

1. Do we need a message for general response status, or should we use a code instead?
2. For the validation results, is a code enough or do we also want a message?
3. Do we want to structure warnings and errors like this, or make one array and add a 'level' field describing whether this is an error or warning?

[jorisleker]

      {
        "field_name": "data.voters_counts.total_admitted_voters_count",
        "code": "IncorrectTotal"
      }

Zou field_name niet een array moeten zijn? Het voorbeeld dat je hier geeft (IncorrectTotal) is het resultaat van een optelling. Dan willen we in principe alle velden in de optelling highlighten, en niet alleen het resultaat. Als A+B+C != D, weet je namelijk niet of A, B, C of D onjuist is overgenomen van het proces-verbaal.

[jorisleker]

And re:3;
In the current setup we will either have errors or warnings, not both at the same time. As we will never have a combination, I think it makes sense to structure them the way you suggest. Otherwise you would have to deduce wether the response is an error or warning by evaluating the first validation_result, and assume all others are of the same type.

Alternative would be to add a top level 'validation_type' key

[jschuurk-kr]

Re:1: A code makes more sense to me, since I think that's easier to keep in sync between frontend and backend. That is assuming we don't use HTTP response status codes to communicate success/failure.

That does raise the question what kind of repsonse status code scheme we want to use and how it would differ from HTTP response status codes.

[jschuurk-kr]

re:2: Code in the response, so the frontend can determine the message shown to the user? Seems confusing to me to put a message in the response and show a different message in the UI.

[praseodym]

Zou field_name niet een array moeten zijn? Het voorbeeld dat je hier geeft (IncorrectTotal) is het resultaat van een optelling. Dan willen we in principe alle velden in de optelling highlighten, en niet alleen het resultaat. Als A+B+C != D, weet je namelijk niet of A, B, C of D onjuist is overgenomen van het proces-verbaal.

Valid point, we could turn it into an array. I assumed the frontend would have some knowledge of these validation rules too so it could highlight other relevant fields, but maybe an array would make more sense.

Re:1: A code makes more sense to me, since I think that's easier to keep in sync between frontend and backend. That is assuming we don't use HTTP response status codes to communicate success/failure.

That does raise the question what kind of repsonse status code scheme we want to use and how it would differ from HTTP response status codes.

HTTP response status codes don't cover every scenario, but I think would be a good start. I agreed with @lkleuver that it would be useful to always have a response body too.

re:2: Code in the response, so the frontend can determine the message shown to the user? Seems confusing to me to put a message in the response and show a different message in the UI.

Agreed, this would mostly be for the developer. Do we want to create a specific code for each specific validation rule, or would several generic ones (e.g. IncorrectTotal) suffice?

[jschuurk-kr]

Do we want to create a specific code for each specific validation rule, or would several generic ones (e.g. IncorrectTotal) suffice?

Several generic ones would suffice, I think. There aren't that many, they aren't that complicated, we have them documented in the use cases, it's not a public API. So we can assume some domain knowledge.

And if field_name is an array, that together with a code like IncorrectTotal fully describes the error/warning. (Well not fully, since you have to know which fields need to add up to the totals field.)

[jschuurk-kr]

A specific code for each specific validation rule could be useful in the future if/when we implement analytics. That doesn't mean we have to use those same codes in the API, though.

[jschuurk-kr]

@lkleuver ☝️

[praseodym]

New example:

Request:

POST http://localhost:8080/api/polling_stations/1/data_entries/12
Content-Type: application/json
Content-Length: 360
Accept: */*

{
  "data": {
    "voters_counts": {
      "poll_card_count": 2000000000,
      "proxy_certificate_count": 50,
      "voter_card_count": 75,
      "total_admitted_voters_count": 225
    },
    "votes_counts": {
      "votes_candidates_counts": 200,
      "blank_votes_count": 10,
      "invalid_votes_count": 15,
      "total_votes_cast_count": 225
    }
  }
}

Response:

HTTP/1.1 200 OK
content-type: application/json
content-length: 380
date: Tue, 14 May 2024 12:34:17 GMT

{
  "saved": true,
  "message": "Data entry saved successfully",
  "validation_results": {
    "errors": [
      {
        "fields": [
          "data.voters_counts.poll_card_count"
        ],
        "code": "OutOfRange"
      },
      {
        "fields": [
          "data.voters_counts.total_admitted_voters_count",
          "data.voters_counts.poll_card_count",
          "data.voters_counts.proxy_certificate_count",
          "data.voters_counts.voter_card_count"
        ],
        "code": "IncorrectTotal"
      }
    ],
    "warnings": []
  }
}

[lkleuver]

what is the test to see if the the request was a success?
check if errors is present and length > 0 ?

[Lionqueen94]

what is the test to see if the the request was a success? check if errors is present and length > 0 ?

I think errors is always present, right @praseodym ? so just checking if it has a length > 0 should be enough

[praseodym]

The request is a success when the response status code is 200 OK. In that case the response body will also contain "saved": true to indicate that the data entry has been saved to the database. This saved entry represents a temporary save that is not yet finalised by the user. It will be able to be retrieved at a later moment to resume data entry, e.g. if the user closed their browser (to be implemented).

validation_results contains errors and warnings related to the user's data entry. For example, an incorrect total value is an error, whereas a high number of blank votes is a warning. The presence of validation errors/warnings does not indicate a server issue or a failure to save these values. However, the presence of errors will impact the user's ability to finalise the data entry (to be implemented).

[praseodym]

Implemented in #42 according to this design. The OpenAPI specification is leading.