Configure 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 Rest API 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 basic and Avro base struct schema.
• Unsupported functionality in this release:
  • Batch, chunk, and compression at producing messaging.
  • Failover, shared, and key-shared subscription types.
  • Retry letter topic, dead letter topic, and negative acknowledgment.

Before using Rest API

Before you can use Rest API, there are some setup steps you need to complete. You need to complete the following setups:

1. Create a service account.
2. Generate a new token for the service account.
3. Configure a namespace or topic with the service account.
4. Grant consume and produce roles to the service account.
5. Get the service URL of your Pulsar 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 Manage area, click Service Accounts.

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

4. On the left navigation pane, do one of the followings:

   a. Click Namespaces, select the namespace you want to associate with the service account you created in step 1, and then select the POLICIES tab.

   or

   b. Click Topics, select the topic you want to associate 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 and produce. The consume and produce role permissions are added.

Enable Rest API

To enable Rest API on StreamNative Platform, you can set broker.pulsarRestMessaging.enabled to true and then use the helm upgrade command to update the configuration.

broker:
  pulsarRestMessaging:
    enabled: true

Work with Rest API

After enabling Rest API, you can use Rest API to produce and consume messages. Rest API sends binary data. You can use the cURL tool to encode a string (for example Hi Pulsar) into UTF-8 format bytes. To send bytes in another format, you need to specify an appropriate file. For more information, see the cURL documentation.

1. Create a subscription on the topic.

   curl -X PUT http://<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'
   

   You should see the following output:

   # No content response
   

2. Produce messages to the topic.

   curl -X POST http://<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'
   

   You should see the following output:

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

3. Consume messages from the topic.

   curl -X POST http://<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
   

   You should see the following output:

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

4. Acknowledge messages.

   curl -X PUT http://<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='
   

   You should see the following output:

   # No content response
   

Rest API reference

For more information, see Rest API reference.