Introduction PIM API

The PIM application provides a Web API to support product data exchange with external systems for integration purposes.
It is not the goal to provide a full headless PIM to support the development of new external editors or separate applications.

The API

• is build for system integration purposes
• focus on the most common use cases
• is a well defined and version safe API that is consistent and supported for the foreseeable future
• is REST-based and uses JSON for detailed information
• has easily understandable documentation, which provides examples
• has also documented what is not supported
• has secured access and communication via API key and TLS
• is extended carefully only to valid common use cases

The API will cover the following cases.

• Product and Classification data (READ)
  Retrieve product data
  • by identifiers like product ID, catalog ID or classification group ID
  • by using additional filter criteria like changed date
• Product data (UPDATE - coming soon)
  Third-party systems can update product certain product information
  For example, to deactivate a product in PIM from ERP in the product life cycle using REST
  • set status
  • update attribute value
  • set product status
  • add product relations
  • add product prices

User examples

• Exchange product information with other internal systems
  • On-demand product creation for sales and marketing purposes
  • Update product status, because of need to (de-)active a product for sales
• Integration with external systems
  • ERP synchronization
    • Send product information from ERP
  • ESB 
    • Incoming data
  • DTP-Tools
    • Accessing classification information or product data

General Usage Information

In general, the API allows you to access products and classifications from PIM. When accessing the objects, keep the following in mind:

• In most cases, all required information for a product is returned by default. For instance, when accessing a Product, the Product's Attribute Values are already included and for objects referenced by Id, like classGroupId or valueListItemId, the description is also returned by default. LATER: You can use an exclude parameter to explicitly define the response.
• Whenever a list is returned, you often have the opportunity to limit your results with a limit Parameter.
• Easy to use/test, e. g. query parameter easier than the header
• API is stateless (no session = PIM will not remember "settings" previous calls, no tracking, etc.)

There are several best practices that are recommended when accessing the API:

• Query only what you need, when you need it
• Exclude what you do not need
• Use the links provided by the response instead of hardcoding API calls.

Limitations

• The API shall be simple and support simple operations. This means it's basically about reading objects and (later) writing products.
• Not all kinds of objects and not all domains are supported.
• Access to API is secured (authentication) but it can't be restricted to certain functions or data (no authorization). This means there is no way to limit the functions/URLs available for the API caller. Neither it's possible which data can be accessed (data-driven security to restrict regarding certain fields accessible or only to assortments).
• API was/is not designed to provide mass data access for certain use cases in regard to connecting systems like DTP, Shop, ERP etc. (exchange 100 or 1000nds of objects)
• API is not a headless PIM application: it is not designed to support its external user interfaces and editors in parallel to the PIM application.
• The cache is valid for five minutes, therefore deleted keys can still access the API in this period of time.

Enhancements

Enhancements in comparison to the previous API.

• faster and less complex by reducing the number of API calls
• retrieve products completely with as few requests as possible (do not additionally determine referenced basic data on product e. g. attribute description is already part of the response)

Endpoints

All API requests should be made to https://{domain}.eu.prodexa.com/pimapi/v1/

Available endpoints

• Classification
  • /classifications
  • /classifications/{classificationId}
• Classification group
  • /classifications/{classificationId}/groups
  • /classifications/{classificationId}/groups/{groupId}
• Product
  • /catalogs/{catalogId}/products
  • /catalogs/{catalogId}/products/{productId}

API Security

Authentication

The API is secured via API Key.

A user with the right privileges can use a UI to

• list api keys

• add/change the description to api key

• delete api key

• create api key

A full api key is displayed only once during the creation.
After this only the first part of an api key is visible.
This means, whenever you lose an api key, you need to create a new one.
We recommend adding a useful description to organize the api keys.

Because tokens are often used to establish long-lasting connections between two systems, each key has an unlimited lifetime.

Header

Every request sent to the api needs to have the following headers set:

accept: application/json
PXM-API-KEY: <YOUR-TOKEN>

An example of a valid api call could look like this:

curl -X GET "https://example.eu.prodexa.com/pxm/pimapi/v1/classifications"\

-H  "accept: application/json"\

-H  "PXM-API-KEY: 2m70da6v7270457ebc7c4f13c81c4d59"

Encryption

The data transfer is encrypted by HTTPS/TLS.

Versioning

The API is versioned.
Enhancements of the API will not increase the version, in this sense, the API is consistent and downward compatible.

Version Number

The version number is part of the endpoint URI, e. g. api/v1/classifications

Online Documentation

Each prodexa Cloud installation provides inbuilt API documentation.
It can be accessed via the menu "system" page.

API Testing

In the Online Documentation, each endpoint is described and can also be accessed and tried out.

In addition access via CURL  or postman is described.