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 201 Created
Content-Type: application/json

{
    "@id": "http://localhost:55001/plone/front-page/@aliases",
    "items": [
        {
            "path": "/simple-alias"
        }
    ],
    "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 201 Created
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 201 Created
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

To search for specific aliases, send a GET request to the /@aliases endpoint on site root with a q parameter:

http

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

curl

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

httpie

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

python-requests

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

Response:

HTTP/1.1 201 Created
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