< Back
Print

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": [ "&gt", 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

Statistic of a Collection

If you want to query the statistics and also the API version of a collection, you can do this via the stats route.

Examples of GET:

https://api.saws.de/<<customershortname>>/stats/<<data collection name>>

Result:

Was this article helpful?
How can we improve this article?
Please submit the reason for your vote so that we can improve the article.
Table of Contents