Owl Datahub (api.saws.de)
Create a Data Collection
To create a data collection, log in to the OWL. If you do not have an account yet, you can create one by using your license. (Register).
If the tile shown is deactivated, you do not yet have a data hub license. In this case, please contact sawsconnector@saws.de.
Click on “Data Collections”. A data collection is a collection of data records (usually product data) in a format defined by you. This data can later be accessed directly by your system or your customer. Depending on the type of derivation, this data can then be divided in different ways. E.g. one data record is a product in all languages, or one data record is a product in a specific language.
Tip: Try to store the data in a few collections and then feed them later to the different systems and applications via different data filters. This saves resources and makes updating the data faster. If in doubt, please ask us.
You can create a new collection by pressing the “+” button.
Give the data collection a simple name. The name will later be part of the URL to access the data.
The “Unique Key” is also important. This defines when a data record is created or an existing data record is updated when the collection is filled. The keys must be found in the transmitted data. If you do not send the attribute “sku” and “language” but, for example, “Article Number” and “LanguageShortName”, then this must be entered as a unique key.
When the collection has been saved, two further buttons appear with which you can delete the collection again or, if necessary, simply “truncate” it.
Creating a data filter
You can use a data filter to filter your collection records later depending on the API key. The simplest way to describe this is in an example.
Let’s assume you have a collection with many products and several suppliers should be able to access it. However, each of them should only be able to see their own products. To do this, you can filter the data on a “SupplierID” attribute located on the product data. Create the following filter for “Supplier A”.
To do this, go to the “Filter” tab and press the “+” button.
Write a data filter in JSON MongoDB format for supplier A and supplier B (MongoDB Filter Syntax) .
The overview should show the following.
We can then use these filters later for the access rights of the API keys. See below.
Create an API Key
An API Key defines the access rights of a client or a system to your data.
You can manage the API Key in this section
To create a new API key, press the “+” button.
You can also limit the API keys to IP addresses or time limits. So if you use a server-to-server connection, or you know the location address of a customer, then restrict access!
We strongly recommend limiting the access of the individual collections / API keys to IP addresses. Especially when it comes to server / server communications. This is an important security mechanism in addition to the key itself.
Here are a few examples of IP address specifications.
If the API key has been saved, you can copy, delete or renew it.
Attention: The access type “Token” is also available for the configuration. Use this facility if you are coming from api.contentserv.com, because at this moment the CS Cloud takes over the authentication!
Authorisation of an API key to a collection by means of a filter
If you have created an API key, a filter and a collection, you can now bring them together.
This can be done from an API perspective via the relations tab or, as shown in this example, via the Collection and the Permission tab.
To do this, open the desired collection and switch to the “Permission” tab.
Select the button “Add permission” there.
You can then select the respective API key and the filter. You can use the filters you created yourself or the “Unlimited” filter, which does not perform any filtering. Or you can select “No Access” to remove all rights for the API key.
To directly check which data the respective API key with the set filter sees, switch to the browser tab.
Select the API Key from the first drop-down list and press the “Search” button.
Querying data via api.saws.de
The appropriate URL for your product API can be found in the attachment dialogue of the Data Collection. It always follows this nomenclature:
https://api.saws.de/<<customershortname>>/<<data collection name>>
Authentication
There are several ways to authenticate yourself to api.saws.de. The simplest option is to use the API key.
This is given as a header in the GET or POST request. To do this, copy it from the OWL and enter it as a header variable with the name “x-api-key”. The best way to access this is with a common REST browser such as Postman or Yet another Rest Client
When you run the query, you should get a response in this format. The total number of records found in the data and the records delivered are according to your limit parameter.
Direct access to records
If you want to access records directly, you can do so by extending the URL with the unique keys you specified in the collection.
The URL expands with the respective keys
https://api.saws.de/<<customershortname>>/<<data collection name>>/<<unique key 1>> https://api.saws.de/<<customershortname>>/<<data collection name>>/<<unique key 1>>/<<unique key 2>>
Example: https://api.saws.de/sawscustomer/products/<<sku>>/ //delivere all records of the specific sku
Result:
Example: https://api.saws.de/sawscustomer/products/<<sku>>/<<language>> //delivere one record of the specific sku with the given language
Result:
Attention: If you choose the direct link to a record, the collection level (“products”) and the “count” parameter will be lost!
Filter
To filter the data, you can include a data filter in JSON format in the body. To do this, the data must be sent as POST. The filters correspond to the MongoDB filter
Examples:
or
{
"filter": {
"sku": "*2938",
"language": [ "de", "en" ]
}
}
or
{
"filter": {
"scchannel": [ "BM_HuberundSohn" ]
}
}
or
{
"filter": {
"scchannel": [ "BM_HuberundSohn" ]
}
}
or
{
"filter": {
"width": [ ">", 147 ]
}
}
Limitation of data columns
If you want to limit the data columns, you can specify the required columns in the attribute: fields in the body. When the data is delivered, only these columns are delivered.
Examples:
{
"fields": ["sku", "language", "name"],
"filter": {
"sku": "*2938",
"language": [ "de", "en" ]
}
}
Result:
Examples of GET:
https://api.saws.de/<<customershortname>>/<<data collection name>>?fields=[sku,language]
Limit of records
If you want to limit the data sets and query the data on packets, you can do this via the parameter limit.
Examples for POST:
{
"fields": ["sku", "language", "name"],
"limit" : "5" //retrieve 5 records beginning atoffset 0
"filter": {
"sku": "*2938",
"language": [ "de", "en" ]
}
}
or
{
"fields": ["sku", "language", "name"],
"limit" : "10,2" //retrieve 2 records beginning at offset 10
"filter": { "sku": "*2938", "language": [ "de", "en" ] } }
Examples of GET:
https://api.saws.de/<<customershortname>>/<<data collection name>>?limit=10,2
Sort of data
If you want to sort the data, you can do this with the parameter “sort”. The column name is also given. If only the name is given, then the data is sorted in ascending order. If a “-” is placed in front of the name, then it is sorted in descending order.
Examples for POST:
{
"fields": ["sku", "language", "name"],
"sort" : "-name"
"filter": {
"sku": "*2938",
"language": [ "de", "en" ]
}
}
Examples of GET:
https://api.saws.de/<<customershortname>>/<<data collection name>>?&sort=-name
Filter data by change date
The query for changed data is very important, as you usually only want to query the changed information. With the latest version of the data hub, it is now possible to query this not only at object level, but also at attribute level.
The following record shows you all changed objects with only the changed attributes (plus unique key) that have changed between 1 January 2024 and 10 September 2024.
Examples for POST:
{
"changes": {
"changed": {
"$gte": "2024-01-01 22:20:00+02" ,
"$lte": "2024-09-10 22:20:00+02"
}
}
}
If you want to have all attributes of all changed products, you have to add the fields parameter. Either with specific fields or with * for all fields.
Examples for POST:
{
"fields" : "*",
"changes": {
"changed": {
"$gte": "2024-01-01 22:20:00+02" ,
"$lte": "2024-09-10 22:20:00+02"
}
}
}
If you want to search only in specific fields for a change, like changes in price or stock in our example, you can add the field parameter also in the “changes” section.
Examples for POST:
{
"fields" : ["Label", "Supplier", "Price", "Stock"],
"changes": {
"field" : ["Price", "Stock"],
"changed": {
"$gte": "2024-01-01 22:20:00+02" ,
"$lte": "2024-09-10 22:20:00+02"
}
}
}
In Addtion you can add a standard object filter as well.
Examples for POST:
{
"fields" : "*",
"filter" : ["sku" : "4711*"],
"changes": {
"field" : ["Price", "Stock"],
"changed": {
"$gte": "2024-01-01 22:20:00+02" ,
"$lte": "2024-09-10 22:20:00+02"
}
}
}
Some additional Information about the filter:
The ‘changes’ attribut can be either an object or an array of objects [or filters].
A filter with the following attributes can be specified under ‘changes’:
field: Changes are only searched for in the specified fields [optional] changed: Period in which the last change must have been made.
Possible filters are: $gt = greater than $gte = greater than or equal $lt = lower than $lte = lower than or equal