POST
Object Store v2 REST APIs
Where possible, we changed noninclusive terms to align with our company value of Equality. We maintained certain terms to avoid any effect on customer implementations. |
The Object Store v2 APIs enable you to use REST to perform the following:
-
Retrieve a list of object stores and keys associated with an application.
-
Store and retrieve key-value pairs in an object store.
-
Delete key-value pairs from an object store.
-
Retrieve Object Store usage statistics for your organization.
Object Store provides these APIs:
Authenticate with the Object Store APIs
-
You need a bearer token to authenticate with the Object Store API. To get the bearer token, you need the client ID and client secret for the app.
-
You need an access token to authenticate with the Object Store v2 Stats API. To get the access token, you need the Anypoint Platform username and password of a user assigned the Organization Administrators role.
Prerequisites
-
Create an app that uses Object Store v2 and deploy it to CloudHub.
See Deploy to CloudHub.
-
Store a key-value pair in the object store.
-
Get the access token (ACCESS_TOKEN) for the Anypoint Platform user.
The user must be assigned the Organization Administrators role to access the Object Store v2 Stats API.
You need the access token to authenticate with the Object Store v2 Stats API.
See Authentication in the Access Management API.
-
Get the organization ID (ORG_ID).
You need the organization ID for operations with the Object Store v2 API and Object Store v2 Stats API.
See the
/api/me
endpoint in the Access Management API. -
Get the environment ID (ENV_ID).
You need the environment ID for operations with the Object Store v2 API and Object Store v2 Stats API.
See the
/api/organizations/ORG_ID/environments
endpoint in the Access Management API. -
Get the region ID (REGION_ID).
You need the region ID for operations with the Object Store v2 Stats API.
See the
/api/v1/organizations/ORG_ID/regions
endpoint in the Object Store v2 API and Example: Retrieve a List of Regions. -
Get the store ID (STORE_ID).
You need the store ID for operations with the Object Store v2 Stats API.
See the
/api/v1/organizations/ORG_ID/environments/ENV_ID/stores/STORE_ID
endpoint in the Object Store v2 API and Example: Retrieve a List of Object Stores. -
Get the client ID (CLIENT_ID) and client secret (CLIENT_SECRET) for the app.
You need the client ID and client secret to get the bearer token.
-
Get the bearer token (BEARER_TOKEN) for the app.
You need the bearer token to authenticate with the Object Store v2 API.
See the
/accounts/oauth2/token
endpoint in the Access Management API.To get the bearer token, you need the client ID and client secret for the app.
Get the Client ID and Client Secret for the App
To get the client ID and the client secret for the app:
-
Log in to Anypoint Platform > Runtime Manager.
-
Click an application and click Manage Application.
-
If the app is not associated with Object Store, click Use Object Store v2 and apply changes.
-
Click Object Store in the left navigation area, and then click Show Client Credentials.
-
Click Copy to Clipboard for Client ID and save it as the value of CLIENT_ID.
-
Click Copy to Clipboard for Client Secret and save it as the value of CLIENT_SECRET.
Object Store v2 API
The Object Store v2 API reads and writes key,list
values,
which is different from Anypoint Connector for Object Store (Object Store Connector),
which reads and writes in the key,value
format.
The following table compares the Object Store REST API operations to Object Store Connector operations:
Object Store v2 API | Object Store v2 REST API Operations | Object Store Connector Operation |
---|---|---|
|
Store |
|
GET |
|
Contains + Retrieve + Retrieve all keys + Retrieve and store (Retrieve part) |
PUT |
|
Store |
DELETE |
|
Remove |
You can retrieve a maximum of 25 keys with each GET operation.
Limitations
If an application writes to an object store using the REST interface and reads with Object Store Connector for Mule 3 from the same key, the read can retrieve only the value at element 0. Therefore, when using the REST API, use the API to write and read content from the object store. Alternatively, you can use the API to write only to index 0.
This limitation doesn’t apply to Object Store Connector for Mule 4 or Anypoint Studio Object Store Connector.
Access the Object Store v2 API
-
Set up an application, such as Postman, to access the object store.
-
Configure the object store access URL, replacing ORG_ID with your organization ID and ENV_ID with your environment ID:
BASE_URL/api/v1/organizations/ORG_ID/environments/ENV_ID/stores/myTestStoreId/objects
Depending on the deployment region, use one of the following domains for the value of BASE_URL in the access URL:
Control Plane BASE_URL Region U.S.
object-store-us-east-1.anypoint.mulesoft.com
US East (N. Virginia)
object-store-us-east-2.anypoint.mulesoft.com
US East (Ohio)
object-store-us-west-1.anypoint.mulesoft.com
US West (N. California)
object-store-us-west-2.anypoint.mulesoft.com
US West (Oregon)
object-store-ap-southeast-1.anypoint.mulesoft.com
Asia Pacific (Singapore)
object-store-ap-southeast-2.anypoint.mulesoft.com
Asia Pacific (Sydney)
object-store-ap-northeast-1.anypoint.mulesoft.com
Asia Pacific (Tokyo)
object-store-ca-central-1.anypoint.mulesoft.com
Canada (Central)
object-store-eu-central-1.anypoint.mulesoft.com
Europe (Frankfurt)
object-store-eu-west-1.anypoint.mulesoft.com
Europe (Ireland)
object-store-eu-west-2.anypoint.mulesoft.com
Europe (London)
object-store-sa-east-1.anypoint.mulesoft.com
South America (São Paulo)
U.S.
MuleSoft Government Cloud
object-store-us-gov-west-1.gov.anypoint.mulesoft.com
US Gov West
EU
object-store-eu-central-1.eu1.anypoint.mulesoft.com
Europe (Frankfurt)
object-store-eu-west-1.eu1.anypoint.mulesoft.com
Europe (Ireland)
-
Configure the application with HTTP headers and body for values to store to or read from the object store.
-
Send the operation to the Object Store v2 API.
Examples: Object Store v2 API
Example: Retrieve a List of Object Stores
To view the list of object stores, submit a curl
command similar to the following, replacing
BASE_URL with the regional domain,
ORG_ID with your organization ID,
ENV_ID with your environment ID, and
ACCESS_TOKEN with your access token:
curl -X GET \
'https://BASE_URL/api/v1/organizations/ORG_ID/environments/ENV_ID/stores' \
-H 'authorization: bearer ACCESS_TOKEN'
This command returns output similar to the following:
{"values":[{"storeId":"APP_os-simple-flow__defaultPersistentObjectStore","encrypted":true,"permanentOsFlag":false,
"persistent":true,"defaultTtlSeconds":2592000,"defaultConfirmationTtlSeconds":600,"isFixedTtl":null},
{"storeId":"APP_scheduler-tests__defaultPersistentObjectStore","encrypted":true,"permanentOsFlag":false,
"persistent":true,"defaultTtlSeconds":2592000,"defaultConfirmationTtlSeconds":600,"isFixedTtl":null}
{"storeId":"APP_sending-a-csv-file-thru-email-using-smtp__defaultPersistentObjectStore","encrypted":true,"permanentOsFlag":false,
"persistent":true,"defaultTtlSeconds":2592000,"defaultConfirmationTtlSeconds":600,"isFixedTtl":null}],"nextPageToken":null}
Example: Retrieve a List of Regions
To view the list of regions, submit a curl
command similar to the following,
replacing
BASE_URL with the regional domain,
ORG_ID with your organization ID, and
ACCESS_TOKEN with your access token:
curl -X GET \
'https://BASE_URL/api/v1/organizations/ORG_ID/regions' \
-H 'authorization: Bearer ACCESS_TOKEN'
This command returns output similar to the following:
[
{
"id": "us-east-1",
"name": "US East (N. Virginia)",
"url": "http://object-store.us-east-1.anypoint.mulesoft.com"
},
{
"id": "us-west-1",
"name": "US West (N. California)",
"url": "http://object-store.us-west-1.anypoint.mulesoft.com"
}
]
Example: Retrieve a List of Partitions
To view the list of partitions, submit a curl
command similar to the following,
replacing
BASE_URL with the regional domain,
ORG_ID with your organization ID,
ENV_ID with your environment ID, and
STORE_ID with the storeId
from the list of object stores, and
ACCESS_TOKEN with your access token:
curl -X GET \
https://BASE_URL/api/v1/organizations/ORG_ID/environments/ENV_ID/stores/STORE_ID/partitions \
-H "Authorization: Bearer ACCESS_TOKEN"
This command returns output similar to the following:
{"values":["PARTITION_ID"],"nextPageToken":null}
Example: Retrieve a List of Keys in a Partition
To view the keys in a partition, submit a curl
command similar to the following,
replacing
BASE_URL with the regional domain,
ORG_ID with your organization ID,
ENV_ID with your environment ID,
STORE_ID with the name of the object store,
PARTITION_ID with the name of the partition, and
ACCESS_TOKEN with your access token:
curl -X GET \
https://BASE_URL/api/v1/organizations/ORG_ID/environments/ENV_ID/stores/STORE_ID/partitions/PARTITION_ID/keys \
-H "Authorization: Bearer ACCESS_TOKEN"
This command returns output similar to the following:
{"values":[{"keyId":"KeyTwo"},{"keyId":"KeyOne"}],"nextPageToken":null}
Example: Retrieve the Value of a Key
To view the value of a key, submit a curl
command similar to the following,
replacing BASE_URL with the regional domain,
ORG_ID with your organization ID,
ENV_ID with your environment ID,
STORE_ID with the name of the object store,
PARTITION_ID with the name of the partition,
KEY_ID with the key ID, and
ACCESS_TOKEN with your access token:
curl -X GET \
https://BASE_URL/api/v1/organizations/ORG_ID/environments/ENV_ID/stores/STORE_ID/partitions/PARTITION_ID/keys/KEY_ID \
-H "Authorization: Bearer ACCESS_TOKEN"
This command returns output similar to the following:
{"binaryValue":"++Kn0AIBAQBbwoABDiJLZXkgMiBWYWx1ZSL8rNmhAQEBAWphdmEuaW8uU2VyaWFsaXphYmzlgGFwcGxpY2F0aW9uL2pzb247IGNoYXJzZXQ9VVRGLbgAAAAAAAAADQ==","keyId":"KeyTwo","valueType":"BINARY"}
Example: Store a Key-Value Pair
To store a key-value pair, submit a curl
command similar to the following,
replacing
BASE_URL with the regional domain,
ORG_ID with your organization ID,
ENV_ID with your environment ID,
STORE_ID with the name of the object store,
PARTITION_ID with the name of the partition,
ACCESS_TOKEN with your access token, and
specify a value (myTestKey
) for KEY_ID:
KEY_ID=myTestKey; \
curl -X POST \
https://BASE_URL/api/v1/organizations/ORG_ID/environments/ENV_ID/stores/STORE_ID/partitions/PARTITION_ID/keys/myTestKey \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
--data '{"stringValue":"Hello World","keyId":"myTestKey","valueType":"STRING"}'
In this command, the value is a JSON string.
To verify that the key-pair is in the object store, get a list of the keys in the partition:
curl -X GET \
https://BASE_URL/api/v1/organizations/ORG_ID/environments/ENV_ID/stores/STORE_ID/partitions/PARTITION_ID/keys \
-H "Authorization: Bearer ACCESS_TOKEN"
This command returns output similar to the following:
{"values":[{"keyId":"KeyTwo"},{"keyId":"KeyOne"},{"keyId":"myTestKey"}],"nextPageToken":null}
Example: Delete a Key and Value
To delete a key-value pair, submit a curl
command similar to the following,
replacing
BASE_URL with the regional domain,
ORG_ID with your organization ID,
ENV_ID with your environment ID,
STORE_ID with the name of the object store,
PARTITION_ID with the name of the partition,
KEY_ID with the key ID, and
ACCESS_TOKEN with your access token:
curl -X DELETE \
https://BASE_URL/api/v1/organizations/ORG_ID/environments/ENV_ID/stores/STORE_ID/partitions/PARTITION_ID/keys/KEY_ID \
-H "Authorization: Bearer ACCESS_TOKEN"
In this command, the value is a JSON string.
To verify that the key-pair is no longer in the object store, get a list of the keys in the partition:
curl -X GET \
https://BASE_URL/api/v1/organizations/ORG_ID/environments/ENV_ID/stores/STORE_ID/partitions/PARTITION_ID/keys \
-H "Authorization: Bearer ACCESS_TOKEN"
This command returns output similar to the following:
{"values":[{"keyId":"KeyTwo"},{"keyId":"KeyOne"}],"nextPageToken":null}
Object Store v2 Stats API
The Object Store v2 Stats API enables you to retrieve statistics on your Object Store usage.
The usage statistics are not real-time and might include latency.
Use the Stats API to view your entire organization’s usage of Object Store for billing purposes:
-
Usage per root organization and all sub-organizations
-
Usage per organization
-
Usage per environment
-
Usage per region
-
Usage per store
Access the Object Store v2 Stats API
-
Set up an application, such as Postman, to access the object store.
-
Configure the access URL, replacing ORG_ID with your organization ID and ENV_ID with your environment ID:
https://object-store-stats.anypoint.mulesoft.com/api/v1/organizations/ORG_ID/environments/ENV_ID?startDate=...&endDate=...&period=...
-
Configure the application with HTTP headers and body for values to store to or read from the object store.
-
Send the operation to the Object Store v2 Stats API.
Examples: Object Store v2 Stats API
Example: Get Usage Metrics by Organization
By default, the Object Store v2 Stats API endpoint retrieves statistics only for the specified ORG_ID.
To get the usage data for the root organization and all sub-organizations, set isMaster
to true
when ORG_ID is the root organization.
If you use isMaster=true
to query a sub-organization, the endpoint returns no results.
To view Object Store usage statistics for the root organization and all sub-organizations,
between July 11, 2023 and September 11, 2023,
submit a curl
command similar to the following,
replacing ORG_ID with the organization ID for your root organization and BEARER_TOKEN with your bearer token:
curl -X GET \
'https://object-store-stats.anypoint.mulesoft.com/api/v1/organizations/ORG_ID?startDate=2023-07-11T17%3A51%3A54.000Z&endDate=2023-09-11T17%3A51%3A54.000Z&period=1month&isMaster=true' \
-H 'authorization: Bearer BEARER_TOKEN'
This request returns a response similar to the following:
[
{"timeStamp":"2023-07-01T00:00:00Z","objectStoreRequestCount":0},
{"timeStamp":"2023-08-01T00:00:00Z","objectStoreRequestCount":38},
{"timeStamp":"2023-09-01T00:00:00Z","objectStoreRequestCount":28}
]
To view Object Store usage statistics for the root organization and all sub-organizations for one day, submit a curl
command similar to the following,
replacing ORG_ID with the organization ID for your root organization and BEARER_TOKEN with your bearer token:
curl -X GET \
'https://object-store-stats.anypoint.mulesoft.com/api/v1/organizations/ORG_ID?startDate=2023-11-11T17%3A51%3A54.000Z&endDate=2023-11-131T17%3A51%3A54.000Z&period=1day&isMaster=true' \
-H 'authorization: Bearer BEARER_TOKEN'
This request returns a response similar to the following:
[
{"timeStamp":"2023-11-11T00:00:00Z","objectStoreRequestCount":36}
{"timeStamp":"2023-11-12T00:00:00Z","objectStoreRequestCount":22}
{"timeStamp":"2023-11-13T00:00:00Z","objectStoreRequestCount":43}
]
To view Object Store usage statistics for a sub-organization,
between February 10, 2023 and April 10, 2023,
submit a curl
command similar to the following, replacing
ORG_ID with the organization ID for the sub-organization and
BEARER_TOKEN with your bearer token:
curl -X GET \
'https://object-store-stats.anypoint.mulesoft.com/api/v1/organizations/ORG_ID?startDate=2023-02-10T17%3A51%3A54.000Z&endDate=2023-04-10T17%3A51%3A54.000Z&period=1month' \
-H 'authorization: Bearer BEARER_TOKEN'
This request returns a response similar to the following:
[
{"timeStamp":"2023-02-10T00:00:00Z","objectStoreRequestCount":1},
{"timeStamp":"2023-03-10T00:00:00Z","objectStoreRequestCount":15},
{"timeStamp":"2023-04-10T00:00:00Z","objectStoreRequestCount":2}
]
To view Object Store usage statistics for one day for a sub-organization,
submit a curl
command similar to the following, replacing
ORG_ID with the organization ID for the sub-organization and
BEARER_TOKEN with your bearer token:
curl -X GET \
'https://object-store-stats.anypoint.mulesoft.com/api/v1/organizations/ORG_ID?startDate=2023-12-01T17%3A51%3A54.000Z&endDate=2023-12-03T17%3A51%3A54.000Z&period=1day' \
-H 'authorization: Bearer BEARER_TOKEN'
This request returns a response similar to the following:
[
{"timeStamp":"2023-12-01T00:00:00Z","objectStoreRequestCount":4}
{"timeStamp":"2023-12-02T00:00:00Z","objectStoreRequestCount":2}
{"timeStamp":"2023-12-03T00:00:00Z","objectStoreRequestCount":8}
]
Example: Get Usage Metrics by Environment
To view Object Store usage statistics for an environment between June 13, 2021 and September 13, 2021,
submit a curl
command similar to the following, replacing
ORG_ID with your organization ID,
ENV_ID with your environment ID,
and BEARER_TOKEN with your bearer token:
curl -X GET \
'https://object-store-stats.anypoint.mulesoft.com/api/v1/organizations/ORG_ID/environments/ENV_ID?startDate=2021-06-13T17%3A51%3A54.000Z&endDate=2021-09-13T17%3A51%3A54.000Z&period=1month' \
-H 'authorization: Bearer BEARER_TOKEN'
This request returns a response similar to the following:
[
{"timeStamp":"2021-06-01T00:00:00Z","objectStoreRequestCount":3},
{"timeStamp":"2021-07-01T00:00:00Z","objectStoreRequestCount":30},
{"timeStamp":"2021-08-01T00:00:00Z","objectStoreRequestCount":1},
{"timeStamp":"2021-09-01T00:00:00Z","objectStoreRequestCount":25}
]
Example: Get Usage Metrics by Region
To view Object Store usage statistics for a region,
submit a curl
command similar to the following, replacing
ORG_ID with your organization ID,
ENV_ID with your environment ID,
REGION_ID with the region from which to retrieve metrics, and
BEARER_TOKEN with your bearer token:
curl -X GET \
'https://object-store-stats.anypoint.mulesoft.com/api/v1/organizations/ORG_ID/environments/ENV_ID/regions/REGION_ID?startDate=2021-06-13T17%3A51%3A54.000Z&endDate=2021-09-13T17%3A51%3A54.000Z&period=1month' \
-H 'authorization: Bearer BEARER_TOKEN'
To retrieve the REGION_ID, see Example: Retrieve a List of Regions.
This request returns a response similar to the following:
[
{"timeStamp":"2021-06-01T00:00:00Z","objectStoreRequestCount":3},
{"timeStamp":"2021-07-01T00:00:00Z","objectStoreRequestCount":30},
{"timeStamp":"2021-08-01T00:00:00Z","objectStoreRequestCount":1},
{"timeStamp":"2021-09-01T00:00:00Z","objectStoreRequestCount":25}
]
Example: Get Usage Metrics by Store
To view Object Store usage statistics for a store,
submit a curl
command similar to the following, replacing
ORG_ID with your organization ID,
ENV_ID with your environment ID,
REGION_ID with the region to retrieve metrics from,
STORE_ID with the store ID to retrieve metrics for,
and BEARER_TOKEN with your bearer token:
curl -X GET \
'https://object-store-stats.anypoint.mulesoft.com/api/v1/organizations/ORG_ID/environments/ENV_ID/regions/REGION_ID/stores/STORE_ID?startDate=2021-06-13T17%3A51%3A54.000Z&endDate=2021-09-13T17%3A51%3A54.000Z&period=1month' \
-H 'authorization: Bearer BEARER_TOKEN'
To retrieve the STORE_ID, see Example: Retrieve a List of Object Stores.
This request returns a response similar to the following:
[
{"timeStamp":"2021-06-01T00:00:00Z","objectStoreRequestCount":3},
{"timeStamp":"2021-07-01T00:00:00Z","objectStoreRequestCount":30},
{"timeStamp":"2021-08-01T00:00:00Z","objectStoreRequestCount":1},
{"timeStamp":"2021-09-01T00:00:00Z","objectStoreRequestCount":25}
]