Submission Walkthrough 1: simple search - sgpinkus/json-schema GitHub Wiki

Say we have a Link Description Object:

{
    "href": "http://example.com/search",
    "rel": "search",
    "method": "GET",
    "encType": "application/x-www-form-urlencoded",
    "schema": {
        "type": "object",
        "properties": {
            "searchText": {
                "type": "string",
                "required": true
            },
            "resultsPerPage": {
                "enum": [10, 20, 30, 50, 100],
                "default": 20
            }
        },
        "additionalProperties": false
    }
}

This link represents a URI for some kind of search service. However, just making a GET request to http://example.com/search will not get us what we want, because the server will not know what we are looking for.

So, to use the link properly, we assemble some data that follows the schema described in the schema property: (note that the resultsPerPage property is optional)

{
    "searchText": "foo bar",
    "resultsPerPage": 30
}

Now we are ready to use our link, but how do we communicate this data to the server? The answer lies in the encType property of the link description object.

The encType property determines the encoding scheme for our data. In this case, it is application/x-www-form-urlencoded - this is the format used in query strings, such as ?foo=bar&baz=qux.

So the encoding of our submission data using this scheme is searchText=foo%20bar&resultsPerPage=30.

Since our method is "GET", the appropriate place for us to put this data is in the query string. So to follow this link, using our custom-made data, we end up making a GET request to the URI: "http://example.com/search?searchText=foo%20bar&resultsPerPage=30".

Making a request to this URI (including the query string) correctly communicates our search requirements to the server, so it can return an appropriate response.