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 all retrieved via My Relewise. Navigate to Administration -> API Keys, and copy the Dataset ID, the Server URL, and the API key.

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

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

A Note on API Keys

When you first gain access to My Relewise, 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.

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-package. 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 here.

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 npm or it can be referenced through CDN providers jsDelivr or UNPKG.

Additional examples may be found in our GitHub repository.

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

---

PHP

Our official SDK for PHP is available through Packagist.

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

---

Java

Our Java SDK can be found here.

You can also refer to our GitHub repository.

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 content 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.

Datakeys are Case Sensitive

Most datakeys in Relewise are case sensitive. Ensure that your data adheres to this case sensitivity to avoid unnecessary issues during implementation.

To learn more, click here.

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.

.NET

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

TS/JS

import { Tracker, UserFactory } from "@relewise/client"

const tracker = new Tracker("<Your dataset Id>", "<Your API Key>", { serverUrl: "<Your Server Url>" });

tracker.trackProductView({ 
  productId: 'p-1', 
  user: UserFactory.anonymous() 
})

PHP

use Relewise\Client\Tracker;
use Relewise\Client\UserFactory;

$tracker = new Tracker("<Your dataset Id>", "<Your API Key>", ["serverUrl" => "<Your Server Url>"]);

$tracker->trackProductView([
    'productId' => 'p-1',
    'user' => UserFactory::anonymous()
]);

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.