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 #

n_pbt_restclient lnv_rest
n_pbt_json lnv_j
long ll_status

lnv_rest = create n_pbt_restclient
lnv_rest.is_base_url = "https://api.example.com"
lnv_rest.of_set_bearer(ls_token)

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

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

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, -4 failure (no network, unknown name, timeout, TLS; is_last_error says which), -6 refused in demo mode.

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 #

string ls_body
if lnv_rest.of_get("/orders?status=open") = 200 then
	ls_body = lnv_rest.of_response_text()
	// One value : of_json_value. The whole list : n_pbt_utils.of_json_get_payload and
	// of_json_get_str on each object, or your own parser on ls_body.
end if

Downloading a document #

long ll_status
ll_status = lnv_rest.of_download("/orders/4152/invoice.pdf", "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.is_last_error)
end if

An API that answers with an error #

choose case lnv_rest.of_post("/shipments", ls_body)
	case 200, 201
		// created
	case 401
		MessageBox("API", "Token expired : " + lnv_rest.of_json_value("message"))
	case is < 0
		MessageBox("Network", lnv_rest.is_last_error)
end choose

Asynchronous (no UI freeze) #

The synchronous calls above block the script (the UI stays alive but the line waits). The asynchronous API does not even block the script: the request runs on a worker thread and its answer comes back later as an event.

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 async call 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. 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 an in-flight 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, as_error), ue_progress(al_id, al_done, al_total).

// Async : the UI never freezes, and there is nothing to wire.
ll_id = uo_rest.of_get_async("https://api.example.com/orders/4152")

// The answer arrives on its own in the ue_response event of uo_rest :
IF al_status >= 200 AND al_status < 300 THEN
	ls_body = uo_rest.of_response_text(al_id)
END IF

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 — is_last_error says why.
• The timeout: 30 seconds by default; a heavy report deserves more, a health check less.

← Component reference · Guide contents