HTTP Client API

Request Management

web::request_create(requestId)

Creates a new HTTP request object. You can later modify the request by calling the request getter and setter functions.

Arguments:
  • requestId – output argument holding the internal request id generated by the underlying libaimmshttp.dll.
web::request_close(requestId)

Explicitly delete an HTTP request object. If you just make a single call to an HTTP server, you should call this function after web::request_invoke() to prevent memory leaks. At the end of the AIMMS session, all outstanding requests will be closed by web::library_termination().

Arguments:
  • requestId – id of the request to close. After the call the request object pointed to by requestId will be invalid.
web::request_invoke(requestId, responseCode)

Execute the HTTP request created by web::request_create() and prepared through calls to the request getter and setter functions. Depending on the call to web::request_setResponseBody(), the response body will either be discarded (default), or stored in the file passed to web::request_setResponseBody().

The function web::request_invoke() may be called multiple times for the same requestId. This may be particularly useful when the Connection header is set to keep-alive to prevent the additional costs of setting up a new connection.

Arguments:
  • requestId – id of the request object to invoke.
  • responseCode – output argument containing the HTTP response code of the request.

Request Getters and Setters

web::request_setURL(requestId, url)

Sets the URL to be used by the request object (created through web::request_create()) in the next call to web::request_invoke(). This URL may include a query string constructed using the utility function web::query_format().

Arguments:
  • requestId – id of the request object to set the URL for
  • url – the URL to set for the request object
web::request_getURL(requestId, url)

Get the current URL set for a request object created through web::request_create().

Arguments:
  • requestId – id of the request object
  • url – output string argument holding the current URL of the request object
web::request_setMethod(requestId, methodType)

Set the HTTP method to be used in the next call to web::request_invoke(). Valid values are:

  • GET
  • PUT
  • POST
  • DELETE
Arguments:
  • requestId – id of the request object to set the HTTP method for
  • methodType – input string argument holding the HTTP method to set
web::request_getMethod(requestId, methodType)

Get the current HTTP method set for a request object created through web::request_create().

Arguments:
  • requestId – id of the request object
  • url – output string argument holding the current HTTP method of the request object
web::request_setHeaders(requestId, headers)

Set the HTTP headers to be used in the next call to web::request_invoke().

If you do not specify HTTP headers yourself, the following default headers will be set

Connection: close
Accept-Encoding: identity, *;q=0

The latter header indicates the HTTP client does not currently support compression. If you do set HTTP headers you may need to add the Accept-Encoding header to indicate to the server that the HTTP Client library does not support compression.

You may retain the default HTTP headers, by calling web::request_getHeaders() prior to calling this function, and overwriting existing headers, or add new ones.

If you want to re-use the request for multiple calls to the same HTTP server, you may want to set the Connection header to keep-alive to re-use the connection between several calls.

Arguments:
  • requestId – id of the request object to set the HTTP method for
  • methodType – one-dimensional string parameter argument, holding the header arguments and values
web::request_getHeaders(requestId, headers)

Get the current HTTP headers set for a request object created through web::request_create().

Arguments:
  • requestId – id of the request object
  • headers – one-dimensional output string parameter holding the current HTTP headers set for the request object
web::request_setOptions(requestId, clientOptions)

Sets the HTTP Client library options to be used by the request object (created through web::request_create()) in the next call to web::request_invoke(). The library currently supports a single option requestTimeout, the timeout to be used for the request.

Arguments:
  • requestId – id of the request object to set the options for
  • clientOptions – one-dimensional string parameter argument, holding the option arguments and values
web::request_getOptions(requestId, clientOptions)

Get the current options set for a request object created through web::request_create().

Arguments:
  • requestId – id of the request object
  • clientOptions – one-dimensional output string parameter argument, holding the option arguments and values
web::request_setResponseBody(requestId, responseBodyType, responseBodyValue)

Indicate the method to be used to retrieve the response body in the next call to web::request_invoke(). Valid values are for the response body type are:

  • None: discard the response body
  • File: save the response body to the file specified through responseBodyValue
Arguments:
  • requestId – id of the request object to set the response body type for
  • responseBodyType – the response body type to use
  • responseBodyValue – the file name to store the response body for response body type File
web::request_getResponseBody(requestId, responseBodyType, responseBodyValue)

Get the current response body method set for a request object created through web::request_create().

Arguments:
  • requestId – id of the request object to get the response body type for
  • responseBodyType – the response body type set
  • responseBodyValue – the file name to store the response body for response body type File
web::request_setRequestBody(requestId, requestBodyType, requestBodyValue)

Indicate the method to be used to set the response body in the next call to web::request_invoke(). Valid values are for the request body type are:

  • None: do not set a request body
  • File: retrieve the request body from the file specified through requestBodyValue
Arguments:
  • requestId – id of the request object to set the response body type for
  • requestBodyType – the request body type to use
  • requestBodyValue – the file name to retrieve the request body from for response body type File
web::request_getRequestBody(requestId, requestBodyType, requestBodyValue)

Get the current request body method set for a request object created through web::request_create().

Arguments:
  • requestId – id of the request object to get the response body type for
  • requestBodyType – the request body type set
  • requestBodyValue – the file name to retrieve the request body from for response body type File

Utility functions

web::base64_encode(src, dest)

This function encodes the input string src into a base64-encoded output string dest

Arguments:
  • src – input string to base64-encode
  • dest – base64-encoded output string
web::base64_decode(src, dest)

This function decodes the base64-encoded input string src into the output string dest

Arguments:
  • src – base64-encoded input string
  • dest – decoded output string
web::query_format(oneDimStringParameter, formattedQuery)

This function converts a one-dimensional string parameter from your model into a URI-encoded query string that you may add to a URL that you pass to an HTTP request through the function web::request_setURL().

Arguments:
  • oneDimStringParameter – one-dimensional input string parameter holding the query arguments and values
  • formattedQuery – scalar output string argument holding the URI-encoded constructed query string

Library Management

web::library_termination()

This function is called during the termination sequence of the HTTP CLient Library. It will close all outstanding requests.