URL Query Parameters

URL query parameters have been added as a feature to support queries through the API. They work by assigning a value to a key within the URL, in the format ?key=value, and this string is then passed in as parameters to the API's function. They also work within encoded URLs.

To use URL query parameters:

1. In the pronghorn.json, define a parameter with type 'object'. This object will include all query parameters.
2. Add all properties to access via the URL as properties inside the schema. Include a data type so the URL parameter is correctly parsed.
3. Determine if any parameters are required, such as when no default value is specified. If these required parameters are not included, the API return will error.
4. Reference the query parameters in the function as properties of the originally defined object parameter.

Example pronghorn.json method input:

{
    "input": [
        {
            "type": "object",
            "name": "queryParameters",
            "description": "description of query parameters",
            "schema": {
                "type": "object",
                "properties": {
                    "stringField": {
                        "type": "string"
                    },
                    "numberField": {
                        "type": "integer"
                    },
                    "booleanField": {
                        "type": "boolean"
                    },
                    "arrayField": {
                        "type": "array"
                    },
                    "objectField": {
                        "type": "object"
                    }
                },
                "required": [
                    "stringField",
                    "numberField",
                    "objectField"
                ]
            }
        }
    ]
}

Example function call:

    http://example_url/route?stringField=hello&numberField=7&booleanField=true&objectField[key]=value

Example object passed into function:

    {
        "stringField": "hello",
        "numberField": 7,
        "booleanField": true,
        "objectField": {
            "key": "value"
        }
    }

While using objects in URLs is not recommended, it can be done one of two ways:

1. In the notation of a JSON string, such as:

       ?objectField={"key":"value"}
   

2. In square-brackets notation, such as:

       ?objectField[key]=value
   

Order of Operations

It is important to note that if parameters are passed in through both the request body and the URL query string, it will prioritize the request body and completely ignore the query parameters. In the following case, the value of the string parameter will be "world".

    {
        "options": {
            "string": "world"
        }
    }

    URL: http://example_url?string=hello

These URL query parameters can be used for all request types, such as POST, GET, DELTE, and PUT, although it is recommended to use mainly with GET requests.