Management API
      Back to home
      1. Help Center
      2. 1 - Get started with Bluestone PIM
      3. Management API

      Migrate to the new MAPI

      Learn how to use our new MAPI service to access Bluestone PIM endpoints.

      We are moving towards using API Gateway for MAPI to replace our current custom service setup. The current MAPI is now considered deprecated and will be discontinued by 02.01.2025.

      Here are the primary reasons for this change:

      • Enhanced Performance and Stability: The move aims to boost system performance and provide a more reliable operational environment.
      • Strengthened Security: By adopting API Gateway and using OAuth2, we aim to improve security measures, reducing risks and better protecting our data.
      • Reduced Maintenance: The new setup is expected to require less maintenance, making operations more efficient.
      • Improved Control Over Request Rates: This change will allow for better management of traffic, helping to handle request rates more effectively.
      • Better Reporting: The transition will enhance reporting capabilities, providing clearer insights and analytics.

      Summary of changes

      • OAuth2 authentication
      • New domain
      • Better throttling

      API reference

      Migration

      Authentication

      The current version of MAPI authenticates requests using an API key in the header. However, the new MAPI will shift to an OAuth2 flow for authentication.

      This change requires clients to first obtain a JWT access token using an ID and secret. This token will then need to be included in all subsequent calls to MAPI. 

      Authentication URL's

      • Test: https://idp.test.bluestonepim.com/op/token
      • Production: https://idp.bluestonepim.com/op/token
      • Production US: https://idp-us.bluestonepim.com/op/token
       

      Token expiration

      The access token is valid for one hour. You can inspect it to see details like when it was issued and when it will expire.

      Request URL changes

      In the Management API (MAPI), the structure of request URLs is composed of three distinct parts.

      To illustrate, let's use the URL responsible for retrieving a product from PIM based on its ID:

      Example of the old URL (Production environment):

      https://mapi.bluestonepim.com/pim/products/{id}

      The breakdown of this URL is as follows:

      • Old hostname: mapi.bluestonepim.com
      • Service path: pim
      • Resource path: products/{id}

      New Hostname

      The new hostname has changed in the following way:

      • Production EU: From "mapi.bluestonepim.com" to "api.bluestonepim.com"
      • Production US: From "mapi-us-e1.bluestonepim.com" to "api-us.bluestonepim.com"
      • Test EU: From "mapi.test.bluestonepim.com" to "api.test.bluestonepim.com" 

      Service Path

      The service path specifies the service to which the request is directed.

      Most service paths will stay unchanged. Only the following services will change paths:

      • Media Bank: From "media" to "media-bank"
      • Search: From "core-search" to "search"
      • CMS: From "cms-context" to "cms"

      Resource Path

      This section represents the exact resource within the chosen service. During this migration, resource paths will remain consistent and will not be altered.

      Throttling and Rate Limits

      In order to ensure high performance and maintain a fair usage policy, the new Management API (MAPI) incorporate throttling mechanisms. These mechanisms control the rate at which API requests can be made, ensuring that the infrastructure remains responsive and available to all users.

      The exact limits applicable to your integrations are stipulated in the contract agreement with Bluestone PIM.

      The limits apply to all clients combined within a customer organization.  

      Limits 

      • Rate Limit: A predefined number of requests are allowed per second (RPS). For instance, if the rate limit is set to 10 RPS, this means you can make up to 10 requests in one second.

      • Burst Limit: Beyond the steady rate limit we support a burst of up to 10 additional RPS. This provides flexibility for scenarios where short-term, higher request volumes might be needed. For example, if you do 0 requests one second, you can do 20 requests the next second. If you do 9 requests one second, you can do 11 requests the next second and so on. 

      Handling Limit Exceedance

      Should you exceed the set rate limits you will receive an HTTP 429 response, indicating "Too Many Requests". 

      It's essential to implement a backoff strategy in your integration. A backoff strategy typically involves:

        1. Detecting when a 429 status code is received.
        2. Waiting for a predetermined duration before making the next request.
        3. Gradually increasing the wait time if subsequent requests also result in a 429 response.

      This approach not only helps in complying with the rate limits but also ensures that your application remains resilient and adaptive to varying API conditions.

      In conclusion, while throttling might seem like a constraint, it's a necessary measure to ensure equitable access, maintain service performance, and promote good API consumer habits. Make sure to monitor your API request patterns and adjust them as needed to fit within the provided limits. If you find that this is not possible, please contact Bluestone PIM about increasing the limits.

      Basic example

      This Python example shows how to get an access token and fetch all catalogs in your organization in the test environment. 

      Advanced example

      This Python example also shows how to get an access token and fetch all catalogs in your organization in the test environment. The script is structured to handle common error conditions that might occur when interacting with an API, like network issues, server errors, or authentication problems, and employs retry logic with backoff to increase robustness and resilience in the face of transient errors.