HTTP API Reference for Momento Topics
Momento provides an HTTP API interface for your applications that can’t use our SDKs or for ones that prefer to use things like curl or fetch. For example, when deploying to edge compute services like Cloudflare Workers, Fastly Compute@Edge, etm. this API is for you. Be aware that most other applications should likely use Momento’s SDK clients.
You can also view the Open API Specification in our public workspace in Postman.
This documentation does not describe how to implement HTTP request syntax as that is different and unique to each language you might use.
Regions
To access the Momento HTTP API, use one of the following endpoints in the region of your API token and cache. If you do not see a region you require, let’s discuss. Please contact support.
Authentication
Each request requires an API key or Momento auth token generated via the Momento console or a token "vending machine" microservice you host. Momento auth tokens control access to the Momento services and can be set to expire and grant/restrict access to specific resources.
The token may be provided in one of two places in the request:
- An
Authorization
header - A
token
query parameter
If both the header and query parameter are provided, the request will fail with a 400 Bad Request
indicating only one value must be set.
Publish
Publishes a message to a topic.
Request
- Path: /topics/{cacheName}/{topicName}
- HTTP Method: POST
Path parameters
Parameter name | Required? | Type | Description |
---|---|---|---|
cacheName | yes | URL-safe string | The name of the cache containing the topic. |
topicName | yes | URL-safe string | Name of the topic to publish to. |
Query parameters
Parameter name | Required? | Type | Description |
---|---|---|---|
token | no** | URL-safe string | The Momento auth token, in string format, to be used for authentication/authorization of the request. |
Headers
Header name | Required? | Description |
---|---|---|
Authorization | no** | The Momento auth token, in string format, is used for authentication/authorization of the request. |
Content-Type | yes | To publish plain text data (UTF-8), specify text/plain . To publish binary data, specify application/octet-stream |
Body
The body of the HTTP POST request should contain the value that you wish to publish to the topic. You may publish
either text data, or binary data. To specify which type of data you are publishing, use the Content-Type
header, as
documented in the Headers section above.
Responses
Success
Status code: 204 No Content
- The message was successfully published to the provided topic
Error
Status code: 400 Bad Request
- This error type typically indicates that the request was incorrectly specified. See the message body for further details.
Status code: 401 Unauthorized
- This error type typically indicates that the Momento auth token passed in is either invalid or expired. See the body of the message for further details.
Status code: 403 Forbidden
- This error type typically indicates the Momento auth token passed in does not grant the required access to the resources you attempted. See the body of the message for further details.
Status code: 404 Not Found
- “Cache Not Found” indicates that the specified cache does not exist.
Status code: 429 Too Many Requests
- This error type typically indicates that account limits were exceeded. See the message body for further details, or contact Momento support to request a limit increase.
Status code: 500 Internal Server Error
- This error type typically indicates that the service is experiencing issues. Contact Momento support for further assistance.
Examples
Below is an example that publishes the value hello world!
to the example topic in the my-cache cache in the us-east-1 region.
Publish with token query parameter
curl -X POST -d 'hello world!' "https://api.cache.cell-us-east-1-1.prod.a.momentohq.com/topics/my-cache/example?token=<token>"
Publish with Authorization header
curl -X POST -H "Authorization: <token>" -d 'hello world!' "https://api.cache.cell-us-east-1-1.prod.a.momentohq.com/topics/my-cache/example"
Subscribe
Subscribes to a topic via long polling, waiting for messages to be published.
Request
- Path: /topics/{cacheName}/{topicName}
- HTTP Method: GET
Path parameters
Parameter name | Required? | Type | Description |
---|---|---|---|
cacheName | yes | URL-safe string | The name of the cache containing the topic. |
topicName | yes | URL-safe string | Name of the topic to subscribe to. |
Query parameters
Parameter name | Required? | Type | Description |
---|---|---|---|
token | no** | URL-safe string | The Momento auth token, in string format, to be used for authentication/authorization of the request. |
sequence_number | no | Integer | Optional parameter to specify the last message received. Ensures messages are received in order or to detect discontinuities. |
Headers
Header name | Required? | Description |
---|---|---|
Authorization | no** | The Momento auth token, in string format, is used for authentication/authorization of the request. |
Responses
Success
Status code: 200 OK
- The subscription was successful and messages were returned. The response will contain a JSON object with the message(s) and their sequence numbers. If there was a gap in the message sequence, a discontinuity message will be included.
Error
Status code: 401 Unauthorized
- This error type typically indicates that the Momento auth token passed in is either invalid or expired. See the body of the message for further details.
Status code: 403 Forbidden
- This error type typically indicates the Momento auth token passed in does not grant the required access to the resources you attempted. See the body of the message for further details.
Status code: 404 Not Found
- “Cache Not Found” indicates that the specified cache or topic does not exist.
Status code: 429 Too Many Requests
- This error type typically indicates that account limits were exceeded. See the message body for further details, or contact Momento support to request a limit increase.
Status code: 500 Internal Server Error
- This error type typically indicates that the service is experiencing issues. Contact Momento support for further assistance.
Examples
Request with no sequence number
This request includes auth as a header.
curl -X GET -H "Authorization: <token>" "https://api.cache.cell-us-east-1-1.prod.a.momentohq.com/topics/my-cache/my-topic"
Response
{
"items": [
{
"item": {
"topic_sequence_number": 0,
"value": {
"text": "hello world"
}
}
}
]
}
Request with a sequence number provided
This request includes auth as a query parameter.
curl -X GET "https://api.cache.cell-us-east-1-1.prod.a.momentohq.com/topics/my-cache/my-topic?token=<token>&sequence_number=100"
Response
{
"items": [
{
"discontinuity": {
"last_topic_sequence": 100,
"new_topic_sequence": 104
}
},
{
"item": {
"topic_sequence_number": 104,
"value": {
"text": "hello world"
}
}
}
]
}