Attaching JSON web services to Buffaly tools

Model an external JSON web service as a ProtoScript service, then expose small typed actions that call named JSON routes through a shared helper.

Reference implementation

The Feeding Frenzy JSONWS integration is the reference pattern. It turns route-based endpoints under https://ff.medek.ai into Buffaly tools while keeping endpoint configuration, authentication, and route execution reusable.

Service-owned binding and helper methods

Actions should not assemble full URLs or read secrets. They pass a route path and a JsonObject to the service. The service passes its BaseUrl, API prefix, and TokenKey to JsonWsHelper.CallJsonRouteSecure(...).

prototype FeedingFrenzyJsonWsService : Service
{
    String BaseUrl = new String();
    String BusinessApiPrefix = "api/feedingfrenzy.admin.business";
    String UiApiPrefix = "api/feedingfrenzy.admin.ui";
    String TokenKey = "FeedingFrenzy.ApiKey";

    function Initialize() : string
    {
        if (StringUtil.IsEmpty(this.BaseUrl))
            return "Error: BaseUrl must be set on the binding.";
        return "initialized";
    }

    function CallBusinessRoute(string routePath, JsonObject args) : string
    {
        JsonObject normalizedArgs = args == null ? new JsonObject() : args;
        return JsonWsHelper.CallJsonRouteSecure(this.BaseUrl, this.BusinessApiPrefix, routePath, this.TokenKey, normalizedArgs);
    }
}

Action wrappers

Each wrapper should validate that a service binding was supplied, build a JsonObject with exactly the parameter names the JSONWS route expects, and call either CallBusinessRoute(...) or CallUiRoute(...).

Authentication and secret handling

A JSONWS binding should store only a logical secret key. The secret value belongs in UserSecrets, not in .pts, .json, .cs, wiki, markdown history, logs, or prompt output.

• Use keys such as FeedingFrenzy.ApiKey and FeedingFrenzy.Local.ApiKey.
• Import legacy environment variable values into canonical UserSecrets without printing them.
• Smoke tests should report that a key resolves and a route returns data, never the bearer token itself.

Scaling the pattern to a larger API

For a small API, a few actions in index.pts may be enough. For a larger API, split actions by remote class or route family and include them from index.pts. This mirrors upstream JSONWS classes and makes route comparison or regeneration easier.