Calling a REST POST API and Parsing JSON/XML Response

This blog post describes a general procedure for writing code that calls an HTTP/HTTPS POST REST API and parses the JSON or XML response.

Step 1: Form the CURL Command

A POST request in the form of a CURL command will look like this:

curl -X POST https://test-api.service.hmrc.gov.uk/organisations/vat/123456789/returns \
-H "Accept: application/vnd.hmrc.1.0+json"  \
-H "Content-Type: application/json" \
-H "Authorization: Bearer hmrc_app_server_token" \
-d '{
  "periodKey": "#001",
  "vatDueSales": 100.00,
  "vatDueAcquisitions": 100.00,
  "totalVatDue": 200,
  "vatReclaimedCurrPeriod": 100.00,
  "netVatDue": 100,
  "totalValueSalesExVAT": 500,
  "totalValuePurchasesExVAT": 500,
  "totalValueGoodsSuppliedExVAT": 500,
  "totalAcquisitionsExVAT": 500,
  "finalised": true
}'

Some notes:

  • Header fields are added using the “-H” option. Add the header fields and values as required by your particular REST API.
  • If OAuth2 authentication is required, the OAuth2 access token is provided in an “Authorization: Bearer …” header field.
  • If HTTP Basic authentication is required, which means providing a username/password, then use the –user option like this:
    --user username:password
    
  • If the request body contains JSON or XML, then query params are added in the URL and should appear just as they would in a browser address bar.  For example: https://test-api.service.hmrc.gov.uk/organisations/vat/123456789/returns?param1=value1&param2=value2
  • If the Content-Type is to be application/x-www-form-urlencoded, then params are specified using “-d” options. In this case, the Content-Type does not need to be explicitly specified.  For example:
    curl -X POST http://mws.amazonservices.com/Feeds/2009-01-01 \
      -d "AWSAccessKeyId=AWS_ACCESS_KEY_ID" \
      -d "Action=CancelFeedSubmissions" \
      -d "FeedSubmissionIdList.Id.1=1058369303" \
      -d "FeedTypeList.Type.1=_POST_PRODUCT_DATA_" \
      -d "FeedTypeList.Type.2=_POST_PRODUCT_PRICING_DATA_" \
      -d "MWSAuthToken=MWS_AUTH_TOKEN" \
      -d "Marketplace=ATExampleER" \
      -d "SellerId=MWS_SELLER_ID" \
      -d "SignatureMethod=HmacSHA256" \
      -d "SignatureVersion=2" \
      -d "Timestamp=CURRENT_DATE_TIME" \
      -d "Version=2009-01-01" \
      -d "Signature=MWS_SIGNATURE"
    
  • The JSON or XML body is specified in a “-d” option.  Enclose the full JSON or XML document in single quotes as shown above.

Step 2. If the REST API POST returns JSON or XML, get a representative sample of the JSON or XML response. For example:

{
  …  whatever JSON is returned goes here …
}

Step 3. Generate Code

Go to the online tool at http://tools.chilkat.io/curl.cshtml and generate code in any of 29 different programming languages. Paste the CURL command and respresentative JSON/XML response into the text boxes, and select the type of response (JSON, XML, Text, or Binary). If the POST returns just a status code, such as 201, and no response body, then select “Text” as the type of response.

Then click “Generate Code” and your sample code is generated. It generates code to create the JSON or XML request body, send the request, and to parse the JSON or XML response.   (If you already have the JSON/XML request body composed by some other means, then just ignore the generated code that creates the JSON/XML.)

Equivalent HTML Form and Chilkat HTTP POST

Any HTML form POST can be duplicated programmatically with the Chilkat HTTP component.

As an example, consider this HTML:

<html>
<body>
<form name="input" action="http://www.chilkatsoft.com/testPostHandler.asp"
method="post">
Arg1: 
<input type="text" name="arg1">
<br>(Arg2 is a hidden input)<br>
<input type="hidden" name="arg2" value="abc123">
Arg3 
<input type="text" name="arg3">
<input type="submit" value="Submit">
</form>
</body>
</html>

It submits a POST to http://www.chilkatsoft.com/testPostHandler.asp. The ASP that receives the post is as follows:

<html>
<head>
<title>Chilkat Test HTTP POST Handler</title>
</head>
<body>
<h1>Test HTTP POST Handler</h1>
<p><b>arg1:</b></p>
<pre>
<%
	Response.Write(Request.form("arg1"))
%>
</pre>
<p><b>arg2:</b></p>
<pre>
<%
	Response.Write(Request.form("arg2"))
%>
</pre>
<p><b>arg3:</b></p>
<pre>
<%
	Response.Write(Request.form("arg3"))
%>
</pre>
</body>
</html>

This may be tested online by going to http://www.chilkatsoft.com/testPost.asp

To duplicate using Chilkat HTTP, set the request object’s Path property equal to the form action, and call AddParam for each Form input. Examples in various programming languages may be found at the links below:

ASP: HTTP POST
SQL Server: HTTP POST
C#: HTTP POST
C++: HTTP POST
C: HTTP POST
Delphi: HTTP POST
Visual FoxPro: HTTP POST
Java: HTTP POST
Perl: HTTP POST
PHP: HTTP POST
Python: HTTP POST
Ruby: HTTP POST
VB.NET: HTTP POST
Visual Basic: HTTP POST
VBScript: HTTP POST