> ## Documentation Index
> Fetch the complete documentation index at: https://grandcentral.backbase.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Call REST endpoints

> Use the gc-http-caller kamelet for every outbound REST call from a connector

The `gc-http-caller` kamelet is the canonical way to make any REST/JSON call out of the connector. Use it for every HTTP method by passing `?method=GET|POST|PUT|DELETE|PATCH`. It handles retries, timeouts, headers, query params, and path variables, and produces structured Grand Central errors through JOLT.

## How the kamelet reads inputs

The kamelet reads the URL, query parameters, path variables, and headers from the exchange. Set them before the `.to(...)` call.

| Where to put it   | Key                            | Type                  | Purpose                                                             |
| ----------------- | ------------------------------ | --------------------- | ------------------------------------------------------------------- |
| Exchange property | `gc-http-caller-url`           | `String`              | The full URL to call; interpolate the vendor base URL with the path |
| Exchange property | `gc-http-caller-queryParams`   | `Map<String, Object>` | Query parameters appended to the URL                                |
| Exchange property | `gc-http-caller-pathVariables` | `Map<String, Object>` | Path variables to substitute into `{name}` placeholders in the URL  |
| Header            | `gc-http-caller-headers`       | `Map<String, Object>` | Additional headers to send with the call                            |

The kamelet writes all of these onto the outgoing HTTP request and clears them after the call returns.

## Kamelet parameters you can tune

The following parameters have defaults, but you can override them in configuration properties in the Grand Central DevHub Application Live repository of your installation: `https://github.com/bb-ecos-${installation}/gc-devhub-${installation}-applications-live/tree/main/runtimes/{runtime}/values/{namespace}/{deployment-name}-values.yaml`

| Parameter                                    | Default                        | Purpose                                                                            |
| -------------------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------- |
| `method`                                     | `GET`                          | HTTP verb: one of `GET`, `POST`, `PUT`, `DELETE`, or `PATCH`                       |
| `contentType`                                | `application/json`             | `Content-Type` header for the request                                              |
| `accept`                                     | `application/json`             | `Accept` header for the response                                                   |
| `gc-http-caller-retry`                       | `false`                        | Enable retry on transient failures                                                 |
| `retryStatuses`                              | `429,500,502,503,504`          | HTTP status codes that trigger a retry                                             |
| `connectTimeout`                             | `5000` ms                      | TCP connect timeout                                                                |
| `soTimeout`                                  | `5000` ms                      | Socket read timeout                                                                |
| `responseTimeout`                            | `5000` ms                      | Wait-for-response timeout                                                          |
| `connectionsPerRoute`                        | `20`                           | Pooled connections per route                                                       |
| `maxTotalConnections`                        | `200`                          | Pool size cap across routes                                                        |
| `gc-http-caller-handleExceptionsInConnector` | `false`                        | If `true`, the kamelet doesn't auto-wrap errors and the connector must handle them |
| `errorTemplate`                              | `transform-error-details.json` | JOLT spec used to map vendor errors to Grand Central error JSON                    |

## Typical call forms

```java theme={"system"}
// Simplest GET
.setProperty("gc-http-caller-url", simple("{{vendor.base.url}}/api/path"))
.to("kamelet:gc-http-caller?method=GET");

// GET by ID using a header
.setProperty("gc-http-caller-url",
    simple("{{vendor.base.url}}/api/path/${header.entityId}"))
.to("kamelet:gc-http-caller?method=GET");

// GET with query params from a Map
.setProperty("gc-http-caller-queryParams", paramsMap)
.setProperty("gc-http-caller-url", simple("{{vendor.base.url}}/api/path"))
.to("kamelet:gc-http-caller?method=GET");

// POST with retry enabled
.to("kamelet:gc-http-caller?method=POST&gc-http-caller-retry={{retryFlag}}");
```

## Exception-handler kamelets

You typically register these once in `configure()` through `onException(...)`. Each turns a thrown exception into a structured Grand Central error response.

Kamelet files are available in the `grandcentral-platform-kamelets` artifact.

| Kamelet                                   | Use it for                                                                                           |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `http-exception-handler`                  | `HttpOperationFailedException` from the vendor; wraps in Grand Central error JSON through JOLT       |
| `json-validation-exception-handler`       | `JsonValidationException` from the schema validator; returns HTTP 400 with GC024 and detailed errors |
| `service-exception-handler`               | Service-level failures                                                                               |
| `grand-central-service-exception-handler` | `GrandCentralServiceException` thrown explicitly from the connector                                  |
| `generic-exception-handler`               | Catch-all fallback for unknown exceptions                                                            |
| `validation-exception-handler`            | General validation errors, for example from `PredicatesValidatingProcessor`                          |
| `custom-http-error-handler`               | Custom HTTP error mapping when the standard handler isn't enough                                     |

Example registration:

```java theme={"system"}
onException(JsonValidationException.class)
    .handled(true)
    .to("kamelet:json-validation-exception-handler"
        + "?schemaErrorTemplate=transform-schema-validation-error-details.json");

onException(HttpOperationFailedException.class)
    .handled(true)
    .to("kamelet:http-exception-handler?errorTemplate=transform-error-details.json");

onException(Exception.class)
    .handled(true)
    .to("kamelet:generic-exception-handler");
```

## Next step

For the Camel building blocks that connect these calls, see [Use Camel EIPs](/platform/developer-guides/build/use-camel-eips).