NSAPI Programmer's Guide for iPlanet Web Server

Table of Contents | Previous | Next | Index | Bookshelf

NSAPI Programmer's Guide for iPlanet Web Server

Appendix G
HyperText Transfer Protocol

The HyperText Transfer Protocol (HTTP) is a protocol (a set of rules that describes how information is exchanged) that allows a client (such as a web browser) and a web server to communicate with each other.

HTTP is based on a request/response model. The browser opens a connection to the server and sends a request to the server.

The server processes the request and generates a response which it sends to the browser. The server then closes the connection.

This appendix provides a short introduction to a few HTTP basics. For more information on HTTP, see the IETF home page at:

http://www.ietf.org/home.html

This appendix has the following sections:

Compliance

Netscape Enterprise Server 3.x and iPlanet Web Server 4.x support HTTP 1.1. Previous versions of the server supported HTTP 1.0. The server is conditionally compliant with the HTTP 1.1 proposed standard, as approved by the Internet Engineering Steering Group (IESG) and the Internet Engineering Task Force (IETF) HTTP working group. For more information on the criteria for being conditionally compliant, see the Hypertext Transfer Protocol--HTTP/1.1 specification (RFC 2068) at:

http://www.ietf.org/html.charters/http-charter.html

Requests

A request from a browser to a server includes the following information:

Request Method, URI, and Protocol Version

Request Headers

Request Data

Request Method, URI, and Protocol Version

A browser can request information using a number of methods. The commonly used methods include the following:

GET--Requests the specified resource (such as a document or image)

HEAD--Requests only the header information for the document

POST--Requests that the server accept some data from the browser, such as form input for a CGI program

PUT--Replaces the contents of a server's document with data from the browser

Request Headers

The browser can send headers to the server. Most are optional. Some commonly used request headers are shown in Table 6.4.

Table 6.4 Common request headers

Request header Description
Accept
The file types the browser can accept.

Authorization
Used if the browser wants to authenticate itself with a server; information such as the username and password are included.

User-agent
The name and version of the browser software.

Referer
The URL of the document where the user clicked on the link.

Host
The Internet host and port number of the resource being requested.

Request header	Description
`Accept`	The file types the browser can accept.
`Authorization`	Used if the browser wants to authenticate itself with a server; information such as the username and password are included.
`User-agent`	The name and version of the browser software.
`Referer`	The URL of the document where the user clicked on the link.
`Host`	The Internet host and port number of the resource being requested.

Request Data

If the browser has made a POST or PUT request, it sends data after the blank line following the request headers. If the browser sends a GET or HEAD request, there is no data to send.

Responses

The server's response includes the following:

HTTP Protocol Version, Status Code, and Reason Phrase

The server sends back a status code, which is a three-digit numeric code. The five categories of status codes are:

100-199 a provisional response.
200-299 a successful transaction.
300-399 the requested resource should be retrieved from a different location.
400-499 an error was caused by the browser.
500-599 a serious error occurred in the server.

Table 6.5 Common HTTP status codes

Status code Meaning
200
OK; successful transaction.

302
Found. Redirection to a new URL. The original URL has moved. This is not an error; most browsers will get the new page.

304
Use a local copy. If a browser already has a page in its cache, and the page is requested again, some browsers (such as Netscape Navigator) relay to the web server the "last-modified" timestamp on the browser's cached copy. If the copy on the server is not newer than the browser's copy, the server returns a 304 code instead of returning the page, reducing unnecessary network traffic. This is not an error.

401
Unauthorized. The user requested a document but didn't provide a valid username or password.

403
Forbidden. Access to this URL is forbidden.

404
Not found. The document requested isn't on the server. This code can also be sent if the server has been told to protect the document by telling unauthorized people that it doesn't exist.

500
Server error. A server-related error occurred. The server administrator should check the server's error log to see what happened.

Status code	Meaning
`200`	OK; successful transaction.
`302`	Found. Redirection to a new URL. The original URL has moved. This is not an error; most browsers will get the new page.
`304`	Use a local copy. If a browser already has a page in its cache, and the page is requested again, some browsers (such as Netscape Navigator) relay to the web server the "last-modified" timestamp on the browser's cached copy. If the copy on the server is not newer than the browser's copy, the server returns a 304 code instead of returning the page, reducing unnecessary network traffic. This is not an error.
`401`	Unauthorized. The user requested a document but didn't provide a valid username or password.
`403`	Forbidden. Access to this URL is forbidden.
`404`	Not found. The document requested isn't on the server. This code can also be sent if the server has been told to protect the document by telling unauthorized people that it doesn't exist.
`500`	Server error. A server-related error occurred. The server administrator should check the server's error log to see what happened.

Response Headers

The response headers contain information about the server and the response data. Common response headers are shown in Table 6.6.

Table 6.6 Common response headers

Response header Description
Server
The name and version of the web server.

Date
The current date (in Greenwich Mean Time).

Last-modified
The date when the document was last modified.

Expires
The date when the document expires.

Content-length
The length of the data that follows (in bytes).

Content-type
The MIME type of the following data.

WWW-authenticate
Used during authentication and includes information that tells the browser software what is necessary for authentication (such as username and password).

Response header	Description
`Server`	The name and version of the web server.
`Date`	The current date (in Greenwich Mean Time).
`Last-modified`	The date when the document was last modified.
`Expires`	The date when the document expires.
`Content-length`	The length of the data that follows (in bytes).
`Content-type`	The MIME type of the following data.
`WWW-authenticate`	Used during authentication and includes information that tells the browser software what is necessary for authentication (such as username and password).

Response Data

The server sends a blank line after the last header. It then sends the response data such as an image or an HTML page.

Buffered Streams

New in iPlanet Web Server 4.1.

Buffered streams improve the efficiency of network I/O (for example the exchange of HTTP requests and responses) especially for dynamic content generation. Buffered streams are implemented in iPlanet Web Server 4.1 as transparent NSPR I/O layers, which means even existing NSAPI modules can use them without any change.

The buffered streams layer adds following features to the iPlanet Web Server:

Enhanced keep-alive support: When the response is smaller than the buffer size, the buffering layer generates the content-length header so that client can detect the end of the response and re-use the connection for subsequent requests.

Response length determination: If the buffering layer cannot determine the length of the response, it uses HTTP 1.1 chunked encoding instead of the content-length header to convey the delineation information. If the client only understands HTTP 1.0, the server must close the connection to indicate the end of the response.

Deferred header writing: Response headers are written out as late as possible to give the servlets a chance to generate their own headers (for example, the session management header set-cookie).

Ability to understand request entity bodies with chunked encoding: Though popular clients do not use chunked encoding for sending POST request data, this feature is mandatory for HTTP 1.1 compliance.

The improved connection handling and response length header generation provided by buffered streams also addresses the HTTP 1.1 protocol compliance issues where absense of the response length headers is regarded as a category 1 failure. In previous Enterprise Server versions it was the responsibility of the dynamic content generation programs to send the length headers. If a CGI script did not generate the content-length header, the server had to close the connection to indicate the end of the response, breaking the keep-alive mechanism. However, it is often very inconvenient to keep track of response length in CGI scripts or servlets, and as an application platform provider, the web server is expected to handle such low-level protocol issues.

Output buffering has been built in to the functions that get data, which are net_read and netbuf_grab (see Chapter 5, "NSAPI Function Reference"). To specify parameters that affect stream buffering, you can set the following variables, which are described in detail in Appendix B, "Variables in magnus.conf."

UseOutputStreamSize

flushTimer

ChunkedRequestBufferSize

ChunkedRequestTimeout

To override the default parameters when invoking a SAF that uses one of the functions net_read or netbuf_grab, you would specify the value of the parameter in obj.conf, for example:

Service fn="my-service-saf" type=perf UseOutputStreamSize=8192

Table of Contents | Previous | Next | Index | Bookshelf

Last Updated: 03/01/00 09:22:25

Appendix G HyperText Transfer Protocol

Appendix G
HyperText Transfer Protocol