Relewise Documentation

Getting started

Welcome to the getting started page for developers. If you are new to Search and Recommendation Engine APIs we recommend you first check out introductions to the Building Blocks before you continue.

Otherwise, you need to do the 3 steps below to be ready for implementation.

1. Ensure you have access

To work with our services you need access to the system - more specifically a server URL, a DataSetId and an API Key. These are both retrieved via My Relewise. Navigate to Settings -> Developer Settings, and copy both the Dataset ID and the API key.

Developer Settings in My Relewise

You need the Dataset and API Key

We recommend that you have access to the site yourself, so you can see live API calls along with other helpful information about your live API calls there. To gain access to MyRelewise, simply reach out to us and request access.

A Note on API Keys

When you first gain access to MyRelewise, you will find a single API key available to you - the Master Key. Please note that this key cannot be used to complete API calls from a browser, among other things. This is done as a safety precaution, to prevent anyone from gaining unwanted access to your dataset via a key and having immediate access to every facet of your Relewise data.

As such, when you are about to start implementing Relewise on your site, make sure to create a new API key for each new area you want to work in, and provide it with the least necessary permissions required. By not granting more access than is minimally required, you maintain the highest level of security. You are not limited in the amount of keys you can create, and can always revoke the ones created, making it easy to maintain a high level of security.

Server URL

In addition to the Dataset ID and the API key, you must make sure to point your API calls to the correct server. To find your server address, log in to MyRelewiseopen in new window and navigate to Settings -> Developer Settings. Here, you will find your server URL on the right hand side:

The Relewise ServerURL is located under Developer Settings

Keep in mind that different datasets will point to different servers depending on the purpose of the dataset, so you should always double check MyRelewise to ensure you are pointing your calls towards the correct server.

2. Choose your technology

Of course, any technology can be used to talk with our API, but if you use one of the below, you can get started even faster.

.NET

If you are using .NET Technology we recommend our official NuGet-packageopen in new window. It's .NET Standard - meaning it works with both .NET Framework, .NET Core, .NET 5, and .NET 6.

There is also an optional Extensions-library to help configure the Relewise Client via app settings. More information about the Extensions-library can be found hereopen in new window.

For hands-on examples of using the .NET package, please refer to our .NET examples page.

TypeScript / JavaScript

Our official SDK for TypeScript and JavaScript is available through npmopen in new window or it can be referenced through CDN providers jsDelivropen in new window or UNPKGopen in new window.

Additional examples may be found in our GitHub repositoryopen in new window.

For usage examples in Javascript please referer to our TS/JS examples page.

PHP

Our official SDK for PHP is available through Packagistopen in new window.

For examples of using the PHP SDK, refer to our PHP examples page.

Java

Our Java SDK can be found via Mavenopen in new window.

You can also refer to our GitHub repositoryopen in new window.

For examples of how to use the Java SDK, please refer to our Java Examples page.

3. Authenticate

The Relewise API uses API Keys for authentication. As mentioned above, all datasets have a master API key that has access to all API calls. This means it can create or delete products and contents etc. so you must keep that key safely guarded.

The Master Key does not permit calls from the browser, among other things, which necessitates the creation of additional, segmented keys. We urge you to be liberal in making these keys, since you can have as many as you want, and having more keys for specialized use makes for greater security in the long term.

Make sure you are using a generated key, and not the Master key, when authenticating your connection. If you do not, the master key will reject the connection.

The dataset ID is used in the URL when making API calls to Relewise, and the API key is parsed as a header value with the Authorization-header.

Below is an example of a tracking request sent to Relewise, which is one of the first things you will do when implementing our system. The request tracks that a user has viewed a product.

curl -X POST https://api.relewise.com/<DatasetId>/v1/TrackProductViewRequest
   -H 'Content-Type: application/json'
   -H 'Authorization: APIKey <Your API Key>'
   -d '{
            "ProductView": {
                "Product": {
                    "Id": "p-1"
                }
            }
        }'

Here is the same tracking in .NET:

var apiKeySecret = "<Your API Key>";
var datasetId = Guid.Parse("<DatasetId>");
Relewise.Client.ITracker tracker = new Tracker(datasetId, apiKeySecret);
await tracker.TrackAsync(
   new ProductView(
       User.ByTemporaryId("<unique Id>"), //Depend on how much you know about the user
       new Product("p-1")
       )
   );

And here in Javascript:

<script src="https://cdn.jsdelivr.net/npm/@relewise/client/dist/relewise.min.js"></script>

<script lang="js">
    const tracker = new Relewise.Tracker('<Your dataset Id>', '<Your API Key>');
    tracker.trackProductView({ 
        productId: 'p-1', 
        user: Relewise.UserFactory.anonymous() 
    })
</script>

With authentication complete, you are ready to proceed in your integration of Relewise. We urge you to read our Best Practices to ensure that you set things up correctly the first time around.

ContactCookies, Privacy & TermsAPI Reference