Aliases

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, Plone 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:

http

POST /plone/front-page/@aliases HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
    "items": [
        {
            "path": "/new-alias"
        },
        {
            "path": "/old-alias"
        },
        {
            "path": "/final-alias"
        }
    ]
}

curl

curl -i -X POST http://nohost/plone/front-page/@aliases -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"items": [{"path": "/new-alias"}, {"path": "/old-alias"}, {"path": "/final-alias"}]}' --user admin:secret

httpie

echo '{
  "items": [
    {
      "path": "/new-alias"
    },
    {
      "path": "/old-alias"
    },
    {
      "path": "/final-alias"
    }
  ]
}' | http POST http://nohost/plone/front-page/@aliases Accept:application/json Content-Type:application/json -a admin:secret

python-requests

requests.post('http://nohost/plone/front-page/@aliases', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'items': [{'path': '/new-alias'}, {'path': '/old-alias'}, {'path': '/final-alias'}]}, auth=('admin', 'secret'))

Response:

HTTP/1.1 204 No Content

Listing URL aliases of a Page#

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

http

GET /plone/front-page/@aliases HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i -X GET http://nohost/plone/front-page/@aliases -H "Accept: application/json" --user admin:secret

httpie

http http://nohost/plone/front-page/@aliases Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/front-page/@aliases', headers={'Accept': 'application/json'}, auth=('admin', 'secret'))

Response:

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

{
    "@id": "http://localhost:55001/plone/front-page/@aliases",
    "items": [
        {
            "datetime": "2022-05-05T00:00:00",
            "manual": true,
            "path": "/simple-alias",
            "redirect-to": "/front-page"
        }
    ],
    "items_total": 1
}

Removing URL aliases of a Page#

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

http

DELETE /plone/front-page/@aliases HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
    "items": [
        {
            "path": "/old-alias"
        }
    ]
}

curl

curl -i -X DELETE http://nohost/plone/front-page/@aliases -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"items": [{"path": "/old-alias"}]}' --user admin:secret

httpie

echo '{
  "items": [
    {
      "path": "/old-alias"
    }
  ]
}' | http DELETE http://nohost/plone/front-page/@aliases Accept:application/json Content-Type:application/json -a admin:secret

python-requests

requests.delete('http://nohost/plone/front-page/@aliases', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'items': [{'path': '/old-alias'}]}, auth=('admin', 'secret'))

Response:

HTTP/1.1 204 No Content

Adding URL aliases in bulk via JSON#

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:

http

POST /plone/@aliases HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
    "items": [
        {
            "datetime": "2022-05-05",
            "path": "/old-page",
            "redirect-to": "/front-page"
        },
        {
            "datetime": "2022-05-05",
            "path": "/fizzbuzz",
            "redirect-to": "/front-page"
        }
    ]
}

curl

curl -i -X POST http://nohost/plone/@aliases -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"items": [{"datetime": "2022-05-05", "path": "/old-page", "redirect-to": "/front-page"}, {"datetime": "2022-05-05", "path": "/fizzbuzz", "redirect-to": "/front-page"}]}' --user admin:secret

httpie

echo '{
  "items": [
    {
      "datetime": "2022-05-05",
      "path": "/old-page",
      "redirect-to": "/front-page"
    },
    {
      "datetime": "2022-05-05",
      "path": "/fizzbuzz",
      "redirect-to": "/front-page"
    }
  ]
}' | http POST http://nohost/plone/@aliases Accept:application/json Content-Type:application/json -a admin:secret

python-requests

requests.post('http://nohost/plone/@aliases', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'items': [{'datetime': '2022-05-05', 'path': '/old-page', 'redirect-to': '/front-page'}, {'datetime': '2022-05-05', 'path': '/fizzbuzz', 'redirect-to': '/front-page'}]}, auth=('admin', 'secret'))

Response:

HTTP/1.1 204 No Content

Adding URL aliases in bulk via CSV#

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

http

POST /plone/@aliases HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="test_file.csv"
Content-Type: text/csv

old path,new path,datetime,manual
/old-page,/front-page,2022/01/01 00:00:00 GMT+0,True

------WebKitFormBoundary7MA4YWxkTrZu0gW--

curl

curl -i -X POST http://nohost/plone/@aliases -H "Accept: application/json" -H "Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW" --data-raw '------WebKitFormBoundary7MA4YWxkTrZu0gW

Content-Disposition: form-data; name="file"; filename="test_file.csv"

Content-Type: text/csv



old path,new path,datetime,manual

/old-page,/front-page,2022/01/01 00:00:00 GMT+0,True



------WebKitFormBoundary7MA4YWxkTrZu0gW--' --user admin:secret

httpie

echo '------WebKitFormBoundary7MA4YWxkTrZu0gW

Content-Disposition: form-data; name="file"; filename="test_file.csv"

Content-Type: text/csv



old path,new path,datetime,manual

/old-page,/front-page,2022/01/01 00:00:00 GMT+0,True



------WebKitFormBoundary7MA4YWxkTrZu0gW--' | http POST http://nohost/plone/@aliases Accept:application/json Content-Type:"multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW" -a admin:secret

python-requests

requests.post('http://nohost/plone/@aliases', headers={'Accept': 'application/json', 'Content-Type': 'multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW'}, data='------WebKitFormBoundary7MA4YWxkTrZu0gW\r\n\nContent-Disposition: form-data; name="file"; filename="test_file.csv"\r\n\nContent-Type: text/csv\r\n\n\r\n\nold path,new path,datetime,manual\r\n\n/old-page,/front-page,2022/01/01 00:00:00 GMT+0,True\r\n\n\r\n\n------WebKitFormBoundary7MA4YWxkTrZu0gW--', auth=('admin', 'secret'))

Response:

HTTP/1.1 204 No Content

Listing all available aliases via JSON#

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

http

GET /plone/@aliases HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i -X GET http://nohost/plone/@aliases -H "Accept: application/json" --user admin:secret

httpie

http http://nohost/plone/@aliases Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/@aliases', headers={'Accept': 'application/json'}, auth=('admin', 'secret'))

Response:

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

{
    "@id": "http://localhost:55001/plone/@aliases",
    "items": [
        {
            "datetime": "2022-05-05T00:00:00",
            "manual": true,
            "path": "/fizzbuzz",
            "redirect-to": "/front-page"
        },
        {
            "datetime": "2022-05-05T00:00:00",
            "manual": true,
            "path": "/old-page",
            "redirect-to": "/front-page"
        }
    ],
    "items_total": 2
}

Listing all available aliases via CSV#

To download all aliases as a CSV file, send a GET request to the /@aliases endpoint on site root:

http

GET /plone/@aliases HTTP/1.1
Accept: text/csv
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i -X GET http://nohost/plone/@aliases -H "Accept: text/csv" --user admin:secret

httpie

http http://nohost/plone/@aliases Accept:text/csv -a admin:secret

python-requests

requests.get('http://nohost/plone/@aliases', headers={'Accept': 'text/csv'}, auth=('admin', 'secret'))

Response:

HTTP/1.1 200 OK
Content-Type: text/csv; charset=utf-8

old path,new path,datetime,manual
/fizzbuzz,/front-page,2022/05/05 00:00:00 GMT+0,True
/old-page,/front-page,2022/05/05 00:00:00 GMT+0,True

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.

http

GET /plone/@aliases?query=/fizzbuzz HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i -X GET 'http://nohost/plone/@aliases?query=/fizzbuzz' -H "Accept: application/json" --user admin:secret

httpie

http 'http://nohost/plone/@aliases?query=/fizzbuzz' Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/@aliases?query=/fizzbuzz', headers={'Accept': 'application/json'}, auth=('admin', 'secret'))

Response:

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

{
    "@id": "http://localhost:55001/plone/@aliases",
    "items": [
        {
            "datetime": "2022-05-05T00:00:00",
            "manual": true,
            "path": "/fizzbuzz",
            "redirect-to": "/front-page"
        }
    ],
    "items_total": 1
}

Bulk removing aliases#

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

http

DELETE /plone/@aliases HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
    "items": [
        {
            "path": "/old-page"
        }
    ]
}

curl

curl -i -X DELETE http://nohost/plone/@aliases -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"items": [{"path": "/old-page"}]}' --user admin:secret

httpie

echo '{
  "items": [
    {
      "path": "/old-page"
    }
  ]
}' | http DELETE http://nohost/plone/@aliases Accept:application/json Content-Type:application/json -a admin:secret

python-requests

requests.delete('http://nohost/plone/@aliases', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'items': [{'path': '/old-page'}]}, auth=('admin', 'secret'))

Response:

HTTP/1.1 204 No Content
Contents