How-to library · Developer docs

How-to library

Task-shaped pages: a title that starts with a verb, the situation in a few lines, the steps, the working code in both engines, and why this way rather than another. Found from a search, done, and left.

How-to APIs and JavaScript

Set and clear a custom URL through the API

Published

customUrl takes an object with url. Set it in a request after the record exists, start the path with a slash, clear it with an empty url rather than null, and expect a 422 when another record already holds the address.

Context

Context. A migration has to keep each old address, or a campaign needs a short one, and the records are written by a script rather than an editor. A custom URL replaces the address made from the record's slugs, on pages, books, blog posts, blogs, FAQ records, custom entity records and product descriptions. What it is for, and how it behaves for visitors, is in Give a record a second URL; this is the API side.

Before you start

Credentials for a backend user who may edit the record, and the record's id: a custom URL is set on an existing record.

Steps

  1. Create the record first, if it is new. A custom URL cannot be set in the request that creates the record.
  2. Send {"customUrl": {"url": "/campaign-name"}} on the record's edit route, with a leading slash: the path is stored exactly as sent.
  3. Read fullPath and customUrl{id,url} back in the same request: fullPath becomes the custom URL, and originalFullPath keeps the address from the slugs.
  4. To remove it, send {"customUrl": {"url": ""}}. The record goes back to its own address.
  5. If the old address must keep working after a change, add a rewrite; changing or clearing a custom URL leaves nothing behind at the old one.

Code

HTTP Set 
PUT /cdna-api/pages/page/1885?properties={id,fullPath,customUrl{id,url}}
Content-Type: application/json

{"customUrl": {"url": "/api-sandbox-custom-url"}}

# 200 {"result":"success","data":{"id":1885,"fullPath":"/api-sandbox-custom-url","customUrl":{"id":4,"url":"/api-sandbox-custom-url"}},"message":"The Page has been saved successfully."}
HTTP Clear 
PUT /cdna-api/pages/page/1885?properties={id,fullPath,customUrl{id,url}}
Content-Type: application/json

{"customUrl": {"url": ""}}

# 200 {"result":"success","data":{"id":1885,"fullPath":"/api-sandbox","customUrl":null},"message":"The Page has been saved successfully."}

Both are real answers on this site's sandbox page. The failures it gave on the way:

RequestAnswer
{"customUrl": null}Not the way to clear it, even though null clears other relations: refused with a 500, "Cannot use object of type …FillValue as array"
A URL another record already has, of any type422, "This value is already used." on customUrl.url
{"customUrl": {"url": "api-sandbox-no-slash"}}200, saved as written: fullPath came back as api-sandbox-no-slash, with no slash, which breaks every link built from it

Why this and not that

Not customUrl in the create request: it is not bound there, so a script that creates and sets in one call ends up with records on their default address; make it two calls and check the second answer. Not null to clear, even though null clears every other relation. Not a check-then-set without handling the 422: another write can take the address in between. And for a migration of many records, decide first between custom URLs (the old address stays the real one) and rewrites (the old address redirects to the new one); Custom URLs and slugs weighs the two.

Go deeper
GuideCustom URLs and slugs How-toGive a record a second URL with a custom URL ReferenceEdit a page: API reference

Was this page helpful?

Your answer goes to the docs team.