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)

Closes an HTTP request object. When a request is closed it is no longer available and after it is completely handled it is deleted. 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.

web::request_invoke_async(requestId, CallBack)

Execute the HTTP request created by web::request_create() and prepared through calls to the request getter and setter functions. Unlike web::request_invoke() this function will return directly to AIMMS after the request has been send.

To handle the response the user must define a “CallBack” procedure in AIMMS. This is a procedure in AIMMS with arguments StringParameter requestId and Parameter responseCode. This procedure is called when the response arrives.

Between the invocation and the callback, the request cannot be changed. In the callback all the getters and setters of the request are available. It is also possible to close the request in the callback.

Arguments

  • requestId – id of the request object to invoke.

  • CallBack – the name of a user defined callback procedure with arguments requestId and responseCode.

web::wait_for_response(timeout)

To make sure that AIMMS is not too busy to handle incoming callbacks, this function can be used to reserve time. It return immediately with value 1 if it one or more callbacks are handled. It returns 0 if it times out after timeout time.

Arguments

  • timeout – time in seconds to wait.

web::wait_for_the_response(requestId)

Waits until the callback of request requestId has been handled and then returns to AIMMS. If a response of an other request arrives, it will be handled and then keeps waiting.

Arguments

  • requestId – id of the request object to invoke.

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

  • methodType – input string argument holding the HTTP method to set

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

  • headers – one-dimensional output string parameter holding the current HTTP headers set for the request object

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

web::request_getResponseHeaders(requestId, headers)

Get the current HTTP headers of the HTTP response after a call to the function web::request_invoke().

Arguments

  • requestId – id of the request object

  • headers – one-dimensional output string parameter holding the current HTTP response headers set for the request object

Utility functions

web::request_generate_curl(requestId, curlCmdFile)

This function will generate a file containing a curl command for the specified request object. This is useful for debugging and triaging network/connection related issues

Arguments

  • requestId – id of the request object generate the curl command for

  • curlCmdFile – the file to write the curl command to

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.

web::setConfig(clientConfigs)

Sets the HTTP Client library configuration to be used. The library currently supports one configuration ReqPoolSize, which can be use to set the request pool size .

Arguments

  • clientConfigs – one-dimensional string parameter argument, holding the config arguments and values