Module httpclient

This module implements a simple HTTP client that can be used to retrieve webpages/other data.

Retrieving a website

This example uses HTTP GET to retrieve http://google.com

echo(getContent("http://google.com"))

Using HTTP POST

This example demonstrates the usage of the W3 HTML Validator, it uses multipart/form-data as the Content-Type to send the HTML to the server.

var headers: string = "Content-Type: multipart/form-data; boundary=xyz\c\L"
var body: string = "--xyz\c\L"
# soap 1.2 output
body.add("Content-Disposition: form-data; name=\"output\"\c\L")
body.add("\c\Lsoap12\c\L")

# html
body.add("--xyz\c\L")
body.add("Content-Disposition: form-data; name=\"uploaded_file\";" &
         " filename=\"test.html\"\c\L")
body.add("Content-Type: text/html\c\L")
body.add("\c\L<html><head></head><body><p>test</p></body></html>\c\L")
body.add("--xyz--")

echo(postContent("http://validator.w3.org/check", headers, body))

SSL/TLS support

This requires the OpenSSL library, fortunately it's widely used and installed on many operating systems. httpclient will use SSL automatically if you give any of the functions a url with the https schema, for example: https://github.com/, you also have to compile with ssl defined like so: nimrod c -d:ssl ....

Types

TResponse* = tuple[version: string, status: string, headers: PStringTable, 
                   body: string]
EInvalidProtocol* = object of ESynch
exception that is raised when server does not conform to the implemented protocol
EHttpRequestErr* = object of ESynch
Thrown in the getContent proc and postContent proc, when the server returns an error
THttpMethod* = enum 
  httpHEAD, ## Asks for the response identical to the one that would
            ## correspond to a GET request, but without the response
            ## body.
  httpGET,                    ## Retrieves the specified resource.
  httpPOST, ## Submits data to be processed to the identified 
            ## resource. The data is included in the body of the 
            ## request.
  httpPUT,                    ## Uploads a representation of the specified resource.
  httpDELETE,                 ## Deletes the specified resource.
  httpTRACE, ## Echoes back the received request, so that a client 
             ## can see what intermediate servers are adding or
             ## changing in the request.
  httpOPTIONS, ## Returns the HTTP methods that the server supports 
               ## for specified address.
  httpCONNECT ## Converts the request connection to a transparent 
              ## TCP/IP tunnel, usually used for proxies.
the requested HttpMethod

Procs

proc request*(url: string; httpMethod = httpGET; extraHeaders = ""; body = ""): TResponse

Requests url with the specified httpMethod.
Extra headers can be specified and must be seperated by \c\L

proc get*(url: string; maxRedirects = 5): TResponse

GET's the url and returns a TResponse object
This proc also handles redirection

proc getContent*(url: string): string

GET's the body and returns it as a string.
Raises exceptions for the status codes 4xx and 5xx

proc post*(url: string; extraHeaders = ""; body = ""; maxRedirects = 5): TResponse

POST's body to the url and returns a TResponse object.
This proc adds the necessary Content-Length header.
This proc also handles redirection.

proc postContent*(url: string; extraHeaders = ""; body = ""): string

POST's body to url and returns the response's body as a string
Raises exceptions for the status codes 4xx and 5xx

proc downloadFile*(url: string; outputFilename: string)
Downloads url and saves it to outputFilename
Generated: 2012-09-23 21:47:54 UTC