Escaped URL paths for item URIs
When using item URIs as part of a URL, Core Service.REST requires that you escape the colon by replacing it with an underscore. For example, tcm:0-1-1 becomes tcm_0-1-1. This is to prevent ASP.NET validation from falsely evaluating the URLs as unsecure.
Content Manager uses a single URI (Uniform Resource Identifiers) for each identifiable Content Manager object. This format presents a challenge to the Core Service.REST API wherever you want to include the URI as part of a URL path. URIs that are part of a URL path are called escaped URI in the Swagger definition, and you should use an escaped form of the URI there.
For example, the path http://localhost:81/api/items/tcm:0-1-1 is intended to retrieve the item with the ID tcm:0-1-1; however, ASP.Net validation (as a default) considers such a URL to be unsecure because of the URI's colon. To prevent this false evaluation within the Microsoft IIS web server, the API requires that you use the escaped form of the ID in URL references.
By contrast, URIs that are part of a URL parameter (that is, URIs that occur anywhere beyond the ? character in a URL) are still called URIs, and a regular colon should continue to be used there.
For example, the URL http://localhost:81/example?foo:bar is intended to pass a parameter foo:bar, which does not need to be escaped.
You can integrate the following code snippet into your client to transform unescaped URIs into escaped ones:
internal static class TcmUtils
{
internal static string EscapeUri(this string tcmUri)
=> string.IsNullOrEmpty(tcmUri) ? tcmUri : tcmUri.Replace(":", "_");
}