AWS Reference Documentation — Sample Requests and Responses are Important

November 7, 2022

AWS Reference Documentation — Sample Requests and Responses are Important

The AWS Reference Documentation is not consistent. In some cases, the documentation provides a sample request and sample response. The samples are extremely helpful, and make it easy to implement the call in any programming language. With Chilkat, you can usually generate sample code by pasting the sample request, and the body of the sample response into Chilkat’s online tool at https://tools.chilkat.io/httpRequestToCode

Here’s an example of a nicely documented AWS API Action: AWS Certificate Manager – ImportCertificate

It provides the following Sample Request and Sample Response:

Sample Request

POST / HTTP/1.1
Host: acm.us-east-1.amazonaws.com
X-Amz-Target: CertificateManager.ImportCertificate
X-Amz-Date: 20161011T184744Z
Content-Type: application/x-amz-json-1.1
Authorization: AWS4-HMAC-SHA256 Credential=key_ID/20161011/us-east-1/acm/aws4_request,
SignedHeaders=content-type;host;x-amz-date;x-amz-target,
Signature=60f965247476c4672c498c24ba255e52a62a7e4bd8678d8ee788af5ffe42f377

{
    "CertificateChain": "Base64-encoded blob",
    "PrivateKey": "Base64-encoded blob",
    "Certificate": "Base64-encoded blob"	
}

Sample Response

HTTP/1.1 200 OK
x-amzn-RequestId: 32f9ab0a-8fe3-11e6-8d69-c91606b24a3f
Content-Type: application/x-amz-json-1.1
Content-Length: 104
Date: Tue, 11 Oct 2016 18:47:46 GMT

{"CertificateArn":"arn:aws:acm:us-east-1:111122223333:certificate/91228a40-ad89-4ce0-9f6c-07009fc8fdfb"}

Some AWS API’s Lack Samples for Request and Response

For example, the AWS Textract – DetectDocumentText

Writing code for the AWS API’s that lack samples are more painful and tedious because we need to hunt for the answers:

What is the value of the X-Amz-Target header?
What is the service_prefix part of the domain? (i.e. <service_prefix>.<region>.amazonaws.com)
Do we send an X-Amz-Target header, or instead send an “Action” request parameter?
Seeing a typical request and response with actual values is so much easier to understand. Providing only a syntax or schema can be vague.

Let’s say we want to implement Textract DetectDocumentText. We can glean from the AWS reference documentation that it should be a POST with a JSON request body and will return a JSON response body. But we need answers to the following questions:

What is the AWS Service Prefix?

Go to https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazontextract.html , scroll down to find your service and click on it.

For Textract we have: https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazontextract.html

You’ll see the note about the service prefix: “Amazon Textract (service prefix: textract) provides the following …”

OK.. so we now know the Host will be textract.<region>.amazonaws.com

`What is the X-Amz-Target`? or do we need an Action request param???

Perhaps the X-Amz-Target is literally the name of the API combined with the Action name? For example, “Textract.DetectDocumentText”. You can experiment by trying it. Or you can Google “AWS Textract X-Amz-Target” to see if anyone else knows. I found https://any-api.com/amazonaws_com/textract/docs/_X_Amz_Target_Textract_DetectDocumentText/DetectDocumentText

It appears the X-Amz-Target should be “Textract.DetectDocumentText”.

What is Contained in the JSON Request Body?

The Amazon reference documentation shows this Request Syntax:

{
   "Document": { 
        "Bytes": blob,
        "S3Object": { 
             "Bucket": "string",
             "Name": "string",
             "Version": "string"
         }
     }
}

I suppose we can infer that you either upload the bytes of the document, or reference an S3 object. An what is a blob? It must be the base64 string representation of the binary data..

Great. So finally… after all this unnecessary pain and suffering, we finally (probably) have enough to write the code.

See

admin