Tim Mattison

Discovering AWS service codes, endpoint prefixes, and target prefixes

Originally posted on 2022-10-25

NOTE: The full process of linking API gateway directly to an AWS service is beyond the scope of this article. This is only provided to help you find the values you need to set up that integration.

If you’re working with API Gateway and you want to create a direct integration into an AWS service you’ll need to know a few things:

  • The service code, AKA the endpoint prefix
  • The target prefix

We’ll refer to the service code as the endpoint prefix from now on.

The endpoint prefix is simply the first section of the DNS name of an AWS service endpoint. For example the CloudWatch Logs endpoint URL in US East 1 is logs.us-east-1.amazonaws.com. In this case logs is our endpoint prefix.

The target prefix is the value you need to specify as the X-Amz-Target header when making a request to the service.

How do I find the endpoint prefix?

The easiest way is to use the AWS CLI and request the list of services from the service quotas service. You can then filter those results to get the endpoint prefix (they call it the service code here). For example if you want to find the CloudWatch Logs endpoint prefix you can do this:

aws service-quotas list-services --query 'Services[?contains(ServiceName, `Logs`)]'

And the output will look like this:

[
    {
        "ServiceCode": "logs",
        "ServiceName": "Amazon CloudWatch Logs"
    }
]

NOTE: This query is case sensitive and I happened to know that Logs started with an uppercase letter. If you want to filter without case sensitivity you can try this:

aws service-quotas list-services | grep -B 1 -A 1 -i logs

And the output will look like this:

{
  "ServiceCode": "logs",
  "ServiceName": "Amazon CloudWatch Logs"
},

If you can’t find the service with a filter like this you can always run aws service-quotas list-services | less and scan through the results manually.

How do I find the target prefix?

Finding the target prefix is a little more difficult. First you’ll need to clone the repo for the AWS SDK for JavaScript like this:

git clone git@github.com:aws/aws-sdk-js.git

Once the repo is cloned, replace SERVICECODE with the service code that you found in the previous step and run this command:

find aws-sdk-js -name "*.normal.json" -exec jq --arg name "SERVICECODE" 'select(.metadata.endpointPrefix == $name) | .metadata.targetPrefix' {} \;

If we do this for CloudWatch Logs the command would look like this:

find aws-sdk-js -name "*.normal.json" -exec jq --arg name "logs" 'select(.metadata.endpointPrefix == $name) | .metadata.targetPrefix' {} \;

And the output will look like this:

"Logs_20140328"

So in this case the target prefix, AKA X-Amz-Target is Logs_20140328.