REST.post: Difference between revisions
Jump to navigation
Jump to search
No edit summary |
|||
| (8 intermediate revisions by 4 users not shown) | |||
| Line 2: | Line 2: | ||
|name=REST.post | |name=REST.post | ||
|trusted=true | |trusted=true | ||
|version=1.5 | |version=1.5.0 | ||
|description= | |description= | ||
Perform an HTTP post request to the specified URL to create a resource. | Perform an HTTP post request to the specified URL to create a resource. | ||
|usage= | |usage= | ||
< | <syntaxhighlight lang="mtmacro" line> | ||
REST.post(url, payload, mediaType, getFullResponse) | REST.post(url, payload, mediaType, getFullResponse) | ||
REST.post(url, payload, mediaType, headers, getFullResponse) | REST.post(url, payload, mediaType, headers, getFullResponse) | ||
</ | </syntaxhighlight> | ||
'''Parameters''' | '''Parameters''' | ||
{{param|url|String | {{param|url|String containing the URL to the resource or collection of resources.}} | ||
{{param|payload|JSON object containing the key:value pairs.}} | {{param|payload|JSON object containing the key:value pairs.}} | ||
{{param|mediaType|String containing a MIME type and charset. See example.}} | {{param|mediaType|String containing a MIME type and charset. See example, but note that any character encoding other than {{code|UTF-8}} will be extremely difficult to produce in MapTool.}} | ||
{{param|headers|JSON object containing header key:value pairs.}} | {{param|headers|JSON object containing header key:value pairs where the value will be an array of 1 or more strings. Example: {{code|'{"X-Header-Name": ["value"]}'}} }} | ||
{{param|getFullResponse|Boolean (0:1). True(1) to get full response.}} | {{param|getFullResponse|Boolean (0:1). True(1) to get full response.}} | ||
'''Returns''' | '''Returns''' | ||
HTTP response as JSON (if full response) or server response, usually JSON but can be XML, HTML, or other formats. | HTTP response as JSON (if full response) or server response, usually JSON but can be XML, HTML, or other formats. | ||
'''Note:''' If a post fails with {{code|getFullResponse}} set to false, an error will be produced with a Status Code of 400. Set {{code|getFullResponse}} to true(1) for more detail. | |||
|example= | |example= | ||
Create a user with a post request. | Create a user with a post request. | ||
< | <syntaxhighlight lang="mtmacro" line> | ||
[h: baseurl = "https://reqres.in"] | [h: baseurl = "https://reqres.in"] | ||
[h: path = "/api/users"] | [h: path = "/api/users"] | ||
| Line 37: | Line 40: | ||
[r: json.indent(response, 2)] | [r: json.indent(response, 2)] | ||
</pre> | </pre> | ||
</ | </syntaxhighlight> | ||
Returns: | Returns: | ||
< | <syntaxhighlight lang="mtmacro" line> | ||
{ | { | ||
"status": 201, | "status": 201, | ||
| Line 61: | Line 64: | ||
} | } | ||
} | } | ||
</ | </syntaxhighlight> | ||
|also= | |also= | ||
[[RESTful Functions Overview|RESTful Functions Overview]] | [[RESTful Functions Overview|RESTful Functions Overview]] | ||
}} | }} | ||
[[Category:RESTful Function]] | [[Category:RESTful Function]] | ||
Latest revision as of 23:59, 10 May 2023
REST.post() Function
Note: This function can only be used in a Trusted Macro
• Introduced in version 1.5.0
Perform an HTTP post request to the specified URL to create a resource.
Usage
REST.post(url, payload, mediaType, getFullResponse)
REST.post(url, payload, mediaType, headers, getFullResponse)Parameters
url- String containing the URL to the resource or collection of resources.payload- JSON object containing the key:value pairs.mediaType- String containing a MIME type and charset. See example, but note that any character encoding other thanUTF-8will be extremely difficult to produce in MapTool.headers- JSON object containing header key:value pairs where the value will be an array of 1 or more strings. Example:'{"X-Header-Name": ["value"]}'getFullResponse- Boolean (0:1). True(1) to get full response.
Returns
HTTP response as JSON (if full response) or server response, usually JSON but can be XML, HTML, or other formats.
Note: If a post fails with getFullResponse set to false, an error will be produced with a Status Code of 400. Set getFullResponse to true(1) for more detail.
Example
Create a user with a post request.
[h: baseurl = "https://reqres.in"]
[h: path = "/api/users"]
[h: mediaType = "application/json; charset=utf-8"]
[h: getFullResponse = 1]
[h: payload = '{ "name": "morpheus", "job": "leader" }']
[h: response = REST.post(baseurl + path, payload, mediaType, getFullResponse)]
<br>
<pre>
[r: json.indent(response, 2)]
</pre>Returns:
{
"status": 201,
"headers": {
"access-control-allow-origin": ["*"],
"cf-ray": ["4b92503c1f49772a-LAX"],
"content-length": ["84"],
"content-type": ["application/json; charset=utf-8"],
"date": ["Sun, 17 Mar 2019 22:13:19 GMT"],
"etag": ["W/\"54-Iq8tAhIi7JekRXqEAyUkl9PsnwI\""],
"expect-ct": ["max-age=604800, report-uri=\"https://report-uri.cloudflare.com/cdn-cgi/beacon/expect-ct\""],
"server": ["cloudflare"],
"set-cookie": ["__cfduid=dd8f9e69613d9ab995b4365e36bcc2e181552860799; expires=Mon, 16-Mar-20 22:13:19 GMT; path=/; domain=.reqres.in; HttpOnly"],
"x-powered-by": ["Express"]
},
"body": {
"name": "morpheus",
"job": "leader",
"id": "996",
"createdAt": "2019-03-17T22:17:50.616Z"
}
}