Implement a paradigm for implementing search endpoints for the SDK and CLI

[devraj]

Is your feature request related to a problem? Please describe. Search is a common feature around the API and has two main characteristics:

• They have the ability to return partial payloads (so do some other detail endpoints, see #20)
• Provide sensible search filters

Describe the solution you'd like Provide a standardised way to implement search among all the endpoints that support it. In particular we want to:

• Reduce the amount of endpoint specific code and do as much in the core endpoint
• Ability to provide metadata to the CLI or other user facing interfaces to draw from

I suggest implementing an end to end solution for two of the endpoints to prove the use case and the requirements e.g:

• [ ] Card types
• [ ] Cardholders

Consider leaving attribute filtering out of the initial solution to keep things relatively simple.

Describe alternatives you've considered NA

Additional context There are certain parameters like name that support sql like syntax:

Limits the returned items to those with a name that matches this string. Without surrounding quotes or a percent sign or underscore, it is a substring match; surround the parameter with double quotes "..." for an exact match. Without quotes, a percent sign % will match any substring and an underscore will match any single character.

We should ensure that those parameters are sanitised before they are sent through to the REST API.

Checklist of the various endpoints that support search, for implementation reference:

• [x] Cardholders
• [ ] Card types
• [ ] Competencies
• [ ] Access groups
• [ ] Operator groups
• [ ] PDF definitions
• [ ] Receptions
• [ ] Redactions
• [ ] Roles
• [ ] Visits
• [ ] Events
• [ ] Items
• [ ] Access Zones
• [ ] Alarm Zones
• [ ] Day categories
• [ ] Doors
• [ ] Elevator groups
• [ ] Fence zones
• [ ] Inputs
• [ ] Interlock groups
• [ ] Macros
• [ ] Outputs
• [ ] Schedules

Sample interaction with httpie:

(gallagher-py3.11) ➜  gallagher git:(alpha-5) ✗ task debug:get -- "card_types/?name=mobile"
task: [debug:get] http get \
https://commandcentre-api-au.security.gallagher.cloud/api/'card_types/?name=mobile' \
"Authorization: GGL-API-KEY $GACC_API_KEY"

HTTP/1.1 200 OK
Cache-Control: no-cache
Content-Length: 406
Content-Type: application/json; charset=utf-8
Date: Thu, 04 Jul 2024 12:31:04 GMT

{
    "results": [
        {
            "availableCardStates": [
                "Active",
                "Disabled (manually)",
                "Lost",
                "Stolen",
                "Damaged"
            ],
            "credentialClass": "mobile",
            "defaultExpiry": {
                "expiryType": "none"
            },
            "facilityCode": "P61405",
            "href": "https://commandcentre-api-au.security.gallagher.cloud/api/card_types/9640",
            "id": "9640",
            "initialCardState": "Active",
            "issueLevel": 1,
            "name": "Mobile Credential",
            "sendRegistrationEmail": true,
            "sendRegistrationSms": true
        }
    ]
}