Parking Management System

The Whitelist service is used to create access permissions for targeted license plates or a regex pattern.

Open costs for this license plate are canceled.

Accesses are active until they are deleted manually.

# Prerequisites

  • The Whitelist App must be installed for the parking space
  • The parking space must be online for accesses to be created or deleted
  • For [Service Accounts](https://youtrack.acc.si/articles/Service Accounts & OAuth) only:
    • The Service Account has the required permissions
    • Bearer token has the scope iam.sa
    • Bearer token has the audience whitelist.acc.si

# API

To communicate with the API a [Service Account](https://youtrack.acc.si/articles/Service Accounts & OAuth) is required.

The API features three types of accesses:

  • License plates
  • Regexes (Sonderkennzeichen)
  • [QR Codes (Handaufkarte)](https://youtrack.acc.si/articles/Link wurde nicht gefunden#handauf)

The endpoints respectively are:

  • /api/whitelist/accesses/<resource-id>/
  • /api/whitelist/regex/<resource-id>/
  • /api/whitelist/qr/<resource-id>/

# License plate

# Viewing active accesses

  • Is a GET request
  • Staging/Development endpoint: https://garage.arivo.fun/api/whitelist/access/resource-id/ (opens new window) (replace resource-id with your resource id)
  • The response is a list of all accesses for this parking space
  • Example using the curl command line tool (Bearer token is redacted. resource-id and access values are examples only):

    • Request:

      curl -X GET "https://garage.arivo.fun/api/whitelist/access/arivo-parking-1/" -H "Authorization: Bearer ***"

    • Response:

      [{ 
  "resource":"arivo-parking-1","license_plate":"GARIVO","country":"A",
  "comment":"","access_id":"13d38e10-2ede-4aab-81cd-19d8a89255bd"
}]
  • Details for a single access can be requested by appending the access_id at the end of the url. (https://garage.arivo.fun/api/whitelist/access/resource-id/access-id/ (opens new window) (replace resource-id and access-id with the actual IDs.))

# Creating an access

  • Is a POST request
  • Staging/Development endpoint: https://garage.arivo.fun/api/whitelist/access/resource-id/ (opens new window) (replace resource-id with your resource id)
  • The body includes the following data:
    • license_plate: <Your license plate> license plates can only include alphanumeric characters and ÄÖÜ. A regex pattern has no such restriction.
    • country: <country code for the license plate> e.g. "D". Required for license plates. Not allowed for regex patterns.
    • comment: <A comment> Free space to include additional information about the access. Does not affect the access itself.
  • The combination of resource-id, license_plate and country must be unique
  • The response includes the newly created access. Especially the field access_id is of interest. It is the unique ID for this access
  • Example using the curl command line tool (Bearer token is redacted. resource-id and access values are examples only):

    • Request:

      curl -X POST "https://garage.arivo.fun/api/whitelist/access/arivo-parking-1/" \
-H "Authorization: Bearer ***" \
-H "Content-Type: application/json" \
-d '{"license_plate": "GARIVO", "country": "A"}'

    • Response:

      {
  "resource":"arivo-parking-1","license_plate":"GARIVO","country":"A","regex":false,
  "comment":"","access_id":"13d38e10-2ede-4aab-81cd-19d8a89255bd"
}

# Deleting an access

  • Is a DELETE request

  • Staging/Development endpoint: https://garage.arivo.fun/api/whitelist/access/resource-id/access-id/ (opens new window) (replace resource-id and access-id with the actual IDs)

  • The access_id is required here

  • The response is empty

  • Example using the curl command line tool (Bearer token is redacted. resource-id and access values are examples only):

    curl -X DELETE \
  "https://garage.arivo.fun/api/whitelist/access/arivo-parking-1/13d38e10-2ede-4aab-81cd-19d8a89255bd/" \
  -H "Authorization: Bearer ***"

# Changing a comment

  • Only comments can be changed. To change a different field a new access needs to be created instead.
  • Is a PATCH request
  • Staging/Development endpoint: https://garage.arivo.fun/api/whitelist/access/resource-id/access-id/ (opens new window) (replace resource-id and access-id with the actual IDs)
  • The response includes the changed access
  • Example using the curl command line tool (Bearer token is redacted. resource-id and access values are examples only):

    • Request:

      curl -X PATCH \
  "https://garage.arivo.fun/api/whitelist/access/arivo-parking-1/13d38e10-2ede-4aab-81cd-19d8a89255bd" \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{"comment":"This is an example"}'

    • Response:

      {
  "resource":"arivo-parking-1","license_plate":"GARIVO","country":"A","regex":false,
  "comment":"This is an example","access_id":"13d38e10-2ede-4aab-81cd-19d8a89255bd"
}

# Regexes

# Viewing active regexes accesses (Sonderkennzeichen)

  • Is a GET request
  • Staging/Development endpoint: https://garage.arivo.fun/api/whitelist/regex/resource-id/ (opens new window) (replace resource-id with your resource id)
  • The response is a list of all accesses for this parking space
    • Int the field simple_regexes there are the regexes displayed in their simple representation
    • For predefined regexes the comment field always hold the translated value of the Sonderkennzeichen name
  • Example using the curl command line tool (Bearer token is redacted. resource-id and access values are examples only):

    • Request:

      curl -X GET "https://garage.arivo.fun/api/whitelist/regex/reverent-fermi-7/" -H "Authorization: Bearer ***"

    • Response:

      [
    {
        "access_id": "4877686c-d5ce-4c3f-8dc3-5270bdcc27ff",
        "resource": "reverent-fermi-7",
        "regexes": [
            "^LE.+$"
        ],
        "regex_type": "custom",
        "country": "A",
        "comment": "Leben fährt gratis",
        "created": "2023-09-14T10:14:06.218472Z",
        "simple_regexes": [
            "LE***"
        ],
        "custom_type": "startswith",
        "predefined_id": null
    },
    {
        "access_id": "897dcd99-02ea-4cb9-877c-f93338e2a9f8",
        "resource": "reverent-fermi-7",
        "regexes": [
            "^.+2$"
        ],
        "regex_type": "custom",
        "country": "A",
        "comment": "Der Fake Bus fährt gratis",
        "created": "2023-09-14T10:18:07.622570Z",
        "simple_regexes": [
            "***2"
        ],
        "custom_type": "endswith",
        "predefined_id": null
    },
    {
        "access_id": "b77aece9-3b42-43df-b041-f08275cd00ca",
        "resource": "reverent-fermi-7",
        "regexes": [
            "ZE\\s+TTEL\\s+\\d+"
        ],
        "regex_type": "custom",
        "country": "A",
        "comment": "Wisch",
        "created": "2023-09-14T10:24:13.726366Z",
        "simple_regexes": [
            "ZE\\s+TTEL\\s+\\d+"
        ],
        "custom_type": "regex",
        "predefined_id": null
    },
    {
        "access_id": "3bab2d90-1f68-4baa-a785-bd38dd91c199",
        "resource": "reverent-fermi-7",
        "regexes": [
            "^[A-Z]{1,2}[\\s\\-.]?[0-9\\s\\-.]+RD$",
            "^[A-Z]{1,2}[\\s\\-.]?[0-9\\s\\-.]+RK$"
        ],
        "regex_type": "predefined",
        "country": "A",
        "comment": "Rettung",
        "created": "2023-09-01T07:45:27.293841Z",
        "simple_regexes": [
            "[XY][123...]RD",
            "[XY][123...]RK"
        ],
        "custom_type": null,
        "predefined_id": "at-emergency-ambulance"
    },
    {
        "access_id": "145e076d-a451-42dd-8d36-1ed7051092ce",
        "resource": "reverent-fermi-7",
        "regexes": [
            "^BP[\\s\\-.]?[0-9\\s\\-.]+$"
        ],
        "regex_type": "predefined",
        "country": "A",
        "comment": "Bundespolizei",
        "created": "2023-09-14T10:15:43.082588Z",
        "simple_regexes": [
            "BP[123...]"
        ],
        "custom_type": null,
        "predefined_id": "at-federal-police"
    }
]

# Deleting an regex access

  • Is a DELETE request

  • Staging/Development endpoint: https://garage.arivo.fun/api/whitelist/regex/resource-id/access-id/ (opens new window) (replace resource-id and access-id with the actual IDs)

  • The access_id is required here

  • The response is empty

  • Example using the curl command line tool (Bearer token is redacted. resource-id and access values are examples only):

    curl -X DELETE \
  "https://garage.arivo.fun/api/whitelist/regex/reverent-fermi-7/4ef54452-3e5c-4bcb-9f6d-e0d76d421fbb/" \
  -H "Authorization: Bearer ***"

# Creating an regex access

For creating an regex access there are two endpoints available:

  • /api/whitelist/regex/predefined/<resource-id>/
  • /api/whitelist/regex/custom/<resource-id>/

This endpoints are used to create an predefined access or an custom regex.

# Predefined regex

The predefined endpoint supports two HTTP methods:

  • GET
  • POST

Where the GET method is used to get the current list of predefined regexes, at of this moment only Austrian predefined accesses are available.

# Get list of predefined accesses
  • Is a GET request
  • Staging/Development endpoint: https://garage.arivo.fun//api/whitelist/regex/predefined/resource-id/ (opens new window) (replace resource-id with your resource id)
  • The response is a list of all predefined regexes
  • Example using the curl command line tool (Bearer token is redacted. resource-id and access values are examples only):

    • Request:

      curl -X GET "https://garage.arivo.fun/api/whitelist/regex/predefined/reverent-fermi-7/" -H "Authorization: Bearer ***"

    • Response:

      [
    {
        "id": "at-emergency-ambulance",
        "name": "Rettung",
        "country": "A",
        "simple_regexes": [
            "[XY][123...]RD",
            "[XY][123...]RK"
        ]
    },
    {
        "id": "at-austrian-armed-forces",
        "name": "Bundesheer",
        "country": "A",
        "simple_regexes": [
            "BH[123...]"
        ]
    },
    ...
]
# Add a predefined regex
  • Is a POST request
  • Staging/Development endpoint: https://garage.arivo.fun/api/whitelist/regex/predefined/resource-id/ (opens new window) (replace resource-id with your resource id)
  • The body includes the following data:
    • id: <Id of the predefined access>
    • country: <country code of the predefined regex>
  • The combination of resource-id, predefined id and country must be unique
  • The response includes the newly created access. Especially the field access_id is of interest. It is the unique ID for this access
  • Example using the curl command line tool (Bearer token is redacted. resource-id and access values are examples only):

    • Request:

      curl -X POST "https://garage.arivo.fun/api/whitelist/access/arivo-parking-1/" \
-H "Authorization: Bearer ***" \
-H "Content-Type: application/json" \
-d '{"id": "at-fire-department", "country": "A" }'

    • Response:

      {
    "access_id": "212b671b-1776-4299-b534-5b7af20baf55",
    "resource": "reverent-fermi-7",
    "regexes": [
        "^FW[\\s\\-.]?[0-9\\s\\-.]+$"
    ],
    "regex_type": "predefined",
    "country": "A",
    "comment": "Feuerwehr",
    "created": "2023-09-18T12:58:04.929093Z",
    "simple_regexes": [
        "FW[123...]"
    ],
    "custom_type": null,
    "predefined_id": "at-fire-department"
}

# Custom regex

The custom regex endpoint supports three types of custom regex:

  • startswith: Custom regex has to start with pattern
  • endswith: Custom regex has to end with pattern
  • regex: The pattern has to be a valid regex

Creating a custom regex:

  • Is a POST request
  • Staging/Development endpoint: https://garage.arivo.fun//api/whitelist/regex/custom/resource-id/ (opens new window) (replace resource-id with your resource id)
  • The body includes the following data:
    • custom_type: <see above definition>
    • pattern: <the pattern of the regex>
    • country: <country code of the custom regex>
    • comment: <has to present to display what the regex matches for non technical personal>
  • The combination of resource-id, predefined id and country must be unique
  • The response includes the newly created access. Especially the field access_id is of interest. It is the unique ID for this access
  • Example using the curl command line tool (Bearer token is redacted. resource-id and access values are examples only):

    • Request:

      curl -X POST "https://garage.arivo.fun/api/whitelist/regex/custom/reverent-fermi-7/" \
-H "Authorization: Bearer ***" \
-H "Content-Type: application/json" \
-d '{custom_type: "startswith", comment: "Test Sonderkennzeichen", pattern: "ABC", country: "A"}'

    • Response:

      {
    "access_id": "4ef54452-3e5c-4bcb-9f6d-e0d76d421fbb",
    "resource": "reverent-fermi-7",
    "regexes": [
        "^ABC.+$"
    ],
    "regex_type": "custom",
    "country": "A",
    "comment": "Test Sonderkennzeichen",
    "created": "2023-09-18T12:59:21.867500Z",
    "simple_regexes": [
        "ABC***"
    ],
    "custom_type": "startswith",
    "predefined_id": null
}

# QR Code (Handaufkarte)

# Viewing active qr code accesses

  • Is a GET request
  • Staging/Development endpoint: https://garage.arivo.fun//api/whitelist/qr/resource-id/ (opens new window) (replace resource-id with your resource id)
  • The response is a list of all accesses for this parking space
  • Example using the curl command line tool (Bearer token is redacted. resource-id and access values are examples only):

    • Request:

      curl -X GET "https://garage.arivo.fun//api/whitelist/qr/reverent-fermi-7/" -H "Authorization: Bearer ***"

    • Response:

      [
    {
        "resource": "reverent-fermi-7",
        "comment": null,
        "access_id": "1438bf7f-1962-4e5d-9561-aafd72adeae4",
        "created": "2023-09-14T10:27:55.746582Z",
        "name": "Open Sesame",
        "payload": "hak_TgJJl5YxdgV91ruD4VLXIJVrVdA9op0v"
    }
]

# Creating an qr access

  • Is a POST request
  • Staging/Development endpoint: https://garage.arivo.fun/api/whitelist/qr/resource-id/ (opens new window) (replace resource-id with your resource id)
  • The body includes the following data:
    • name: <name of the qr code>
    • comment: <A comment> Free space to include additional information about the access. Does not affect the access itself.
  • The response includes the newly created access. Especially the field access_id is of interest. It is the unique ID for this access
  • Example using the curl command line tool (Bearer token is redacted. resource-id and access values are examples only):

    • Request:

      curl -X POST "https://garage.arivo.fun/api/whitelist/qr/reverent-fermi-7/" \
-H "Authorization: Bearer ***" \
-H "Content-Type: application/json" \
-d '{name: "Handaufkarte", comment: "Testing"}'

    • Response:

      {
    "resource": "reverent-fermi-7",
    "comment": "Testing",
    "access_id": "2c43b7a3-ac7d-48d0-a579-6130089d4657",
    "created": "2023-09-18T13:33:57.469302Z",
    "name": "Handaufkarte",
    "payload": "hak_JKw83Qtkhnp3Ou6Y1ffjs39N2Y7kythD"
}

# Deleting an qr access

  • Is a DELETE request

  • Staging/Development endpoint: https://garage.arivo.fun//api/whitelist/qr/reverent-fermi-7/resource-id/access-id/ (opens new window) (replace resource-id and access-id with the actual IDs)

  • The access_id is required here

  • The response is empty

  • Example using the curl command line tool (Bearer token is redacted. resource-id and access values are examples only):

    curl -X DELETE \
  "https://garage.arivo.fun/api/whitelist/qr/reverent-fermi-7/2c43b7a3-ac7d-48d0-a579-6130089d4657/" \
  -H "Authorization: Bearer ***"

# Error messages

If the response status code is not between 200 and 299 the request failed.

In many cases the response includes a JSON object detailing the error.

# Resource not connected

  • status code is 456
  • The JSON object includes the following keys and values:
    • "error": "device_offline"
    • "detail": "offline" or "shutdown"

# Other 456 Errors

  • 456 Errors are Internal errors with a predefined JSON structure:
    • "error": <error source>
    • "detail": <error code>

# Management commands

The whitelist service supports two Django management commands:

  • sync_resource <resource-id>: Triggers a full sync for given resource
  • sync_all_predefined_regexes: Updates all predefined regexes in the database and syncs all resources where the regexes where updated

←