Rest API

Rest API provides a RESTful interface to a Pulsar cluster. With this interface, you can produce and consume messages without using the Pulsar protocol or clients.

• Functionality supported in this release:
  • Support on both non-partitioned and partitioned topics.
  • Produce, consume, and acknowledge messages through a RESTful interface without using the native Pulsar protocol or clients.
  • Support for basic and Avro base struct schema.
• Unsupported functionality in this release:
  • Batch, chunk, compress at producing.
  • Failover, shared, key-shared subscription types.
  • Retry letter topic, dead letter topic, negative acknowledgment.

Before using Rest API

Before you can start using Rest API, there are some setup steps you need to complete. You need to create a service account, generate a new token for that account, configure a namespace or topic with the service account and apply consume and produce roles to it, and then get the endpoint of your cluster. Follow the steps below to complete these tasks.

1. Create a service account. For details on creating a service account, see work with service accounts.

2. On the left navigation pane, in the Admin area, click Service Accounts.

3. Click Generate new token on the service account you created in step 1, then click the Copy icon.

   Tokens are only valid for 7 days. You can also use snctl to get an up-to-date token with better integration. For more information, see get token authentication parameters.

4. On the left navigation pane, in the Admin section, do one of the following:

   a. Click Tenant/Namespace, select the tenant/namespace you want associated with the service account you created in step 1, and then select the Policy tab.

   or

   b. Click Topics, select the topic you want associated with the service account you created in step 1, and then select the Policies tab.

5. In the Authorization area, click Add Role and select the service account you created in step 1 from the drop down.

6. In the Authorization area, click the drop down under the service account name, and select consume, then select produce. The consume and produce role permissions are added.

7. On the left navigation pane, in the Admin area, click Pulsar Clusters.

8. In the Access Points area, click copy on the HTTP Service URL (TLS) line to copy the endpoint of the cluster.

Work with Rest API

After you have completed the configuration steps above, you can start working with Rest API to produce and consume messages.

Schema support Rest API is similar to that of a client in that it does not validate the schema of the data, but instead stores the accepted binary data directly into a topic.

Use CURL with binary data

Rest API needs to send binary data. Use the cURL tool to encode the Hi Pulsar string in to UTF-8 format bytes. If you need to send bytes in another format, specify the appropriate file. For more information see the cURL documentation.

Create a subscription on the topic

curl -X PUT https://<endpoint>:<port>/admin/v2/persistent/public/default/rest-topic/subscription/rest-sub \
  --header 'Authorization: Bearer <Access Token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

Expected output

# No content response

Produce messages

curl -X POST https://<endpoint>:<port>/admin/rest/topics/v1/persistent/public/default/rest-topic/message \
  --header 'Authorization: Bearer <Access Token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/octet-stream' \
  --data-binary 'Hi, Pulsar'

Expected output

# Message id in string format
10:0:-1:0

Consume messages

curl -X POST https://<endpoint>:<port>/admin/rest/topics/v1/persistent/public/default/rest-topic/rest-sub/message \
  --header 'Authorization: Bearer <Access Token>' \
  --header 'Accept: application/octet-stream' \
  --header 'Content-Type: application/json' -v

Expected output

# Headers
X-Pulsar-Message-Id: CAoQACAAMAE=
X-Pulsar-Message-String-Id: 10:0:-1:0
X-Pulsar-Sequence-Id: 0

# Body
Hi, Pulsar

Acknowledge messages

curl -X PUT https://<endpoint>:<port>/admin/rest/topics/v1/persistent/public/default/rest-topic/rest-sub/message \
  --header 'Authorization: Bearer <Access Token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data-raw 'CAoQACAAMAE='

Expected output

# No content response

Rest API reference

For further information, see Rest API reference.