View source for Documentation:Improved routes

You can use improved routes to create shorter, product-neutral URLs for Turnkey Angular applications, MVC views, and REST endpoints while keeping existing routes working.
== Overview ==
Improved routes are alternative URL formats for applications hosted by [[Documentation:Turnkey local development tips|Turnkey]]. They remove <code>Turnkey</code> and <code>AngularApp</code> from application URLs, put the MVC view name before its object reference, and put the REST [[Documentation:ViewModel|ViewModel]] name before the HTTP verb.

The older route formats continue to function. Update links, bookmarks, integrations, and generated documentation to the improved format when you want the new URL structure. Do not assume that existing application links are automatically rewritten.
== Route formats ==
Replace <code>http://localhost:5052</code> in the examples with the host and port where your application runs.

{| class="wikitable"
! Area
! Older route
! Improved route
|-
| Angular application
| <code>http://localhost:5052/Turnkey/AngularApp#/ViewOneThing/11!1</code>
| <code>http://localhost:5052/App#/ViewOneThing/11!1</code>
|-
| MVC view
| <code>http://localhost:5052/Turnkey/Display/11!1?view=ViewOneThingCopy</code>
| <code>http://localhost:5052/MVC/ViewOneThingCopy/11!1</code>
|-
| REST GET, object reference as a query parameter
| <code>http://localhost:5052/TurnkeyRest/Get?command=ViewOneThing&amp;id=11!1</code>
| <code>http://localhost:5052/Rest/ViewOneThing/Get?id=11!1</code>
|-
| REST GET, object reference as a path segment
| Not shown in the older format
| <code>http://localhost:5052/Rest/ViewOneThing/Get/11!1</code>
|}

In these examples:

* <code>ViewOneThing</code> and <code>ViewOneThingCopy</code> are [[Documentation:ViewModel|ViewModel]] names.
* <code>11!1</code> is the root object reference used by the view.
* <code>Get</code> is the REST verb.

Here are examples of improved routes compared to their older equivalents:
<message>Write the content here to display this box</message>
<pre>
        // Better routes App,MVC,Rest
        /// APP
        /// http://localhost:5052/Turnkey/AngularApp#/ViewOneThing/11!1           old
        /// http://localhost:5052/App#/ViewOneThing/11!1                          improved
        /// 
        /// MVC
        /// http://localhost:5052/Turnkey/Display/11!1?view=ViewOneThingCopy      old
        /// http://localhost:5052/MVC/ViewOneThingCopy/11!1                       improved
        /// 
        /// Rest
        /// http://localhost:5052/TurnkeyRest/Get?command=ViewOneThing&id=11!1    old
        /// http://localhost:5052/Rest/ViewOneThing/Get?id=11!1                   improved
        /// http://localhost:5052/Rest/ViewOneThing/Get/11!1                      also improved</pre>Routes have been added, but applications will not use them yet (210314).
== Use an improved application route ==
Use the <code>/App</code> route when linking directly to an Angular application view.

# Identify the ViewModel route and root object reference used by the existing application URL.
# Replace <code>/Turnkey/AngularApp#</code> with <code>/App#</code>.
# Keep the view route and object reference after the hash unchanged.
# Test the link in the deployed application.

For example, change:

<code>http://localhost:5052/Turnkey/AngularApp#/ViewOneThing/11!1</code>

to:

<code>http://localhost:5052/App#/ViewOneThing/11!1</code>
== Use an improved MVC route ==
Use the <code>/MVC</code> route when opening an MVC view. The improved route places the ViewModel name directly after <code>/MVC</code> and the object reference after the view name.

# Find the <code>view</code> query parameter in the older URL.
# Place that ViewModel name after <code>/MVC/</code>.
# Move the <code>id</code> value to the final path segment.
# Remove the older <code>/Turnkey/Display/</code> path and <code>?view=</code> query parameter.

For example, change:

<code>http://localhost:5052/Turnkey/Display/11!1?view=ViewOneThingCopy</code>

to:

<code>http://localhost:5052/MVC/ViewOneThingCopy/11!1</code>
== Use an improved REST route ==
Use the <code>/Rest</code> route to expose a ViewModel as a REST endpoint. REST access is not enabled by the URL alone: set the <code>RestAllowed</code> tagged value on the ViewModel, then ensure that the caller is permitted by the ViewModel access groups. For the full setup, request handling behavior, and JSON response options, see [[HowTos:Expose REST Service]].

The base improved REST pattern is:

<code>&lt;host&gt;/Rest/&lt;ViewModelName&gt;/&lt;Verb&gt;/&lt;rootobjref&gt;</code>

You can instead provide the object reference as the <code>id</code> query parameter:

<code>&lt;host&gt;/Rest/&lt;ViewModelName&gt;/&lt;Verb&gt;?id=&lt;rootobjref&gt;</code>

For example, these two GET URLs address the same ViewModel and root object:

<code>http://localhost:5052/Rest/ViewOneThing/Get?id=11!1</code>

<code>http://localhost:5052/Rest/ViewOneThing/Get/11!1</code>
=== REST verbs ===
The improved route format supports <code>Get</code>, <code>Post</code>, <code>Put</code>, <code>Patch</code>, and <code>Delete</code>. The ViewModel variable <code>vRestVerb</code>, when declared, receives the verb used for the request.

{| class="wikitable"
! Example
! Meaning
|-
| <code>/Rest/ViewOneThing/Get/11!1</code>
| Gets REST output from <code>ViewOneThing</code> for the supplied root object.
|-
| <code>/Rest/ViewOneThing/Put/11!1</code>
| Calls the same ViewModel using the <code>Put</code> verb; <code>vRestVerb</code> receives <code>Put</code> when that variable exists.
|}
=== Pass ViewModel variables ===
Declare String variables in the ViewModel to receive additional request parameters. Add them as URL query parameters.

For example, if <code>ViewOneThing</code> declares String variables <code>MyVar</code> and <code>MyOtherVar</code>, call:

<code>http://localhost:5052/Rest/ViewOneThing/Get/11!1?MyVar=hello&amp;MyOtherVar=world</code>

Use a complete object ID. A GUID or an ID in the form <code>xx|yyyy</code> is appropriate; an abbreviated ID without a class identifier can cause problems.
=== Control actions by verb ===
Use an action's Disable/ReadOnly expression to control which actions run for a REST verb. For example, the expression below makes an action read-only for every verb except <code>Put</code>:

<syntaxhighlight lang="ocl">
vRestVerb&lt;&gt;'Put'
</syntaxhighlight>
== Handle invalid routes ==
When a requested page cannot be found, Turnkey redirects to a ViewModel named <code>RedirectView</code>. You can use that ViewModel to show a user-friendly error, redirect users to a valid page, or implement URL shortcuts. See [[Documentation:Redirection page]] for the required variables and implementation details.
== Why use improved routes? ==
Improved routes:

* Are shorter than the older equivalents.
* Do not expose <code>Turnkey</code> in the URL path.
* Do not expose <code>AngularApp</code> in the Angular application URL.
* Place the MVC ViewModel before the object reference.
* Place the REST ViewModel before the verb.
== See also ==
* [[HowTos:Expose REST Service]]
* [[Documentation:Redirection page]]
* [[Documentation:Navigation]]
* [[Documentation:Turnkey local development tips]]

[[Category:Exposing REST from the model (overview)]]
[[Category:Integration Touchpoints]]
[[Category:Intermediate-Friendly]]
[[Category:Priority 50]]