Contact Free trial Login

Object Store v2 REST APIs

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

  • Object Store API

    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.

  • Object Store Stats API

    You need an access token to authenticate with the Object Store Stats API. To get the access token, you need the Anypoint username and password.

Prerequisites

  • Create an app that uses Object Store v2 and deploy it to CloudHub.

  • Store a key-value pair in the object store.

  • Get the access token (ACCESS_TOKEN) for the Anypoint Platform user.

    You need the access token to authenticate with the Object Store Stats API.

  • Get the organization ID (ORG_ID).

    You need the organization ID for operations with the Object Store API and Object Store Stats API.

    See the /api/me endpoint in the Access Management API.

  • Get the environment ID (ENV_ID).

    You need the organization ID for operations with the Object Store API and Object Store Stats API.

    See the /api/organizations/ORG_ID/environments endpoint in the Access Management API.

  • 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 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:

  1. Log in to Anypoint Platform > Runtime Manager.

  2. Click an application and click Manage Application.

  3. If the app is not associated with Object Store, click Use Object Store v2 and apply changes.

  4. Click Object Store in the left navigation area, and then click Show Client Credentials.

  5. Click Copy to Clipboard for Client ID and save it as the value of CLIENT_ID.

  6. Click Copy to Clipboard for Client Secret and save it as the value of CLIENT_SECRET.

Object Store API

The Object Store 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

POST

  • Object Store

    • Object store TTL, in seconds

      The maximum TTL is 2592000 seconds (30 days).

      If the entryTtl value specified is greater than 30 days, the value defaults to 2592000 seconds (30 days), without returning an error.

    • Persistence property

    • Usage limits for each application or environment, including options for limits based on keys or size, and how to enforce them

  • Key and list (item) value

Store

GET

  • Get keys

  • Get item

  • Get items

  • Get all items

  • Get regions for an organization

Contains + Retrieve + Retrieve all keys + Retrieve and store (Retrieve part)

PUT

  • Put item as string

  • Put item as number

  • Put item as confirmable string

  • Put store

Dual Store + Store

DELETE

  • Remove object store

  • Delete key

  • Delete item

Remove

The Dual Store operation in Object Store Connector consists of two operations: store the key and value, and then reverse the values. The Dual Store operation acts the same as two Object Store v2 "Put item as String" calls to accomplish these results:

  1. objectStore.store(key, value);

  2. objectStore.store(value, key);

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 API

  1. Set up an application, such as Postman, to access the object store.

  2. 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

    prod

    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-west-2.eu1.anypoint.mulesoft.com

    Europe (London)

    object-store-sa-east-1.anypoint.mulesoft.com

    South America (São Paulo)

    prod-eu

    object-store-eu-central-1.eu1.anypoint.mulesoft.com

    Europe (Frankfurt)

    object-store-eu-west-1.eu1.anypoint.mulesoft.com

    Europe (Ireland)

  3. Configure the application with HTTP headers and body for values to store to or read from the object store.

  4. Send the operation to the Object Store API.

Examples: Object Store 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, BEARER_TOKEN with your bearer token, ORG_ID with your organization ID, and ENV_ID with your environment ID:

curl -X GET \
-H 'authorization: bearer BEARER_TOKEN' \
'https://BASE_URL/api/v1/organizations/ORG_ID/environments/ENV_ID/stores'

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 Partitions

To view the list of partitions, submit a curl command similar to the following, replacing BASE_URL with the regional domain, BEARER_TOKEN with your bearer token, ORG_ID with your organization ID, ENV_ID with your environment ID, and STORE_ID with the storeId from the list of object stores:

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, BEARER_TOKEN with your bearer token, ORG_ID with your organization ID, ENV_ID with your environment ID, STORE_ID with the name of the object store, and PARTITION with the name of 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}

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, BEARER_TOKEN with your bearer token, ORG_ID with your organization ID, ENV_ID with your environment ID, STORE_ID with the name of the object store, and PARTITION with the name of the partition, and KEY_ID with the key ID:

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, BEARER_TOKEN with your bearer token, ORG_ID with your organization ID, ENV_ID with your environment ID, STORE_ID with the name of the object store, and PARTITION with the name of the partition, and specify a value 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, BEARER_TOKEN with your bearer token, ORG_ID with your organization ID, ENV_ID with your environment ID, STORE_ID with the name of the object store, and PARTITION with the name of the partition, and KEY_ID with the key ID:

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 Stats API

The Object Store 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 environment

  • Usage per organization

Access the Object Store Stats API

  1. Set up an application, such as Postman, to access the object store.

  2. 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=...

  3. Configure the application with HTTP headers and body for values to store to or read from the object store.

  4. Send the operation to the Object Store Stats API.

Examples: Object Store Stats API

Example: Retrieve Usage Metrics by Organization

To view Object Store usage statistics across the master business organization between July 11, 2020 and September 11, 2020, submit a curl command similar to the following, replacing ORG_ID with your organization ID and BEARER_TOKEN with your bearer token:

curl -X GET \
  'https://object-store-stats.anypoint.mulesoft.com/api/v1/organizations/ORG_ID?startDate=2020-07-11T17%3A51%3A54.000Z&endDate=2020-09-11T17%3A51%3A54.000Z&period=1month' \
  -H 'authorization: Bearer BEARER_TOKEN'

This request returns a response similar to the following:

[
 {"timeStamp":"2020-07-01T00:00:00Z","objectStoreRequestCount":0},
 {"timeStamp":"2020-08-01T00:00:00Z","objectStoreRequestCount":38},
 {"timeStamp":"2020-09-01T00:00:00Z","objectStoreRequestCount":28}
]

Example: Retrieve Usage Metrics by Environment

To view Object Store usage statistics for an environment between June 13, 2020 and September 13, 2020, 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=2020-06-13T17%3A51%3A54.000Z&endDate=2020-09-13T17%3A51%3A54.000Z&period=1month' \
  -H 'authorization: Bearer BEARER_TOKEN'

This request returns a response similar to the following:

[
 {"timeStamp":"2020-06-01T00:00:00Z","objectStoreRequestCount":3},
 {"timeStamp":"2020-07-01T00:00:00Z","objectStoreRequestCount":30},
 {"timeStamp":"2020-08-01T00:00:00Z","objectStoreRequestCount":1},
 {"timeStamp":"2020-09-01T00:00:00Z","objectStoreRequestCount":25}
]

Download Object Store APIs from Exchange

To download the Object Store APIs from Exchange, click Download and select the format to download: RAML, OAS, or as a connector file for Mule 3 or Mule 4:

Download Object Store API in Exchange
Figure 1. The arrow shows the Download button in Exchange.

Was this article helpful?

💙 Thanks for your feedback!

Edit on GitHub