• Article

Reserving an HTTP Namespace

This feature will be removed in a future version of Microsoft SQL Server. Avoid using this feature in new development work, and plan to modify applications that currently use this feature.

Reserving an HTTP namespace for use with an instance of SQL Server can be performed by using either an implicit reservation, such as when you use CREATE ENDPOINT, or by an explicit reservation by using the sp_reserve_http_namespace stored procedure.

URL namespaces are reserved for the following reasons:

  • If an application is running as a nonadministrator account, it cannot bind to the namespace at run-time without having an administrator reserve the namespace. This is a requirement of the kernel-mode HTTP driver (Http.sys).

    The only exception to this rule is if the application is running under the local system account. Applications that are running under the local system account can bind to any namespace as long as it is free. Even when you are running under the local system account, we recommend reserving the namespaces for the following reason.

  • Reserving a namespace guarantees that other applications cannot bind to it; therefore, the application has sole ownership of the namespace.

    For example, if an instance of SQL Server is running under the local system account, reserving namespaces is not required, but we recommend it to avoid application conflicts over URLs.

Reserving namespaces is hierarchical. For example, if the namespace http://adventure-works.com:80/ is reserved, so are all the subnamespaces such as http://adventure-works.com:80/sqlapp1 and http://adventure-works.com:80/sqlapp2/dir1.

Note

To reserve an HTTP namespace by using the kernel-mode HTTP driver (Http.sys) requires Windows administrative privileges on the local computer on which the instance of SQL Server is installed.

Creating an Explicit Reservation

To create an explicit reservation, an administrator who wants users to be able to run an endpoint Data Definition Language (DDL) statement without requiring high privileges on the computer can reserve a URL namespace by using the sp_reserve_http_namespace stored procedure.

For example, you can connect to an instance of SQL Server by using Windows Authentication, a login that has administrator privileges, and execute the following:

sp_reserve_http_namespace N'http://MyServer:80/sql'
GO

The stored procedure explicitly reserves the specified namespace, where MyServer is the server name and 80 is the port number. This procedure reserves the specified URL namespace in a way that subsequent DDL operations within that namespace do not require administrator privileges on the computer. A user without any computer administrator privileges can execute the endpoint DDL statement.

For example, a user may execute the following CREATE ENDPOINT statement:

CREATE ENDPOINT sql_endpoint 
STATE = STARTED
AS HTTP(
   PATH = '/sql/AdvWorks', 
   AUTHENTICATION = (INTEGRATED ), 
   PORTS = ( CLEAR ), 
   SITE = 'MyServer'
)
FOR SOAP (
    ...
)
GO

The endpoint statement just registers the /sql/AdvWorks in the reserved namespace in HTTP.SYS. A client application can then send a SOAP request, such as by requesting a WSDL response from the server, to the endpoint:

http://MyServer/sql/AdvWorks?wsdl

The namespace name specified in the sp_reserve_http_namespace stored procedure must be of the form:

<scheme>://<hostpart>[:<port>]/<RelativeURI>

  • scheme
    Can be http or https.

  • hostpart
    Can be a specific host name or the following wildcard characters: the plus sign (+) or asterisk (*).

    The plus sign (+) implies that the reservation operation applies to all possible host names for the computer for the specified <scheme> and <port>.

    The asterisk (*) implies that the reservation operation applies to all possible host names for the computer for the <scheme> and <port> that are not otherwise explicitly reserved, such as by running other sp_reserve_http_namespace operations, active endpoints, or other applications.

Identifying the Namespace for an Endpoint

You can identify the correct namespace for an endpoint based on the parameters in the CREATE ENDPOINT statement.

The value of the PORTS parameter to the CREATE ENDPOINT statement determines the scheme for the namespace, as shown in the following table:

Endpoint value

<scheme> value

CLEAR

http

SSL

https

n

http

The value of the CLEAR_PORT or SSL_PORT parameter sets the <port> value of the namespace

The value of the PATH parameter sets the <RelativeURI> of the namespace.

The value of the SITE parameter sets the <hostpart> of the namespace.

For example, the following statement creates an endpoint that has the namespace http://testhost:80/sqlurl/myapp.

CREATE ENDPOINT ext_endpoint
    STATE = STARTED
AS HTTP (       
PATH = '/sqlurl/myapp'
, PORTS = CLEAR
, SITE = testhost
, CLEAR_PORT = 80 
)

The following statement creates an endpoint that has the namespace https://*:443/sqlurl/myapp:

CREATE ENDPOINT ext_endpoint
    STATE = STARTED
AS HTTP (       
PATH = '/sqlurl/myapp'
, PORTS = SSL
, SITE = '*'
, SSL_PORT = 443 
)

Examples

The following is another example in which the administrator reserves a namespace in HTTP.SYS for SSL connection. Therefore, a user can create endpoints where PORT is set to SSL.

sp_reserve_http_namespace N'https://MyServer:443/sql'