Browsing an HTTP web server

Available URL names are defined by how your web services are named and designed. Each web service provides its own set of web content. This content is typically generated by custom functions and procedures in your database, but content can also be generated with a URL that specifies a SQL statement. Alternatively, or in conjunction, you can define the root web service, which processes all HTTP requests that are not processed by a dedicated service. The root web service would typically inspect the request URL and headers to determine how to process the request. For more information about the root web service, see Creating and customizing a root web service.

URLs uniquely specify resources such as html content available through HTTP or secured HTTPS requests. This section explains how to format the URL syntax in your web browser so that you can access the web services defined on your SQL Anywhere HTTP web server.

Note

The information in this section applies to HTTP web servers that use general HTTP web service types, such as RAW, XML, and HTML, and DISH services. You cannot use a browser to issue SOAP requests. JSON services return result sets for consumption by web service applications using AJAX.

Syntax

{http|https}://host-name[:port-number][/dbn]/service-name[/path-name|?url-query]

Parameters

host-name and port-number Specifies the location of the web server and, optionally, the port number if it is not defined as the default HTTP or HTTPS port numbers. The host-name can be the IP address of the computer running the web server. The port-number must match the port number used when you started the web server.
See -xs dbeng12/dbsrv12 server option and ServerPort (PORT) protocol option.
dbn Specifies the name of a database. This database must be running on the web server and contain web services.
You do not need to specify dbn if the web server is running only one database or if the database name was specified for the given HTTP/HTTPS listener of the protocol option.

See -xs dbeng12/dbsrv12 server option and DatabaseName (DBN) protocol option.
service-name Specifies the name of the web service to access. This web service must exist in the database specified by dbn. Slash characters ( / ) are permitted when you create or alter a web service, so you can use them as part of the service-name. SQL Anywhere matches the remainder of the URL with the defined services.
The client request is processed if a service-name is not specified and the root web service is defined. A 404 Not Found error is returned if the server cannot identify an applicable service to process the request. As a side-effect, if the root web service does exist and cannot process the request based on the URL criteria, then it is responsible for generating the404 Not Found error.

For more information about the root web service, see Creating and customizing a root web service.

path-name After resolving the service name, the remaining slash delimited path can be accessed by a web service procedure. If the service was created with URL ON, then the whole path is accessible using a designated URL http variable. If the service was created with URL ELEMENTS, then each path element can be accessed using designated http variables URL1 to URL10.

Path element variables can be defined as host variables within the parameter declaration of the service statement definition. Alternatively, or additionally, HTTP variables can be accessed from within a stored procedure using the HTTP_VARIABLE function call. For more information, see HTTP_VARIABLE function [HTTP].

The following example illustrates the SQL script used to create a web service where the URL clause is set to ELEMENTS:

CREATE SERVICE TestWebService
    TYPE 'HTML'
    URL ELEMENTS
    AUTHORIZATION OFF
    USER DBA 
    AS CALL TestProcedure ( :url1, :url2 );

This TestWebService web service calls a procedure that explicitly defines the url1 and url2 host variables.

You can access this web service using the following URL, assuming that TestWebService is running on the demo database from localhost through the default port:

http://localhost/demo/TestWebService/Assignment1/Assignment2/Assignment3

This URL accesses TestWebService, which runs TestProcedure and assigns the Assignment1 value to url1, and the Assignment2 value to url2. Optionally, TestProcedure can access other path elements using the HTTP_VARIABLE function. For example, a HTTP_VARIABLE('url3') function call returns Assignment3.

For more information about URL ELEMENTS and URL-based variables, see CREATE SERVICE statement.

url-query An HTTP GET request may follow a path with a query component that specifies HTTP variables. Similarly, the body of a POST request using a standard application/x-www-form-urlencoded Content-Type can pass HTTP variables within the request body. In either case, HTTP variables are passed as name/value pairs where the variable name is delimited from its value with an equals signs. Variables are delimited with an ampersand.

HTTP variables can be explicitly declared as host variables within the parameter list of the service-statement, or accessed using the HTTP_VARIABLE function from within the stored procedure of the service statement.

For example, the following SQL script creates a web service that requires two host variables. Host variables are identified with a colon ( : ) prefix.

CREATE SERVICE ShowSalesOrderDetail
    TYPE 'HTML'
    URL OFF
    AUTHORIZATION OFF
    USER DBA 
    AS CALL ShowSalesOrderDetail( :customer_id, :product_id );

Assuming that ShowSalesOrderDetail is running on the demo database from localhost through the default port, you can access the web service using the following URL:

http://localhost/demo/ShowSalesOrderDetail?customer_id=101&product_id=300

This URL accesses ShowSalesOrderDetail and assigns a value of 101 to customer_id, and a value of 300 to product_id. The resultant output is displayed in your web browser in HTML format.

Remarks

The web browser prompts for user name and password when required to connect to the server. The browser base64 then encodes the user input within an Authorization request header and resends the request.

If your web service URL clause is set to ON or ELEMENTS, the URL syntax properties of path-name and url-query can be used simultaneously so that the web service is accessible using one of several different formatting options. When using these syntax properties simultaneously, the path-name format must be used first followed by the url-query format.

In the following example, this SQL script creates a web service where the URL clause is set to ON, which defines the url variable:

CREATE SERVICE ShowSalesOrderDetail
    TYPE 'HTML'
    URL ON
    AUTHORIZATION OFF
    USER DBA 
    AS CALL ShowSalesOrderDetail( :product_id, :url );

The following is a sample list of acceptable URLs that assign a url value of 101 and a product_id value of 300:

http://localhost:80/demo/ShowSalesOrderDetail2/101?product_id=300
http://localhost:80/demo/ShowSalesOrderDetail2?url=101&product_id=300
http://localhost:80/demo/ShowSalesOrderDetail2?product_id=300&url=101

When a host variable name is assigned more than once in the context of path-name and url-query, the last assignment always takes precedence. For example, the following sample URLs assign a url value of 101 and a product_id value of 300:

http://localhost:80/demo/ShowSalesOrderDetail2/302?url=101&product_id=300
http://localhost:80/demo/ShowSalesOrderDetail2/String?product_id=300&url=101

Example

The following URL syntax is used to access a web service named gallery_image that is running in a database named demo on a local HTTP server through the default port, assuming that the gallery_image service is defined with URL ON:

http://localhost/demo/gallery_image/sunset.jpg

The URL appears to request a graphic file in a directory from a traditional web server, but it accesses the gallery_image service with sunset.jpg specified as an input parameter for an HTTP web server.

The following SQL script illustrates how the gallery service could be defined on the HTTP server to accomplish this behavior:

CREATE SERVICE gallery_image
    TYPE 'RAW'
    URL ON
    AUTHORIZATION OFF
    USER DBA 
    AS CALL gallery_image ( :url );

The gallery_image service calls a procedure with the same name, passing the client-supplied URL. For a sample implementation of a gallery_image procedure that can be accessed by this web service definitions, see samples-dir\SQLAnywhere\HTTP\gallery.sql.

Discuss this page in DocCommentXchange.