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:
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.
See also
Requests
after-request-handler  
before-request-handler  
building-URL  
getting-URL  
global-request-data  
non-request  
normalized-URL  
request  
request-handler  
request-URL  
startup-handler  
vely-dispatch-request    
See all
documentation


You are free to copy, redistribute and adapt this web page (even commercially), as long as you give credit and provide a dofollow link back to this page - see full license at CC-BY-4.0. Copyright (c) 2019-2023 Dasoftver LLC. Vely and elephant logo are trademarks of Dasoftver LLC. The software and information on this web site are provided "AS IS" and without any warranties or guarantees of any kind. Icons from table-icons.io copyright PaweĊ‚ Kuna, licensed under MIT license.