Index...
Centrallix Documentation
|
11.5 HTTP Client
The HTTP Client object permits integration with remote HTTP/HTTPS web servers and web service APIs.
HTTP Client Connector Format
An HTTP client connector is set up by creating an .http file in "structure file" format. Below is an example which simply retrieves the contents of the LightSys.org home page.
$Version=2$
my_http "application/http"
{
server = "www.lightsys.org";
path = "/";
protocol = "https";
method = "GET";
allowsubdirs = 0;
cache_min_ttl = 3600000; // one hour
cache_max_ttl = 86400000; // one day
}
The properties above are described below:
| Property | Description |
|---|
| server | The IP address or host name of the HTTP server |
| path | The path on the server; this is what typically goes in a URL after the server's name and port. |
| protocol | Either "http" or "https". |
| method | Currently supported methods: GET, POST, DELETE. |
| cache_min_ttl | The minimum milliseconds to cache a response from the web server. |
| cache_max_ttl | The maximum milliseconds to cache a response from the web server. |
| cache_max_length | The maximum length response to cache, in bytes. Defaults to 1048576 bytes (1 MiB). |
| success_codes | A list of HTTP codes (other than 2XX codes) to treat as successful results. |
| request_content_type | The content type to use in a POST request body. This can be "application/x-www-form-urlencloded", "application/xml", or "application/json". |
| restrict_content_type | Limit the allowed content types from the remote server to this type or its more specific descendents. This does not set the Accept HTTP header. |
| expected_content_charset | The character set expected for the server's response body. |
| override_content_charset | Whether to override the character set in the server's response Content-Type with the expected charset (above). Useful if the server is providing an incorrect charset in its Content-Type response. Boolean. |
| retry_limit | The maximum number of retries to attempt after an error. Defaults to 0 (no retries). |
| retry_delay | The delay between the initial try and the first retry, in seconds. Decimal values accepted. Defaults to 1.0 seconds. |
| retry_backoff_ratio | The amount to multiply the retry delay by on subsequent (2nd, 3rd, etc.) retries. Decimal values accepted. Defaults to 2.0, so the delay doubles with each retry. |
| retry_for | What error conditions trigger a retry vs. a failure. A list of one or more of: tcp_reset (TCP connection reset by peer), rude_close (peer closed the connection at a time other than after the response is sent), http_4xx (the server indicated the request was faulty), http_401 (unauthorized), http_5xx (the server failed to handle the request), and/or tls_error (TLS handshake failed for any reason). Note that enabling retry_for http_4xx and allowsubdirs results in HTTP 404 errors being excluded from the retry function, since they instead trigger the parent/subobject search. Default: retry for none. |
| redirect_limit | The limit on the number of redirects allowed, if allowredirects is enabled. Default 4. |
| allow_insecure_redirects | Whether to allow redirection from an HTTPS URL to an HTTP URL. Default 0 (false). Boolean. |
| force_secure_redirects | If redirected from an HTTPS URL to an HTTP URL, force the use of HTTPS on the redirection. Default 0 (false). Boolean. |
| allowredirects | Whether to allow redirection at all. Deprecated - use redirect_limit instead. Default 1 (true). Boolean. |
| allowcookies | Whether to process and send cookies. Default 0 (false). Boolean. |
| allowsubdirs | Set to 0 (or false) if the path specified here is fixed. If the path could contain additional elements that need to be passed to the server, specified by a SQL query for example, set this to 1 (or true). Use with care since this can "leak" objectsystem path information inappropriately to a remote server. Default 0 (false). Boolean. |
| allowbadcert | Set to 1 (true) to disable verification of the server's certificate. Default 0 (false). Boolean. |
| ssl_cipherlist | Use this to manually configure the list of allowed SSL ciphers. Defaults to the Centrallix global ssl_cipherlist setting, or 'DEFAULT' if none is set. |
| send_auth_initial | Whether to send an Authorization header (if configured) on the first request (true/1) or wait until a 401 is received before sending the Authorization header (false/0). Sending the Authorization header immediately can reduce latency due to fewer connections, but some servers (including Centrallix in http-strict mode) may require that a 401 be sent with an auth cookie before authentication is allowed. Defaults to 1 (true). |
| username | Username for HTTP Basic authentication. |
| password | Password for HTTP Basic authentication. |
| authline | Authorization header to use. If more flexibility is needed in constructing the authorization header, a Parameter may be used instead; see below. |
| proxyauthline | Proxy-Authorization header to use. |
All of these properties can contain expressions that reference parameters and other data.
HTTP Client - Returned Data
HTTP clients connect to a remote web server and issue a HTTP command to obtain a document. That document could be in any number of formats, but for web services, it is usually in JSON or XML format.
The HTTP client does not parse the JSON or XML data itself; instead another Centrallix driver reads that data from the HTTP client and parses it into objects. This normally happens automatically, so long as the web server returned an XML or JSON MIME type in its response.
Those objects derived from the JSON or XML data can then be individually queried using the Centrallix SQL language. Here's an example:
SELECT
:first_name,
:last_name
FROM
/api_objects/myclient.http?person_id=12345
If the API being quieried by the .http object is paginated and multiple requests need to be placed, remember that the .http object itself does not do any parsing of the returned content. So, iteration over the API pages must be done at the SQL query level. See the FROM Clause modifiers PAGED and NONEMPTY for more information on two different ways to do this. Here's an example:
SELECT
:first_name,
:last_name
FROM
PAGED EXPRESSION ('/api_objects/myclient.http?page=' + :p:cx__page ) p
HTTP Client - Parameters
In order to effectively integrate with most web services, some data of some form needs to be sent to the web service. This is done via HTTP client parameters.
Parameters are placed inside the "application/http" top level object, and have the following form:
paramname "http/parameter"
{
type=string;
source=param;
usage=post;
default=runserver("Default value");
}
The "paramname" above is the name of the parameter. "http/parameter" is the object type and can't be changed.
The properties of a parameter are described below:
| Property | Description |
|---|
| type | The data type of the parameter, either string or integer. |
| source | How the parameter value is supplied to the http object. Can be "param" for a URL-style parameter, or "path" to use a specified pathname element provided in the SQL query for example, or "none" to only use the default value. |
| usage | How to use the parameter and its value in connecting to the remote server. "header" means to send the parameter as an HTTP header. "url" means to send the parameter as a URL parameter. "post" means to send the parameter in the POST body. |
| default | Provides a default value for the parameter. Can contain an expression, in which case the runserver() domain declaration should be used. The default can reference other parameters, as well. |
| pathpart | For "path" sourced parameter values, this specifies which pathname element after the .http object to use as the parameter value. |
Parameter value source types:
| Source | Description |
|---|
| param | Look in the pathname's open parameters for the parameter's value. For example, if the http object is opened as /myclient.http?p=1234 then the value 1234 would be used for the parameter p. |
| path | Look in a path element for the parameter's value. This also requireds that the setting 'pathpart' be specified. For example, if parameter x is set to source=path and pathpart=1, then opening the http object as /myclient.http/1234 would use the value 1234 for parameter x. |
| none | The parameter's value will not be derived from any source. Instead, only the default value (as described above) will be used. |
Parameter usage types:
| Usage | Description |
|---|
| header | Send the parameter and its value as an HTTP header. For example, if the parameter's name is Authorization and the value is "Bearer abcdefg", then the HTTP header "Authorization: Bearer abcdefg" will be sent with the request. |
| url | The parameter will be sent as a URL parameter with the request. For example, if the parameter's name is x and the value is 1234, then the HTTP request sent to the server might be "GET /pathname/goeshere.php?x=1234". |
| post | The parameter and its value will be sent to the server in a POST request body. The request body format can be URL encoded, XML, or JSON (see request_content_type, above). See below for details on the POST request body. |
| none | Do not use the parameter anywhere. However, the parameter can still be referenced by other expressions, such as other parameter default values and expressions for HTTP client settings like "path". |
HTTP Client - POST Request Body Format
POST requests use a request body whose type is specified by request_content_type, see above. The three supported types are "application/x-www-form-urlencloded", "application/xml", and "application/json".
If a POST request is sent in Form URL Encoded format, the parameters are encoded in a flat fashion without any structure. If you have two parameters, "a.b" and "a.c", they will be sent exactly with those names.
When a POST request is sent with an XML or JSON request content type, the POST parameters are encoded in a hierarchical fashion. To send multiple levels of JSON or XML, use periods in the parameter name, for example parameter name "person.name.first" and "person.name.last" would send XML something like
<person><name><first>John</first><last>Smith</last></name></person>
or JSON like
{ "person": { "name": { "first":"John", "last":"Smith" } } }
Note that to use parameter names with periods in them, you have to enclose the parameter names in quotation marks, for example:
"person.name.first" "http/parameter" { type=string; usage=post; source=none; default="John"; }
If you need to send a JSON array (instead of a JSON object), use numbers for the object name. For example, to send a JSON-RPC v1 request body, use these types of parameters:
method "http/parameter" { type=string; usage=post; source=none; default="method_name_here"; }
"params.0" "http/parameter" { type=string; usage=post; source=none; default="value 0"; }
"params.1" "http/parameter" { type=string; usage=post; source=none; default="value 1"; }
id "http/parameter" { type=integer; usage=post; source=none; default=1; }
This would send:
{ "method":"method_name_here", "params":["value 0", "value 1"], "id":1 }
Comments...
(none yet)
Add a Comment...
|
