search

maykinmedia / open-klant

Registratiecomponent voor de opslag en ontsluiting van klantgegevens volgens de Klantinteracties API-specificatie.
Other
2 stars 3 forks source link

Support multiple ways of serializating lists in query params #250

Open swrichards opened 1 month ago

swrichards commented 1 month ago

Thema / Theme

Klantinteracties API

Omschrijving / Description

Currently, and specifically in the expand query parameter, list values are expected to be serialized as a comma separated string (expand=expand=leiddeTotInterneTaken,hadBetrokkenen), but not in other commonly accepted formats, e.g.:

The feature request here would be to:

  1. support, at the very least, the multiple occurrence style in addition to the current default of the comma-separated style OR
  2. Raise an error for the repeated occurrence / bracket style

Demo

Comma-separated expand works as expected

GET /klantinteracties/api/v1/klantcontacten?expand=leiddeTotInterneTaken,hadBetrokkenen

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "uuid": "ecbaa74e-dfc6-4e69-bdaf-0cfc0efdc84f",
            // ...
            "_expand": {
                "hadBetrokkenen": [
                    {
                        "uuid": "3643c297-dc73-4152-a02b-3484268ffc91",
                        "url": "http://localhost:8338/klantinteracties/api/v1/betrokkenen/3643c297-dc73-4152-a02b-3484268ffc91",
                        "wasPartij": {
                            "uuid": "2e919767-b82c-4c13-83b7-2391bcbfdedb",
                            "url": "http://localhost:8338/klantinteracties/api/v1/partijen/2e919767-b82c-4c13-83b7-2391bcbfdedb"
                        },
                        "hadKlantcontact": {
                            "uuid": "ecbaa74e-dfc6-4e69-bdaf-0cfc0efdc84f",
                            "url": "http://localhost:8338/klantinteracties/api/v1/klantcontacten/ecbaa74e-dfc6-4e69-bdaf-0cfc0efdc84f"
                        },
                        "digitaleAdressen": [],
                        "bezoekadres": {
                            "nummeraanduidingId": "",
                            "adresregel1": "",
                            "adresregel2": "",
                            "adresregel3": "",
                            "land": ""
                        },
                        "correspondentieadres": {
                            "nummeraanduidingId": "",
                            "adresregel1": "",
                            "adresregel2": "",
                            "adresregel3": "",
                            "land": ""
                        },
                        "contactnaam": {
                            "voorletters": "",
                            "voornaam": "",
                            "voorvoegselAchternaam": "",
                            "achternaam": ""
                        },
                        "volledigeNaam": "",
                        "rol": "klant",
                        "organisatienaam": "Open Inwoner Platform",
                        "initiator": true
                    }
                ],
                "leiddeTotInterneTaken": [
                    {
                        "uuid": "5e3bccbf-bfdf-470d-b653-23f73a8c7b63",
                        "url": "http://localhost:8338/klantinteracties/api/v1/internetaken/5e3bccbf-bfdf-470d-b653-23f73a8c7b63",
                        "nummer": "0000000001",
                        "gevraagdeHandeling": "Vraag beantwoorden in aanleiding gevend klant contact",
                        "aanleidinggevendKlantcontact": {
                            "uuid": "ecbaa74e-dfc6-4e69-bdaf-0cfc0efdc84f",
                            "url": "http://localhost:8338/klantinteracties/api/v1/klantcontacten/ecbaa74e-dfc6-4e69-bdaf-0cfc0efdc84f"
                        },
                        "toegewezenAanActor": {
                            "uuid": "1f6a0f66-02a7-4a67-ab65-fcf63a25d214",
                            "url": "http://localhost:8338/klantinteracties/api/v1/actoren/1f6a0f66-02a7-4a67-ab65-fcf63a25d214"
                        },
                        "toelichting": "Beantwoorden vraag",
                        "status": "te_verwerken",
                        "toegewezenOp": "2024-09-24T14:05:11.108551Z",
                        "afgehandeldOp": null
                    }
                ]
            }
        }
    ]
}

Repeated key style defaults to last occurrence

GET /klantinteracties/api/v1/klantcontacten?expand=leiddeTotInterneTaken&expand=hadBetrokkenen

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "uuid": "ecbaa74e-dfc6-4e69-bdaf-0cfc0efdc84f",
             // ...
            "_expand": {
                "hadBetrokkenen": [
                    {
                        "uuid": "3643c297-dc73-4152-a02b-3484268ffc91",
                        "url": "http://localhost:8338/klantinteracties/api/v1/betrokkenen/3643c297-dc73-4152-a02b-3484268ffc91",
                        "wasPartij": {
                            "uuid": "2e919767-b82c-4c13-83b7-2391bcbfdedb",
                            "url": "http://localhost:8338/klantinteracties/api/v1/partijen/2e919767-b82c-4c13-83b7-2391bcbfdedb"
                        },
                        "hadKlantcontact": {
                            "uuid": "ecbaa74e-dfc6-4e69-bdaf-0cfc0efdc84f",
                            "url": "http://localhost:8338/klantinteracties/api/v1/klantcontacten/ecbaa74e-dfc6-4e69-bdaf-0cfc0efdc84f"
                        },
                        "digitaleAdressen": [],
                        "bezoekadres": {
                            "nummeraanduidingId": "",
                            "adresregel1": "",
                            "adresregel2": "",
                            "adresregel3": "",
                            "land": ""
                        },
                        "correspondentieadres": {
                            "nummeraanduidingId": "",
                            "adresregel1": "",
                            "adresregel2": "",
                            "adresregel3": "",
                            "land": ""
                        },
                        "contactnaam": {
                            "voorletters": "",
                            "voornaam": "",
                            "voorvoegselAchternaam": "",
                            "achternaam": ""
                        },
                        "volledigeNaam": "",
                        "rol": "klant",
                        "organisatienaam": "Open Inwoner Platform",
                        "initiator": true
                    }
                ]
            }
        }
    ]
}

Bracket notation is ignored entirely

GET /klantinteracties/api/v1/klantcontacten?expand[]=leiddeTotInterneTaken&expand[]=hadBetrokkenen

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "uuid": "ecbaa74e-dfc6-4e69-bdaf-0cfc0efdc84f",
            // ...
            "_expand": {}
        }
    ]
}

Toegevoegde waarde / Added value

Given that all three styles are seen in the wild and likely to be adopted by (low) level HTTP client implementations, it would make sense to support all styled out of the box.

Specifically, in this case, the params keyword argument used by Python requests by default serializes using the repeat occurrence serialization style, and it would be nice to support this functionality out of the box.

Aanvullende opmerkingen / Additional context

No response