18.4.0 released Sep 25, 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
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:
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:
Use "--path" parameter in vv to set the application path:
vv -q --path="/api/v2/shopping"
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
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 of a request URL is 2500 bytes.
You can also write URLs where the entire request, including the request name, is in the query string. See normalized-URL.
Requests
after-request-handler
before-request-handler
building-URL
end-request-handler
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 link back to this page (dofollow) - 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.