Request URL

Application path

A request URL is a URL that calls your Vely code. The leading part of its path is called "application path" and is determined by the caller; it is usually specified in a web proxy configuration or in an environment for command-line programs.

By default, application path is assumed to be the application name (see how_vely_works), and would be:

/<app name>

So if your application name is "shopping", then the default application path is:

/shopping

You would then specify this application path in the client, for instance:

in Apache configuration file (see for example connect_apache_unix_socket):

ProxyPass "/shopping" unix:///var/lib/vv/shopping/sock/sock|fcgi://localhost/shopping

in Nginx configuration file (see for example connect_nginx_unix_socket):

location /shopping { include /etc/nginx/fastcgi_params; fastcgi_pass  unix:///var/lib/vv/shopping/sock/sock; }

in a command-line program as the SCRIPT_NAME environment variable (see command_line):
```
export SCRIPT_NAME="/shopping"
```

Request name

Request name is always the first path segment after the application path, for instance:

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

In this case 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 for all input parameters, see input-param.

A request name can be can be made up of alphanumeric characters, hyphen or underscore only and cannot start with a digit. Often it is in the same form as the names of Vely statement_APIs, which is that of "verb"-"object", for example "add-note", "show-orders" etc. This form clearly communicates the functional purpose of the request in the URL itself, as well as the names of source code files that handle them, which in this case would be "add_note.vely", "show_orders.vely" etc. Note however you can name a request any way you like.

URL payload

The actual URL payload, i.e. the input parameters, follow after the request name. For example, the full URL may be:

https://some.web.site/shopping/buy-item?name=ABC&price=600

Here, the required request name is "buy_item" and there are two other parameters ("name" and "price") with values of "ABC" and "600" respectively (see request).

The input parameters can also be specified as path segments in the form of "/name/value". This is often done when writing a REST API. So for example, the above URL can be:

https://some.web.site/shopping/buy-item/name/ABC?price=600

You can specify some or all parameters as path segments, so for example to specify all of them, the above URL can be written as:

https://some.web.site/api/v2/shopping/buy-item/name/ABC/price/600

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/api/v2/shopping/buy/name/ABC/price/600/edit

then this would be the same URL as before with the additional parameter "edit" of value "true".

If you specify input parameters as path segments, keep in mind that the path is meant to represent a logical hierarchy, where each path segment precedes in meaning the previous. In other words, input parameters representing a broader logical notion come first in the path, and those with a narrower one come afterwards. This order may represent the resource hierarchy (as it is often done with REST), but it does not have to.

Customizing application path

The application path can be customized to be any path you wish, but it must have the application name as the last segment:

/some/path/<app name>

This helps identify application at a glance. For example, if your application name is "shopping", the application path may be

/api/v2/shopping

and would be specified like this:

in Apache configuration file (see for example connect_apache_unix_socket):

ProxyPass "/api/v2/shopping" unix:///var/lib/vv/shopping/sock/sock|fcgi://localhost/shopping

in Nginx configuration file (see for example connect_nginx_unix_socket):

location /api/v2/shopping { include /etc/nginx/fastcgi_params; fastcgi_pass  unix:///var/lib/vv/shopping/sock/sock; }

in a command-line program as the SCRIPT_NAME environment variable (see command_line):
```
export SCRIPT_NAME="/api/v2/shopping"
```

For web requests, the URL sent by the caller might look something like this:

https://some.web.site/api/v2/shopping/buy-item?name=ABC&price=600

To tell Vely what the custom application path is, specify it in the "--path" parameter in vv when making your application, in this case:

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

Parameters

It is up to you how you 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"

void buy_item() {
    out-header default

    input-param name
    input-param price

    run-query @mydb = "insert into orders (name, price) values ('%s', '%s')" : name, price no-loop
    @OKAY
}

Normalized URL

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