Calling other services

Two ways to make an outbound HTTP call. A `client` block is a typed wrapper around a known API — name the base URL once, declare each operation as a verb-tagged method. `Http.*` is the facade for a URL you only know at runtime — a webhook, a discovered endpoint. Both hand back an `HttpResponse` you branch on; a non-2xx is a value, not a throw.

Summary#

When your app has to reach out to another service — a payment API, a shipping tracker, a webhook — you have two tools, and which one you pick is decided by a single question: do you know the API at author time?

You know it → a typed a typed HTTP client (client) block. You declare the shape once and every call site is type-checked.
You don't (the URL is built at runtime) → the Http.* Http.*.

Either way the result is an HttpResponse, and a non-2xx status is an ordinary value you branch on — not an exception you have to catch.

Description#

A typed client for a known API#

A a typed HTTP client (client) block is the one to reach for when you're integrating a specific, known API. Inside client Shipping { … } you name the BaseUrl once and declare each operation tagged with its verb ([Get], [Post], [Put], [Patch], [Delete]) and a path — e.g. [Get("/track/{code}")] TrackResult Track(string code);. The request and response bodies are typed, so a call site that passes the wrong shape is a compile error, not a 4am surprise. It reads like calling a local method; the platform does the HTTP. Full syntax and examples on a typed HTTP client (client).

The facade for a runtime URL#

When the URL isn't knowable until runtime — a webhook target stored on a record, an endpoint you just discovered — use the Http.*. Http.Get/Post/Put/Delete take the URL as a value and return an HttpResponse, so a webhook call is var res = Http.Post(webhookUrl, body); and you branch on res.IsSuccess.

The response is a value, not a throw#

An HttpResponse carries the status code, the body as text, and an IsSuccess flag (true for 2xx). A non-2xx — a 404, a 500, a rate-limit 429 — is a normal return you inspect, not an exception. That is deliberate: an outbound call fails in ordinary, expected ways, and forcing every one through a try/catch would be noise. You branch on the status the same way you'd branch on any other value.

Credentials belong in secrets#

An API key or client secret an outbound call needs is declared as a secret, never inlined. For signing users in through a third party, or calling an API on a user's behalf, see OAuth clients (app.OAuthClients).