Fwrest Client Generator

FWRest Client Generator

Overview

Generate production-ready AdvPL/TLPP code that consumes external REST APIs using the framework FWRest class. FWRest is the HTTP client class — it is the counterpart to the @Get/@Post annotation-based REST server (see tlpp-rest-endpoint-generator for exposing endpoints, not consuming them).

FWRest wraps low-level HTTP socket calls and supports the four standard verbs GET, POST, PUT, DELETE (no native PATCH support). It handles SSL automatically through appserver.ini socket configuration.

When to Use

Use this skill when generating code that:

• Calls a third-party REST API from inside Protheus (integrations with CRMs, payment gateways, ERPs, government services, etc.)
• Sends JSON payloads to external services
• Pulls data from external endpoints into a Protheus routine
• Needs HTTP Basic, Bearer/JWT, or OAuth 2.0 authentication
• Replaces legacy HTTPCGet / HTTPCPost / HTTPQuote calls with the framework client

Do NOT use this skill for:

• Exposing endpoints from Protheus → use ../tlpp-rest-endpoint-generator/SKILL.md
• Workstation-side HTTP calls that must run on the user's machine → use HTTPCGet/HTTPCPost with WebAgent
• File downloads from non-REST endpoints → use HTTPQuote or WSDownload

FWRest Architecture

Lifecycle

A typical FWRest call follows this five-step lifecycle:

1. Instantiate — oClient := FWRest():New(cHost) where cHost is the base URL only (scheme + host + optional port), e.g. "https://api.example.com".
2. Configure — SetPath(), SetPostParams(), SetGetParams(), SetTimeOut(), SetChkStatus(), SetLegacySuccess().
3. Build headers — Plain Array of "Key: Value" strings, e.g. {"Content-Type: application/json", "Authorization: Bearer xyz"}.
4. Invoke verb — :Get(aHead), :Post(aHead), :Put(aHead, cBody), :Delete(aHead, cBody). All return .T. on success.
5. Read result — GetResult() on success (response body as character), GetLastError() on failure, GetHTTPCode() for the numeric status.

Path vs Query Parameters

Special characters in query values must be URI-encoded via the Escape() function — otherwise the request will fail or be misinterpreted.

Status Code Semantics

No PATCH Support

FWRest does not support the PATCH verb. If the target API requires PATCH, generate code using HTTPQuote() instead and note this limitation explicitly.

Bundled Reference Files

This skill uses progressive disclosure. The SKILL.md body covers the architecture, decision logic, and the generation checklist. Detailed method reference, code templates, and authentication patterns are in the references/ directory — read them on demand based on the scenario:

Also refer to references/sonarqube-rules-reference.md for the complete SonarQube rules reference shared across skills.

Generation Workflow

Step 1: Gather Requirements

Identify from the user's request:

• Target API — base URL, path, and HTTP verb(s)
• Authentication scheme — None, Basic, Bearer/JWT, API Key, or OAuth 2.0
• Payload format — JSON (default), XML, form-encoded, binary/gzip
• Expected response codes — only 2xx, or also 204/3xx/4xx as part of contract
• Timeout requirement — default 120s vs custom (e.g. webhook endpoints with 5s SLA)
• Whether the call is part of a transaction — affects error handling strategy

Step 2: Load Templates

Read references/fwrest-client-templates.md for the verb-specific template. Combine with the auth header pattern from references/fwrest-authentication-patterns.md.

Step 3: Pick the Status-Code Strategy

• Standard CRUD (200/201 only matter): leave defaults.
• API uses full 2xx range (e.g. 202 Accepted, 204 No Content): call oClient:SetLegacySuccess(.F.) (requires LIB 20240812+).
• Need to read body of 4xx/5xx responses: call oClient:SetChkStatus(.F.) and inspect GetHTTPCode() + GetResult() manually.

Step 4: Wrap in Try/Catch + Logging

Wrap every FWRest invocation in a TLPP Try/Catch block. Log failures via FWLogMsg() including the URL, HTTP code, and the truncated response body. Never log secrets (tokens, passwords).

Step 5: Validate Against Checklist

Use the checklist below to verify the generated code covers all requirements.

FWRest Client Generation Checklist

Structure

• #include "totvs.ch" (AdvPL) or #include "tlpp-core.th" (TLPP) present, in lowercase
• User Function declares oClient, aHeader, cBody, cResponse, nHttpCode as locals with explicit types (TLPP as Object, as Array, etc.)
• FWRest():New(cHost) receives ONLY the base URL — path is set via SetPath()

Request Construction

• SetPath() called with leading /
• Query parameter values passed through Escape() when they may contain spaces or special chars
• Headers built as an Array of "Key: Value" strings (note the literal space after the colon)
• Content-Type header included for POST/PUT bodies (application/json, application/xml, etc.)
• Body serialized via oJson:toJson() — never built by string concatenation when the data is dynamic
• SetPostParams(cBody) called before :Post() (Post body is NOT a parameter of :Post())
• PUT/DELETE bodies passed as the second positional argument of :Put(aHead, cBody) / :Delete(aHead, cBody)

Authentication

• Secrets read from GetMV() parameter or environment, never hardcoded
• HTTP Basic: "Authorization: Basic " + Encode64(cUser + ":" + cPass)
• Bearer/JWT: "Authorization: Bearer " + cToken
• OAuth 2.0 token-acquisition call is a separate FWRest call to the auth server, cached for the token's expires_in window
• Token never logged or echoed in error responses

Response Handling

• Verb result captured in a local lOk (e.g. lOk := oClient:Post(aHeader))
• GetHTTPCode() retrieved into a local before any branching
• GetResult() parsed via JsonObject():New() + :fromJson() and the fromJson() return checked (returns Nil on success, error string otherwise)
• Failure branch reads GetLastError() AND GetHTTPCode() (both can be informative)

Robustness

• SetTimeOut() set explicitly (default 120s is often too long for synchronous calls)
• Calls wrapped in Try/Catch to capture transport-layer exceptions
• SetChkStatus(.F.) used when the API returns 204/4xx as part of contract
• SetLegacySuccess(.F.) used when the API uses the full 2xx range
• FreeObj(oClient) after use in long-running routines to release the socket promptly

Logging & Observability

• Successful calls logged at INFO level with URL + HTTP code (no body)
• Failed calls logged at ERROR level with URL + HTTP code + truncated response (max ~500 chars)
• FWLogMsg("ERROR", , "REST_CLIENT", FunName(), , "01", cMessage, 0, 0, {}) pattern used
• No use of ConOut() for production logging (only acceptable in standalone smoke tests)
• No secrets, tokens, passwords, or full request bodies emitted to logs

SonarQube Compliance

• No hardcoded passwords, tokens, or API keys in source code
• No IIF() — use If/Else/EndIf blocks
• GetMV() calls outside of loops
• No UI functions (MsgAlert, MsgYesNo, Aviso, Help) inside the call path of a transaction or scheduled job
• Includes in lowercase (e.g., #include "totvs.ch")
• No use of RpcSetEnv inside REST endpoint handlers that themselves invoke FWRest — environment must already be prepared

Refer to references/sonarqube-rules-reference.md for the complete SonarQube rules reference.

Common Pitfalls