Bluestone PIM Public API is a set of endpoints optimized for serving large amounts of data to many external systems.
This API will not provide endpoints for data maintenance or any logic, only optimized read access to data.
General
The API will not support a strict JSON schema, as the different data models will expand in the future. It is strongly recommended for API clients to use the Tolerant Reader design pattern (see for example https://medium.com/digitalfrontiers/demystified-tolerant-reader-ca07d6bea602). The API may change backward-compatible without prior notice (e.g., new optional parameters may be added to the request, and new fields may be added to the response). The order of the fields in a returned JSON is not significant and may change.
Products
Product endpoints will return the following information about the products:
- Bluestone PIM ID
- Name
- Number
- Description
- Updated timestamp
- Attributes
- Media
- Labels
- Categories
- Relations
- Variant/bundle information
A single product can be fetched by PIM product ID using /products/{id}.
Products in a category can be fetched by category ID using /categories/{categoryId}/products. That can also include products in subcategories.
Search/filter products
If it is necessary to find products by other properties, the /products/list endpoint provides basic searching/filtering.
The request body must contain one or more of the following parameters. If more than one is supplied, it will work as a filter where all conditions must be met.
Property
- ids - Get products that match the given PIM product IDs.
- names - Get products that match the given names. Also matches part of the product name.
- Search for "Shirt" will match both "Shirt with tie" and "Blue Shirt".
- numbers - Get products with given numbers. The number is a changeable identification and will typically contain the product's ERP number. Can contain most characters despite being called "number".
- labels - Get products with given labels
- categories - Get products in given category IDs. Does not support subcategories.
- attributes - Get products with given attribute IDs assigned in PIM, regardless of value.
- attributeFilters - Get products with the given attribute numbers with given values. Attribute number is a changeable identification and can be used to map to external systems. Can contain most characters despite being called "number".
- relations - Get products with the given relation IDs.
- productTypes - Get products with the given product type. Alternatives:
- SINGLE
- GROUP
- VARIANT
- BUNDLE
- bundles - Get the bundle products the given ids are a part of.
{
"numbers": [
"123456",
"L64574"
]
}
{
"categories": [
"5d78f989590801000cd0915a",
"5d78f90252faff000e534359"
],
"attributeFilters": [
{
"number": "color",
"value": "Blue"
}
]
}
Categories
Usually, a product is organized into one or more categories in Bluestone PIM.
A category has the following information:
- Bluestone PIM ID
- Name
- Number
- Description
- Order of category in the parent category
- Media
- Order of products in category
All the root level categories sometimes referred to as catalogs, can be fetched with the endpoint or categories.
Each category can have many subcategories on multiple levels.
Use endpoint /categories/{categoryId} to get all sub-categories for a given category ID. If you expect a large category tree, this can return multiple levels, so consider splitting it into multiple calls.
Use /categories/{categoryId}/ancestors to find parent categories for a given category ID.
Relations
Use /relations to list all available relations.
Attributes
Use /attributes to list all available attribute definitions.
Syncs
Before something is visible in Public API, it must be published from PIM. This is an approval process to ensure product quality, usually done manually by managers in PIM. When something is published it gets synced to Public API. Use/syncs endpoint to get a list of sync events.
- Using the parameter createdAfter, it is possible to get sync events after a given timestamp.
- Using webhooks makes it possible to be informed when a sync is completed.
Tip! Use endpoints in Differences to see more information about the sync event.
Differences
See differences for products, categories, attributes, and relations given a sync ID.
This will list new, updated, or removed entities.
Contexts
Most endpoints will return information in a given context. Context is usually equivalent to language.
Get list of all available contexts with endpoint /contexts
Health
Use /health to see if Public API is responsive.