restclient — n_pbt_restclient #

← Component reference · Guide contents

An HTTPS client for PowerBuilder, version 10 included: GET, POST, PUT, PATCH, DELETE, headers, a JSON body, a file download. Native — the system's TLS, proxy and decompression, and no CORS wall, because the request does not leave from a page.

▶ See it live — Demo application, REST client tile: the answers, the code that gets them and this page, side by side (Internet connection required).

At a glance #

Quick start #

// Local variables
n_pbt_restclient lnv_rest
n_pbt_json lnv_j
string ls_token, ls_customer
long ll_status

// One client for the API : its address and the token it sends (here read from the settings)
lnv_rest = create n_pbt_restclient
lnv_rest.is_base_url = "https://api.example.com"
ls_token = ProfileString("app.ini", "api", "token", "")
lnv_rest.of_set_bearer(/*token*/ ls_token)

// Read : the status comes back, the body waits in the object
ll_status = lnv_rest.of_get(/*url*/ "/orders/4152")
if ll_status = 200 then ls_customer = lnv_rest.of_json_value(/*path*/ "customer")

// Create : the body is built with n_pbt_json, never by hand
lnv_j.of_set_number(/*path*/ "order", /*value*/ 4152)
lnv_j.of_set_string(/*path*/ "status", /*value*/ "shipped")
ll_status = lnv_rest.of_post(/*url*/ "/shipments", /*body*/ lnv_j.of_text())
if ll_status < 0 then MessageBox("API", lnv_rest.of_get_last_error())

// The client is no longer needed
destroy lnv_rest

Every HTTP method returns the status the server chose — a 404 is an answer, not an error — or a negative code when the request did not go through: -5 invalid URL or header, client certificate not found, -4 failure (no network, unknown name, timeout, TLS, a text body over 64 MB — 16 MB in a 32-bit process; of_get_last_error() says which), -6 refused in demo mode. -2 says the client could not be created. An object made by create is enough for synchronous calls; for the events of the async calls, see "Where to write the events", below.

Why native, and not the page #

A fetch() launched from a page of the library is subject to CORS: every API that does not send Access-Control-Allow-Origin is closed to it, and enterprise APIs do not send it. So the request leaves from the DLL, through WinHTTP: the system's TLS and certificates, the configured proxy, gzip. What you lose: nothing; what you gain: every API.

Properties #

Constants: METHOD_GET, METHOD_POST, METHOD_PUT, METHOD_PATCH, METHOD_DELETE for of_request.

Methods #

Examples #

Reading a list and walking it #

// Local variables
string ls_body, ls_id
n_pbt_json lnv_list
long ll_i

// One value : of_json_value("items/1/id"). The whole list : load the body into an
// n_pbt_json and walk it by path.
if lnv_rest.of_get(/*url*/ "/orders?status=open") = 200 then
	ls_body = lnv_rest.of_response_text()
	lnv_list.of_load(/*json*/ ls_body)
	for ll_i = 1 to lnv_list.of_count(/*path*/ "items")
		ls_id = lnv_list.of_get_string(/*path*/ "items/" + String(ll_i) + "/id")
	next
end if

Downloading a document #

// Local variables
long ll_status

// Download the invoice to a file, then open it
ll_status = lnv_rest.of_download(/*url*/ "/orders/4152/invoice.pdf", /*path*/ "C:\temp\invoice-4152.pdf")
if ll_status = 200 then
	Run("C:\temp\invoice-4152.pdf")
elseif ll_status < 0 then
	MessageBox("Download", lnv_rest.of_get_last_error())
end if

An API that answers with an error #

// Local variables
n_pbt_json lnv_j

// The status decides : 200 or 201 = created, 400 = the request was refused (is_last_request
// tells what it asked for, its secrets masked), 401 = the token expired, below 0 = the network failed
lnv_j.of_set_number(/*path*/ "order", /*value*/ 4152)
choose case lnv_rest.of_post(/*url*/ "/shipments", /*body*/ lnv_j.of_text())
	case 200, 201
	case 400
		MessageBox("API", lnv_rest.of_json_value(/*path*/ "message") + "~r~n~r~n" + lnv_rest.is_last_request)
	case 401
		MessageBox("API", "Token expired : " + lnv_rest.of_json_value(/*path*/ "message"))
	case is < 0
		MessageBox("Network", lnv_rest.of_get_last_error())
end choose

An intranet API with Windows authentication #

// Local variables
n_pbt_restclient lnv_rest
long ll_status

// An IIS API of the intranet : the Windows session answers the server's challenge,
// nothing is typed. Off by default : switch it on for this client only.
lnv_rest = create n_pbt_restclient
lnv_rest.is_base_url = "https://erp.intranet.local/api"
lnv_rest.ib_windows_auth = true

// A header refused (a line break in the value) returns -5 and is not set
if lnv_rest.of_set_header(/*name*/ "X-Client", /*value*/ "PowerBuilder") < 0 then return

// Read an order : 401 when the server refused the Windows account
ll_status = lnv_rest.of_get(/*url*/ "/orders/4152")
if ll_status = 401 then
	MessageBox("ERP", "Access denied")
elseif ll_status < 0 then
	MessageBox("ERP", lnv_rest.of_get_last_error())
end if

// The client is no longer needed
destroy lnv_rest

A search typed by the user #

// Local variables
string ls_names[], ls_values[]
long ll_status

// What the user typed may hold # & + : of_url encodes every name and every value
ls_names[1] = "q"
ls_values[1] = sle_search.text
ls_names[2] = "page"
ls_values[2] = "2"
ll_status = lnv_rest.of_get(/*url*/ lnv_rest.of_url(/*path*/ "/items", /*names*/ ls_names, /*values*/ ls_values))

An API protected by OAuth2 #

// Local variables
n_pbt_restclient lnv_api

// One client for an API protected by OAuth2 (Azure AD, Keycloak, Salesforce...) : the token
// is asked once, then renewed by the client itself a minute before it expires
lnv_api = create n_pbt_restclient
lnv_api.is_base_url = "https://api.example.com"
if lnv_api.of_oauth_client_credentials(/*token_url*/ "https://login.example.com/oauth2/token", /*client*/ "my-app", /*secret*/ ProfileString("app.ini", "api", "secret", ""), /*scope*/ "orders.read") < 0 then
	MessageBox("API", lnv_api.of_get_last_error())
	return
end if

// Every request now carries the token
lnv_api.of_get(/*url*/ "/orders/4152")
destroy lnv_api

A list into a DataStore #

// Local variables
datastore lds_orders
long ll_rows

// The open orders of the API straight into a DataStore, as Retrieve does from a database :
// one row per object, each member in the column of its name, the rows not modified
lds_orders = create datastore
lds_orders.DataObject = "d_orders"
ll_rows = lnv_rest.of_retrieve(/*target*/ lds_orders, /*url*/ "/orders?status=open", /*path*/ "items")
if ll_rows < 0 then MessageBox("API", lnv_rest.of_get_last_error())

Asynchronous (without freezing the UI) #

During a synchronous call the UI is frozen until the answer: the window no longer repaints and no longer answers clicks. That does not matter for a short call; for any call that may take time — a slow server, a large body, an uncertain network —, use the asynchronous API: the request runs on a worker thread and its answer comes back later as an event. Synchronous and async calls share the same session: the cookie set by a synchronous login serves the async calls that follow, and the other way round; a synchronous call never waits behind the async requests of the same object.

Setup — nothing to wire: the component delivers the answer on its own in ue_response. of_open / of_close open and close the client (optional: the first request opens it), of_clear_cookies forgets the cookies kept between requests. Internally the component's pump calls of_process_events to drain the answers — you never call it.

Send — of_request_async(method, url, body), or the shortcuts of_get_async, of_post_async, of_put_async, of_patch_async, of_delete_async, return a request id at once — or -5 at once, with no event afterwards, for an invalid URL or header (of_get_last_error() says why, for instance "invalid URL: …"). Six requests at most run at the same time; the next ones wait their turn in a queue. of_download_async(url, path) downloads to a file and of_upload(url, field, path) uploads a file as multipart/form-data — both with progress. of_cancel(id) stops a request. Retries (il_max_retries, il_retry_backoff_ms) replay on 429/503/network failure.

Receive — ue_response(al_id, al_status) (read the body with of_response_text(al_id) / of_status(al_id) INSIDE the handler), ue_failed(al_id, al_code, as_error), ue_progress(al_id, al_done, al_total). An id is valid only for the object that sent the request. A runtime error in one of these events is not swallowed: it reaches the application's SystemError event like any script error, and the next answers are delivered all the same.

Where to write the events #

An object made by create n_pbt_restclient serves the synchronous calls very well — it is what the quick start does —, but its events have no script: PowerBuilder cannot write ue_response on an object created in a script. For the async calls, two ways:

• the object placed in the window (or the user object): in the painter, insert a nonvisual object n_pbt_restclient and name it inv_rest; its events ue_response, ue_failed and ue_progress are then scripted like a control's, and it is born and dies with the window — what the demo application does;
• a descendant: inherit from n_pbt_restclient (n_my_api), write ue_response in that descendant, and create it with create n_my_api.

Closing the window that holds the client from one of its events is allowed: the answers still waiting are not delivered.

// Local variables
long ll_id

// Async : the UI never freezes, and there is nothing to wire. inv_rest is the restclient
// placed in the window ; the request id comes back at once
ll_id = inv_rest.of_get_async(/*url*/ "https://api.example.com/orders/4152")

// Local variables
string ls_body

// Event ue_response of inv_rest : the answer arrives on its own, and it is read here
if al_status >= 200 and al_status < 300 then ls_body = this.of_response_text(/*id*/ al_id)

Good practice #

• One client per API, with its is_base_url and its headers set once: the call code carries only the path and the body.
• The body is built with n_pbt_json, never by concatenation: a quote in a customer name breaks nothing.
• Test the status, then the negative code: >= 200 and < 300 is fine, >= 400 the server said no, < 0 the request did not leave — of_get_last_error() says why.
• The timeout: 30 seconds by default; a heavy report deserves more, a health check less.
• What may take time goes async: a synchronous call freezes the UI until the answer.
• A redirection keeps your request: a 301 or a 302 rewrites only a POST into a GET — a PUT, a PATCH or a DELETE is sent again as it is, body included; a 303 goes on as a GET without a body. A relative Location (?page=2, ../) is resolved the way a browser would.
• A redirection to another origin takes nothing of yours: none of the headers set by of_set_header (token, API key) follows it — only Content-Type stays. An origin is a host, a port and a scheme: an http:// API redirected to https:// loses its token, so write https:// in is_base_url. The Windows credentials (ib_windows_auth) and the client certificate are only given to the host and port of the request. An HTTPS → HTTP redirection is refused.
• Test what of_set_header, of_set_bearer and of_set_basic return when the value comes from user input or a file: a line break, or a character beyond Latin-1 (a header travels in Latin-1; not for of_set_basic, whose pair leaves as base64), is refused there (-5) and nothing is set. A refused header never leaves half-made.
• Windows credentials leave only if you ask: ib_windows_auth = true for an intranet API with Windows authentication, never on a client that talks to the Internet.
• A text body is capped at 64 MB, 16 MB in a 32-bit application: a large export is read with of_download / of_download_async, which write a file with no limit.
• Encode what the user typed: the query of a URL goes as written — a # cuts it, a & adds a parameter, a + becomes a space. Build it with of_url, or encode one value with of_url_encode.
• Never credentials in the URL (https://user:pwd@…): the request is refused (-5); use of_set_basic.
• The User-Agent is PBToolboxAI/<version>; of_set_header("User-Agent", …) replaces it when an API demands yours.

← Component reference · Guide contents