#API

We offer an API that allows you to manage UI Extensions with the same capabilities as the UI interface. This enables you to efficiently integrate and control your UI Extensions programmatically.

#Prerequisites

Before proceeding, ensure that you have an active App (it can be a Custom App or an active connection) to an Akeneo PIM.

To learn how to create a Connection, see the Authentication Guide. If you're setting up a Custom App, follow the steps in this tutorial to obtain an App token.

#Authentication and authorization

#Authentication

Having a valid Akeneo PIM API token provided by either a Connection or an App to be authenticated to use the UI extension API endpoints.

#Authorization

To manage your extension, ensure that your Connection or App has the necessary permissions.

1. For Connections: The user associated with the Connection must have the permission UI extensions > Manage your extensions using the API enabled.
2. For Apps: You need to request the scope manage_extensions.

Granting these permissions before setup helps prevent unnecessary errors.

#Using Postman

The quickest way to get started with UI extensions is by using our Postman collection.

#1. Import the Postman Collection

1. Download our Postman collection
2. Download our Postman environment variable template
3. Import those files into Postman (follow this guide if you're not familiar with how Postman collections work)

#2. Fill the environment variables

The collection includes a pre-script for handling PIM Connection authentication.

Before making API requests, ensure your environment variables are filled with your Akeneo PIM Connection credentials: a valid pim_access_token will be generated automatically on your first request. If you don't receive a token, or you don't see it within the environment variable list, double-check your credentials.

#3. Create a UI extension

1. Select the Postman environment you've just created
2. Click on the Add an extension POST request
3. Customize the data to send as you want before click on Send
4. Copy the newly created extension UUID. It will be asked to modify or delete the UI extension.

#4. Update a UI extension

1. Make sure that the right environment is selected
2. Click on the Update an extension POST request
3. Fill the ui_extension_uuid parameter with the UUID of the concerned UI extension
4. Customize the data according to your needs before clicking on Send

#5. Delete a UI extension

1. Make sure that the right environment is selected
2. Click on the Delete an extension POST request
3. Fill the ui_extension_uuid parameter with the UUID of the concerned UI extension
4. Click on Send

#Using Curl

#1. Retrieve your credentials from your targeted PIM

1. Create a Connection in Akeneo PIM:

• Navigate to Connect > Connection settings > Create.
• Fill out the form to create the Connection.
• Note the generated client ID, secret, username, and password.

2. Set your environment variables:

• Define the client ID, secret, username, password, and Akeneo host URL as environment variables:

  • Shell

       export CLIENT_ID="your-client-id"
       export CLIENT_SECRET="your-client-secret"
       export API_USERNAME="your-API-username"
       export API_PASSWORD="your-API-password"
       export TARGET_PIM_URL="https://your-pim.cloud.akeneo.com"
      

Replace the placeholders with your actual credentials and host URL.

3. Encode your credentials:

• Encode the client ID and secret in base64 format, separated by a colon ::
  • Shell

       export BASE64_ENCODED_CLIENTID_AND_SECRET=$(echo -n "$CLIENT_ID:$CLIENT_SECRET" | base64 -w 0)
      // For Mac OS user remove the -w 0 option
      

4. Your API token:

• Make the API call to retrieve your API token using the environment variables:
  • Shell

       curl --request POST "$TARGET_PIM_URL/api/oauth/v1/token" \
       --header "Content-Type: application/json" \
       --header "Authorization: Basic $BASE64_ENCODED_CLIENTID_AND_SECRET" \
       --data-raw '{
       "grant_type": "password",
       "username": "'"$API_USERNAME"'",
       "password": "'"$API_PASSWORD"'"
       }'
      

After retrieving the API token, store the access_token from the response in an environment variable:

     export PIM_API_TOKEN="..."
     // Replace with the actual token from the response
    

#2. Create a UI extension

You can create a UI extension once you have a valid PIM API token.

    curl --request POST "$TARGET_PIM_URL/api/rest/v1/ui-extensions" \
    --header "Authorization: Bearer $PIM_API_TOKEN" \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "name": "my_awesome_extension",
        "version": "V1.02",
        "type": "link",
        "position": "pim.product.header",
        "configuration": {
            "url": "https://myapp.com/product",
            "default_label": "My awesome extension",
            "labels": {
              "en_US": "My awesome extension"
            }
        }
    }'
    

#3. Update a UI extension

To update a UI extension, you must have a valid PIM API token and the UUID of the extension you want to update.

    curl --request PATCH "$TARGET_PIM_URL/api/rest/v1/ui-extensions/$EXTENSION_UUID" \
    --header "Authorization: Bearer $PIM_API_TOKEN" \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "version": "V1.03",
        "type": "iframe",
        "position": "pim.product.tab"
    }'
    

#4. Delete a UI extension

To delete a UI extension, you must have a valid PIM API token and the UUID of the extension you want to delete.

    curl --request DELETE "$TARGET_PIM_URL/api/rest/v1/ui-extensions/$EXTENSION_UUID" \
    --header "Authorization: Bearer $PIM_API_TOKEN"
    

#API reference

Several choices are offered to deep dive into our API, to discover all the endpoints, and their request/response schema:

• You can consult this static documentation
• Discover it thanks to the postman collection (see the Postman section)