Example: Producing data with REST Proxy

Here we will illustrate how to produce to a String key and value type Topic.

For an extensive set of curl requests demonstrating all available features, you can refer to the rest-proxy-examples repository.

Producing via curl

Prerequisites

You have created an application on Self Service and requested and received produce access to a topic. In the below example the topics Key and Value Type are both String.

Security context

Depending on the security configuration, you may use TLS or OAuth to authenticate and authorize client requests.

TLS

Acquire the certificate and key file you used when registering your producer. In this example, the two files are in the working directory and are named auth.key and auth.cert.

OAuth

It is the caller’s responsibility to initiate an OAuth flow to obtain a valid JWT token and to ensure it is refreshed before it expires. Below is an example of how to retrieve a token using Keycloak:

curl -X POST \
  https://keycloak.cloud.axual.com/auth/realms/axual/protocol/openid-connect/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'client_id=<producer_client_id>' \
  -d 'grant_type=client_credentials' \
  -d 'client_secret=<your_client_secret>'

Extract the JWT token from the response. The token must contain a claim keyed after your configured security.oauth.enabled.principal-claim-name string. The contents of that particular claim will be used to authenticate and authorize the request against Kafka. The resource we are trying to access—in this case the Topic—should have ACLs matching the string contents of the provided claim.

Prepare your request header following the format:

  --header "Authorization: Bearer <obtained_token>"

Putting it all together

Update the first few lines in the following script with your deployment information, then run the commands.

REST_PROXY_URL="https://rest-ams01.cloud.axual.com:99999"
AXUAL_ENVIRONMENT="example" (1)
AXUAL_TOPIC_NAME="my_test_topic" (2)
UUID="unique_producer_${RANDOM}" (3)

curl -k --request POST \
  --url "${REST_PROXY_URL}/topic/${AXUAL_ENVIRONMENT}/${AXUAL_TOPIC_NAME}" \
  --header "axual-application-id: irrelevant-for-producers" \
  --header "axual-producer-uuid: ${UUID}" \
  --header "Content-Type: application/json" \
  --key ./auth.key \ (4)
  --cert ./auth.cert \
  --data '
  {
     "keyMessage":{
        "type":"STRING", (5)
        "message":"{\"name\": \"axl\"}"
     },
     "valueMessage":{
        "type":"STRING", (6)
        "message":"{\"employer\": \"Axual\", \"age\": \"21\"}"
     }
  }'

1	Associates the created session with a Producer object. Subsequent calls may use the same UUID to avoid overhead associated with creating a new Producer
2	Environment `Short name` as it appears on Self Service
3	Topic `Name` as it appears on Self Service
4	Depending on your configuration, you may use the OAuth header instead of TLS configuration here
5	Should match the Topic Key type
6	Should match the Topic Value type

You can also import any of the curl examples into Postman using the "Import > Raw Text" option and pasting the command.