Request URL

19.0.0 released Nov 08, 2023

Request URL

A request URL is a URL that calls your Vely code. Aside from the scheme, domain and port, it's made up of:

application path,
request path, and
parameters.

Here's a breakdown of URL structure:

<scheme>://<domain>[:<port>]<application path><request path><parameters>

For example, in the following URL, "/my_app" is application path, "/my_request" is request path and "/par1/val1?par2=val2" are parameters "par1" and "par2" with values "val1" and "val2":

https://your.website.com/my_app/my_request/par1/val1?par2=val2

Application path

The leading part of URL's path is called "application path". By default, application path is the application name (see how-vely-works); if it's "shopping", then the default application path is:

/shopping

Application name can contain alphanumerical characters, underscores and hyphens.
- Customizing application path
You can change the application path. To do that, you need to specify it when you make your application (see vv); each application has its own unique application path. Note that whatever it may be, the application name must always be its last path segment. For example, if your application name is "shopping", then the application path may be:

/api/v2/shopping

Use "--path" parameter in vv to set the application path:

vv -q --path="/api/v2/shopping"

Request path

Request path follows the application path, and by default it's the request name preceded with a forward slash, for instance:

https://some.web.site/shopping/buy-item

In this case the application path is "/shopping" and the request path is "/buy-item" (which means the request name is "buy_item"). Note that hyphen ("-") in the URL name is always converted to underscore ("_") for a Vely request name (this is true also for all input parameters, see input-param). The reason is that a hyphen cannot be a part of C identifier (such as a function or a variable). Since the source file name must match the request name, the .vely file that implements this request must be "buy_item.vely".

A request name can be made up of alphanumeric characters or underscore ("_") only, and cannot start with a digit.
- Hierarchical request path
Note that two underscores in the request name can be substituted for a forward slash in the URL. This way, a request name can also be written as a resource path, given as a number of path segments. In this case such path must start and end with an underscore. For instance, a request name may be "items__wine_collection__red_wine" and the request path is then "/_items/wine-collection/red-wine_":

https://some.web.site/shopping/_items/wine-collection/red-wine_/

In this case "/shopping" is the application path (and "shopping" is the application name), while "/items/wine-collection/red-wine" is the request path, while "items__wine_collection__red_wine" is the request name, with hyphens and forward slashes replaced with single and double underscores. Note that you could also write the beginning and ending of a request path as a path segment consisting of an underscore alone (i.e. as "/_/"):

https://some.web.site/shopping/_/items/wine-collection/red-wine/_/

The name of .vely file that implements such a request would be:

items__wine_collection__red_wine.vely

This makes it easy to identify the source .vely files that handles the request, as Vely source code directory is flat (and all requests are visible at a glance), and it is easy to visually tell the request path based on the name of a source file.

You can also make this same call by using hyphens (or underscores), for instance:

https://some.web.site/shopping/items--wine-collection--red-wine

Parameters in URL

The actual input parameters follow after the request path, and can be specified in a number of ways.
- Query string
Parameters can be specified after a question mark in a "name=value" form, where values are generally URL encoded. For example, the full URL may be:

https://some.web.site/shopping/buy-items?sku=4811&price=600

Here, the required request name is "buy_item" and there are two other parameters ("sku" and "price") with values of "4811" and "600" respectively (see request).
- Path segments
The input parameters can also be specified as path segments in the form of "/name/value". So for example, the above URL can be:

https://some.web.site/shopping/buy-item/sku/4811/price/600

- Double path segments
Another way to specify parameters is to specify name and value separated by an equal sign within a single path segment:

https://some.web.site/shopping/buy-item/sku=4811/price=600/

This way, you can have a readable representation of parameter names and values, while still maintaining the hierarchical form which conveys how are the parameters structured.
- Mixed
You can specify some or a mix of the above ways to write parameters, for instance the above URL can be written as:

https://some.web.site/shopping/buy-item/sku/4811?price=600

- End-point
The very last path segment can miss a value, and by default it would be "true", so if you add a parameter "edit":

https://some.web.site/shopping/buy-item/sku/4811/price/600/edit

then this would be the same URL as before with the additional parameter "edit" of value "true". This is useful to specify an action that follows the resource specified in the URL.

Parameters in Vely program

It is up to you how to structure your parameters, i.e. the order in a query path or path segments, and which ones (if any) are in a query string. Regardless of your choices, the code handling a request is the same. In the example used here, you can obtain the parameters in request handler source file "buy_item.vely":

#include "vely.h"

request-handler /buy-item
    out-header default

    input-param sku
    input-param price

    run-query @mydb = "update wine_items set price='%s' where sku='%s'" : price, sku no-loop
    @OKAY
end-request-handler

For a hierarchical URL path, you would write:

#include "vely.h"

request-handler /items/wine-collection/red-wine
    ...
end-request-handler

Maximum length

Maximum length of a request URL is 2500 bytes.

Normalized URL

You can also write URLs where the entire request, including the request name, is in the query string. See normalized-URL.