In the case of limited support for POST in the HTTP client software where pure data cannot be submitted in the HTTP message body, RESTfm is able to handle data encoded in either application/x-www-form-urlencoded or multipart/form-data formats.

Note: The application/x-www-form-urlencoded and multipart/form-data formats are only applicable to the HTTP POST method (and not GET, PUT or DELETE).

Note 2: Only the application/x-www-form-urlencoded format is described here. This format uses the same 'URL encoding' scheme as required for GET query string parameters as described here.

Advantages

  • Support for larger data size than what is possible using a GET query string.

Limitations

  • Will not work for field names that begin with 'RFM', as these are reserved words for RESTfm query string parameters.
    Note: There is work-around where another format (e.g. JSON) may be embedded into a single RFMdata field. See section on embedding other formats below.

Examples

Layout URI - JSON - POST Response

http://demo.restfm.com/RESTfm/postcodes/layout/brief%20postcodes.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
    "data": [
        {
            "Pcode": "9999",
            "Locality": "A New Location",
            "State": "",
            "Comments": ""
        }
    ],
    "meta": [
        {
            "recordID": "5884344",
            "href": "\/RESTfm\/postcodes\/layout\/brief%20postcodes\/5884344.json"
        }
    ],
    "info": {
        "X-RESTfm-Version": "2.0.1\/r280",
        "X-RESTfm-Protocol": "4",
        "X-RESTfm-Status": 201,
        "X-RESTfm-Reason": "Created",
        "X-RESTfm-Method": "POST"
    }
}
Example JSON format HTTP POST response.

Embedding other formats

RESTfm allows data in a different format (say XML, JSON, or your custom format) to be embedded into a single RFMdata field inside of an application/x-www-form-urlencoded or multipart/form-data message.

Advantages

  • No clashing of name space for field names that begin with 'RFM'.
  • Support for bulk operations where multiple records may be included in the one HTTP transaction.

Limitations

  • Additional encoding requirements.

Required parameters

RFMformat=<name>

Specify format of embedded data.

RFMdata=<encoded data> Embedded data of specified format. Must be "URL encoded" in addition to specified format.

Examples

Original JSON message to create two new records:

Bulk URI - JSON - POST Message

1
2
3
4
5
6
7
8
9
10
11
12
{
    "data": [
        {
            "Pcode": "9998",
            "Locality": "A New Location 1"
        },
        {
            "Pcode": "9999",
            "Locality": "A New Location 2"
        }
    ]
}
Example bulk JSON format CREATE message.

The above JSON message is then URL encoded and embedded into a x-www-form-urlencoded POST message as the RFMdata parameter.
Note: Both the RFMformat and RFMdata parameters are required

Layout URI - x-www-form-urlencoded embedded JSON - POST Message

1
RFMformat=JSON&RFMdata=%7B%22data%22%3A%5B%7B%22Pcode%22%3A%229998%22%2C%22Locality%22%3A%22A%20New%20Location%201%22%7D%2C%7B%22Pcode%22%3A%229999%22%2C%22Locality%22%3A%22A%20New%20Location%202%22%7D%5D%7D
Example JSON format Bulk message embedded into an x-www-form-urlencoded POST message.

Response when message is POSTed:

Bulk URI - JSON - POST Response

http://demo.restfm.com/RESTfm/postcodes/bulk/brief%20postcodes.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
{
    "meta": [
        {
            "recordID": "9913809"
        },
        {
            "recordID": "9913810"
        }
    ],
    "data": [
        {
            "Pcode": "9998",
            "Locality": "A New Location 1",
            "State": "",
            "Comments": ""
        },
        {
            "Pcode": "9999",
            "Locality": "A New Location 2",
            "State": "",
            "Comments": ""
        }
    ],
    "info": {
        "X-RESTfm-Version": "3.0.0beta\/r420",
        "X-RESTfm-Protocol": "4",
        "X-RESTfm-Status": 200,
        "X-RESTfm-Reason": "OK",
        "X-RESTfm-Method": "POST"
    },
    "metaField": [
        {
            "name": "Pcode",
            "autoEntered": 0,
            "global": 0,
            "maxRepeat": 1,
            "resultType": "text"
        },
        {
            "name": "Locality",
            "autoEntered": 0,
            "global": 0,
            "maxRepeat": 1,
            "resultType": "text"
        },
        {
            "name": "State",
            "autoEntered": 0,
            "global": 0,
            "maxRepeat": 1,
            "resultType": "text"
        },
        {
            "name": "Comments",
            "autoEntered": 0,
            "global": 0,
            "maxRepeat": 1,
            "resultType": "text"
        }
    ]
}
Example bulk JSON format CREATE response.