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.)