restclient — n_pbt_restclient #

← Referencia de componentes · Índice de la guía

Un cliente HTTPS para PowerBuilder, versión 10 incluida: GET, POST, PUT, PATCH, DELETE, cabeceras, un cuerpo JSON, la descarga de un archivo. Nativo — el TLS, el proxy y la descompresión del sistema, y ningún muro CORS, porque la petición no sale de una página.

▶ Verlo en vivo — Aplicación de demostración, mosaico REST client: las respuestas, el código que las obtiene y esta página, lado a lado (se requiere conexión a Internet).

En resumen #

Inicio rápido #

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

Cada método HTTP devuelve el estado que eligió el servidor — un 404 es una respuesta, no un error — o un código negativo cuando la petición no llegó: -5 URL no válida, -4 fallo (sin red, nombre desconocido, tiempo agotado, TLS; is_last_error dice cuál), -6 rechazado en modo demo.

Por qué nativo, y no la página #

Un fetch() lanzado desde una página de la biblioteca está sujeto a CORS: toda API que no envíe Access-Control-Allow-Origin le queda cerrada, y las API de empresa no lo envían. La petición sale por tanto de la DLL, por WinHTTP: el TLS del sistema con sus certificados, el proxy configurado, gzip. Lo que pierde: nada; lo que gana: todas las API.

Propiedades #

Constantes: METHOD_GET, METHOD_POST, METHOD_PUT, METHOD_PATCH, METHOD_DELETE para of_request.

Métodos #

Ejemplos #

Leer una lista y recorrerla #

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

Descargar un documento #

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

Una API que responde con 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

Asíncrono (sin congelar la interfaz) #

Las llamadas síncronas anteriores bloquean el script (la interfaz sigue viva pero la línea espera). La API asíncrona ni siquiera bloquea el script: la petición corre en un hilo de trabajo y su respuesta vuelve más tarde como evento.

Preparación — nada que cablear: el componente entrega la respuesta por sí solo en ue_response. of_open / of_close abren y cierran el cliente (opcional: la primera llamada asíncrona lo abre), of_clear_cookies olvida las cookies guardadas entre peticiones. Internamente el pump del componente llama a of_process_events para repartir las respuestas — usted nunca lo llama.

Enviar — of_request_async(method, url, body), o los atajos of_get_async, of_post_async, of_put_async, of_patch_async, of_delete_async, devuelven de inmediato un id de petición. of_download_async(url, path) descarga a un archivo y of_upload(url, field, path) sube un archivo como multipart/form-data — ambos con progreso. of_cancel(id) detiene una petición en vuelo. Los reintentos (il_max_retries, il_retry_backoff_ms) reintentan en 429/503/fallo de red.

Recibir — ue_response(al_id, al_status) (leer el cuerpo con of_response_text(al_id) / of_status(al_id) DENTRO del manejador), 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

Buenas prácticas #

• Un cliente por API, con su is_base_url y sus cabeceras puestas una vez: el código de las llamadas solo lleva la ruta y el cuerpo.
• El cuerpo se construye con n_pbt_json, nunca por concatenación: una comilla en el nombre de un cliente no rompe nada.
• Compruebe el estado, luego el código negativo: >= 200 y < 300 está bien, >= 400 el servidor dijo no, < 0 la petición no salió — is_last_error dice por qué.
• El tiempo de espera: 30 segundos por defecto; un informe pesado merece más, una comprobación de presencia menos.

← Referencia de componentes · Índice de la guía