unatrix-rest-api

Connect with the Unatrix REST API.

• unatrix-rest-api
  • 1. Requirements
  • 2. Local Testing (for developing)
  • 3. Official documentation
  • 4. Install
    • 4.1. Unatrix secrets
    • 4.2. Unatrix request
  • 5. Usage
    • 5.1. Single item
    • 5.2. Multiple items
    • 5.3. List
  • 6. Release a new version

1. Requirements

• PHP
• JavaScript

2. Local Testing (for developing)

Retreive the current version from package.json and insert into VERSION_NUMBER

VERSION_NUMBER=1.1.0
npm run format && npm run lint && npm run build && npm pack --pack-destination ~ && cd ~/Documents/projects/wp-apriori/theme && npm rm @friendventure/unatrix-rest-api && npm i ~/friendventure-unatrix-rest-api-${VERSION_NUMBER}.tgz && cd -

3. Official documentation

I found this old document burried in the code of the very old WordPress website of our client (not written by Friendventure). The document is from 2012, but seems to work. That is why this node modules functionality is based on the old document.

Unatrix_API.pdf

The latest documentation is API.html which has been sent to Friendventure on 10.10.2023 (after completing this node module).

4. Install

npm i @friendventure/unatrix-rest-api

4.1. Unatrix secrets

Create a file unatrix-secrets.php. This file will be required by the Unatrix request. Fill in the UNATRIX_TOKEN. You can get that from the client. Find a value for UNATRIX_IDENTIFIER and make sure in every JavaScript request you send to the Unatrix request you use the same value.

<?php

/** A $_GET parameter name that is used to identify an advertisement from Unatrix. The parameter value is expected to be the ID of any advertisement. It does not matter what string you choose, as long as you make sure it is also written the exact same way in non-PHP files like Twig-files. You need to re-save permalinks in WordPress after changing this value. */
if (!defined("UNATRIX_GET_PARAM")) define("UNATRIX_GET_PARAM", "unatrixId");

/** Secret Unatrix token. The API is from 2012 and a bit dangerous. With this key we can READ, WRITE, UPDATE and DELETE. Keep this very secret!!! */
if (!defined("UNATRIX_TOKEN")) define("UNATRIX_TOKEN", "xxx-xxx-xxx");

/** Identifier to reduce posts from unauthorized sources. Include this in the body of any post. */
if (!defined("UNATRIX_IDENTIFIER")) define("UNATRIX_IDENTIFIER", "xxx-xxx-xxx");

4.2. Unatrix request

Create a file unatrix.php and make it accessible under the URL defined in ConstructorOptions['phpFetchFile']. This file can send requests to Unatrix and outputs the response as a JSON string.

<?php

/** This file exists, because we need to protect the UNATRIX_TOKEN. Sending a request with JavaScript would reveal that UNATRIX_TOKEN. */

// Avoid access to this file with incorrect data
$data = file_get_contents('php://input');

/** Fetch request body */
$request = json_decode($data);

/**
 * We expect the body to have an identifier (this is public so not a very good safety feature but it should avoid basic attacks or exploits)
 * @example body: JSON.stringify({ identifier: 'xxx-xxx-xxx' }),
 */
if ($request->identifier !== UNATRIX_IDENTIFIER) {
  http_response_code(404);
  die;
}

require_once "./unatrix-secrets.php";

/** Search Params. We just append what was sent with JavaScript */
$params = parse_url($_SERVER['REQUEST_URI'], PHP_URL_QUERY);

/**
 * Unatrix REST API request URL
 * @var $requestUrl Unatrix request
 * @example https://apriori.unatrix.com/api.php/{UNATRIX_TOKEN}/advertisements.json?language=de&page=1&per_page=15&filter[category_1_id]=84&filter[category_3_id]=73
 */
$requestUrl = "$request->unatrixHost/" . UNATRIX_TOKEN;

// Add method (e.g. advertisements.json)
$requestUrl .= urldecode($request->unatrixMethod);

// Add parameters (?language=de&foo=...)
$requestUrl .= "?" . $params;

// Make the call
if ($curl = curl_init()) {
  curl_setopt($curl, CURLOPT_URL, $requestUrl);
  curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

  // Return the JSON data
  $rawJsonData = curl_exec($curl);
  // $http_code = curl_getinfo($curl, CURLINFO_HTTP_CODE);

  echo $rawJsonData;
}

5. Usage

5.1. Single item

To get the data for a single advertisement:

import { UnatrixGetSingleAdvertisementById } from '@friendventure/unatrix-rest-api';

/** @type {import('@friendventure/unatrix-rest-api').UnatrixResponseAdvertisement} Will return data with the latest 4 advertisements */
const data = await UnatrixGetSingleAdvertisementById({
  id: '123456',
  fetchRequestIdentifier: 'xxx-xxx-xxx',
  phpFetchFile: `${window.location.origin}/api/unatrix.php`,
});

const advertisement = data.ad;

5.2. Multiple items

To get the data for multiple advertisements:

import { UnatrixGetAdvertisements } from '@friendventure/unatrix-rest-api';

/** @type {import('@friendventure/unatrix-rest-api').UnatrixResponseAdvertisements} Will return data with the latest 4 advertisements */
const data = await new UnatrixGetAdvertisements({
  fetchRequestIdentifier: 'bas9n-sasd8h23nrh',
  phpFetchFile: `${window.location.origin}/api/unatrix.php`,
  parameters: {
    per_page: 4,
    page: 1,
    language: 'de',
  },
});

/** The advertisements */
const advertisements = data.pager.results;

5.3. List

Display a list of items from Unatrix. The results can be searched and filtered.

import { UnatrixList } from '@friendventure/unatrix-rest-api';

const unatrix = new UnatrixList({
  listElement: component.querySelector('ul.items'),
  loadMoreTrigger: component.querySelector('div.loadMore'),
  noResultsElement: component.querySelector('div.noResults'),
  loaderElement: component.querySelector('div.loader'),
  inputSearch: component.querySelector('input[name="text"]'),
  inputLocation: component.querySelector('input[name="location"]'),
  filterElementForCategory1: component.querySelector('select[name="jobType"]'),
  filterElementForCategory3: component.querySelector('select[name="employer"]'),
  filterElementForCategory4: component.querySelector(
    'select[name="contractType"]',
  ),
  template: BasisJobKachelTemplate,
  fetchRequestIdentifier: 'xxx-xxx-xxx',
  phpFetchFile: `${window.location.origin}/api/unatrix.php`,
});

const BasisJobKachelTemplate = (options) => {
  console.log(options.item); // Data for single application

  return `<div>${options.item.title}</div>`;
};

6. Release a new version

npm version patch|minor|major
npm publish --access public