Submission Walkthrough 2: Creating an item with POST - sgpinkus/json-schema GitHub Wiki

Say we have a Link Description Object:

{
    "href": "http://example.com/items",
    "rel": "create",
    "method": "POST",
    "encType": "application/json",
    "schema": {
        "type": "object",
        "properties": {
            "title": {
                "title": "Item title",
                "type": "string"
            },
            "message": {
                "title": "Message",
                "description": "A plain-text message",
                "type": "string"
            }
        },
        "additionalProperties": false
    }
}

This link represents a URI allowing us to create a new item (which would then presumably be included in any subsequent GET request to http://example.com/items).

So, to use the link properly, we assemble some data that follows the schema described in the schema property:

{
    "title": "Hello, world!",
    "message": "Test message"
}

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/json, which is the media type for JSON documents.

So the encoding of our submission data using this scheme is exactly what we had above:

{
    "title": "Hello, world!",
    "message": "Test message"
}

Since our method is "POST", the appropriate place for us to put this data is in the POST body of the request. So to follow this link, we make an HTTP POST request to "http://example.com/items". The POST data submitted will be the JSON representation listed above, and the Content-Type header of our HTTP request will have the value of application/json, to reflect the format we have used to encode the data.

The raw request sent to the server should look like this:

POST /items HTTP/1.1
Host: example.com
User-Agent: Mozilla/4.0
Content-Length: 63
Content-Type: application/json

{
    "title": "Hello, world!",
    "message": "Test message"
}

The POST body is simply a string, and the data it represents can use any encoding.

However, a common encoding for POST request data (and the one used by default in HTML forms) is application/x-www-form-urlencoded (the same format used in HTTP query strings). If the Link Description Object specifies an encType of application/json, it is a mistake to simply include the JSON string as a value in an HTML form. If I submitted the JSON string representing my data as part of an HTML form, then the raw request would look something like this:

POST /items HTTP/1.1
Host: example.com
User-Agent: Mozilla/4.0
Content-Length: 126
Content-Type: application/x-www-form-urlencoded

data=%7B%0A%20%20%20%20%22title%22%3A%20%22Hello%2C%20world!%22%2C%0A%20%20%20%20%22message%22%3A%20%22Test%20message%22%0A%7D

This is not correct.