Aliases

A mechanism to redirect old URLs to new ones.

When an object is moved (renamed or cut/pasted into a different location), the redirection storage will remember the old path. It is smart enough to deal with transitive references (if we have a -> b and then add b -> c, it is replaced by a reference a -> c) and circular references (attempting to add a -> a does nothing).

The API consumer can create, read, and delete aliases.

Verb	URL	Action
POST	/@aliases	Add one or more aliases
GET	/@aliases	List all aliases
DELETE	/@aliases	Remove one or more aliases

Adding new URL aliases for a Page

By default, Nick automatically creates a new alias when an object is renamed or moved. Still, you can also create aliases manually.

To create a new alias, send a POST request to the /@aliases endpoint:

POST /news/@aliases HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk
Content-Type: application/json

{
  "items": [
    {
      "path": "/news-items" 
    },
    {
      "path": "/news-posts" 
    }
  ]
}

Or use the client directly:

import { Client } from '@robgietema/nick';

const cli = Client.initialize({ apiPath: 'http://localhost:8080' });
const login = await cli.login({ username: 'admin', password: 'admin' });

const { data } = await cli.createAliases({
  token: login.data.token,
  path: '/news',
  data: {
    items: [
      {
        path: '/news-items',
      },
      {
        path: '/news-posts',
      },
    ],
  },
});

Response:

HTTP/1.1 201 Created

Listing URL aliases of a Page

To list aliases, you can send a GET request to the /@aliases endpoint:

GET /news/@aliases HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

Or use the client directly:

import { Client } from '@robgietema/nick';

const cli = Client.initialize({ apiPath: 'http://localhost:8080' });
const login = await cli.login({ username: 'admin', password: 'admin' });

const { data } = await cli.getAliases({
  token: login.data.token,
  path: '/news',
});

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:8080/news/@aliases",
  "items": [
    {
      "datetime": "2022-04-08T16:00:00.000Z",
      "manual": true,
      "path": "/news-items",
      "redirect-to": "/news"
    },
    {
      "datetime": "2022-04-08T16:00:00.000Z",
      "manual": true,
      "path": "/news-posts",
      "redirect-to": "/news"
    }
  ],  
  "items_total": 2
}

Removing URL aliases of a Page

To remove aliases, send a DELETE request to the /@aliases endpoint:

DELETE /news/@aliases HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

{
  "items": [
    {
      "path": "/news-items"
    }
  ]
}

Or use the client directly:

import { Client } from '@robgietema/nick';

const cli = Client.initialize({ apiPath: 'http://localhost:8080' });
const login = await cli.login({ username: 'admin', password: 'admin' });

const { data } = await cli.deleteAliases({
  token: login.data.token,
  path: '/news',
  data: {
    items: [
      {
        path: '/news-items',
      },
    ],
  },
});

Response:

HTTP/1.1 204 No Content

Adding URL aliases in bulk

You can add multiple URL aliases for multiple pages by sending a POST request to the /@aliases endpoint on site root using a JSON payload. datetime parameter is optional:

POST /@aliases HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk
Content-Type: application/json

{
  "items": [
    {
      "path": "/news-items",
      "redirect-to": "/news"
    },
    {
      "path": "/news-posts",
      "redirect-to": "/news"
    },
    {
      "path": "/event-posts",
      "redirect-to": "/events"
    }
  ]
}

Or use the client directly:

import { Client } from '@robgietema/nick';

const cli = Client.initialize({ apiPath: 'http://localhost:8080' });
const login = await cli.login({ username: 'admin', password: 'admin' });

const { data } = await cli.createAliases({
  token: login.data.token,
  data: {
    items: [
      {
        path: '/news-items',
        'redirect-to': '/news',
      },
      {
        path: '/news-posts',
        'redirect-to': '/news',
      },
      {
        path: '/event-posts',
        'redirect-to': '/events',
      },
    ],
  },
});

Response:

HTTP/1.1 201 Created

Listing all available aliases

To list all aliases, send a GET request to the /@aliases endpoint on site root:

GET /@aliases HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

Or use the client directly:

import { Client } from '@robgietema/nick';

const cli = Client.initialize({ apiPath: 'http://localhost:8080' });
const login = await cli.login({ username: 'admin', password: 'admin' });

const { data } = await cli.getAliases({
  token: login.data.token,
});

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:8080/@aliases",
  "items": [
    {
      "datetime": "2022-04-08T16:00:00.000Z",
      "manual": true,
      "path": "/news-items",
      "redirect-to": "/news"
    },
    {
      "datetime": "2022-04-08T16:00:00.000Z",
      "manual": true,
      "path": "/news-posts",
      "redirect-to": "/news"
    },
    {
      "datetime": "2022-04-08T16:00:00.000Z",
      "manual": true,
      "path": "/event-posts",
      "redirect-to": "/events"
    }
  ],  
  "items_total": 3
}

Filter aliases

Parameters

All of the following parameters are optional.

Name	Type	Description
query	string	Full-text search. Can match paths or text fields.
manual	boolean	Filter by manual or automatically created redirects.
start	string	Filter redirects created after this date.
end	string	Filter redirects created before this date.
b_start	integer	Batch start index (offset).
b_size	integer	Batch size (maximum items returned).

To search for specific aliases, send a GET request to the @aliases endpoint with one or more of the above named parameters as shown in the following example.

GET /@aliases?query=/news HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

Or use the client directly:

import { Client } from '@robgietema/nick';

const cli = Client.initialize({ apiPath: 'http://localhost:8080' });
const login = await cli.login({ username: 'admin', password: 'admin' });

const { data } = await cli.getAliases({
  token: login.data.token,
  query: {
    query: '/news',
  },
});

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:8080/@aliases",
  "items": [
    {
      "datetime": "2022-04-08T16:00:00.000Z",
      "manual": true,
      "path": "/news-items",
      "redirect-to": "/news"
    },
    {
      "datetime": "2022-04-08T16:00:00.000Z",
      "manual": true,
      "path": "/news-posts",
      "redirect-to": "/news"
    }
  ],  
  "items_total": 2
}

Bulk removing aliases

To bulk remove aliases send a DELETE request to the /@aliases endpoint on site root:

DELETE /news/@aliases HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

{
  "items": [
    {
      "path": "/news-items"
    }
  ]
}

Or use the client directly:

import { Client } from '@robgietema/nick';

const cli = Client.initialize({ apiPath: 'http://localhost:8080' });
const login = await cli.login({ username: 'admin', password: 'admin' });

const { data } = await cli.deleteAliases({
  token: login.data.token,
  path: '/news',
  data: {
    items: [
      {
        path: '/news-items',
      },
    ],
  },
});

Response:

HTTP/1.1 204 No Content