Guides

URL query parameters

URL query parameters allow you to pass values through the API via the URL in the format ?key=value. They also work within encoded URLs.

To use URL query parameters:

1

Define a query parameters object in pronghorn.json

In the pronghorn.json, define a parameter with type object. This object will contain all query parameters.

2

Add properties to the schema

Add all properties you want to access via the URL as properties inside the schema. Include a data type so the URL parameter is correctly parsed.

3

Define required parameters

Determine which parameters are required — for example, those with no default value. If required parameters are not included in the request, the API will return an error.

4

Reference query parameters in your function

Reference the query parameters in the function as properties of the originally defined object parameter.

Example pronghorn.json method input:

1{
2    "input": [
3        {
4            "type": "object",
5            "name": "queryParameters",
6            "description": "description of query parameters",
7            "schema": {
8                "type": "object",
9                "properties": {
10                    "stringField": {
11                        "type": "string"
12                    },
13                    "numberField": {
14                        "type": "integer"
15                    },
16                    "booleanField": {
17                        "type": "boolean"
18                    },
19                    "arrayField": {
20                        "type": "array"
21                    },
22                    "objectField": {
23                        "type": "object"
24                    }
25                },
26                "required": [
27                    "stringField",
28                    "numberField",
29                    "objectField"
30                ]
31            }
32        }
33    ]
34}

Example function call:

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

Example object passed into function:

1{
2    "stringField": "hello",
3    "numberField": 7,
4    "booleanField": true,
5    "objectField": {
6        "key": "value"
7    }
8}

Passing objects in URLs

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

  1. As a JSON string:

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

  2. In square-brackets notation:

    ?objectField[key]=value

Order of operations

If parameters are passed through both the request body and the URL query string, the request body takes priority and the query parameters are ignored entirely. In the following example, the value of the string parameter will be world:

1{
2    "options": {
3        "string": "world"
4    }
5}
URL: http://example_url?string=hello

URL query parameters can be used with all request types (POST, GET, DELETE, PUT), but are recommended primarily for GET requests.