---
title: How HuxxConnect Works
slug: how-huxxconnect-works
type: explanation
plugin: huxx-connect
summary: The HuxxConnect mental model — describe an API and its endpoints once, then display or sync that data anywhere while the plugin handles auth, caching, and logging.
keywords: [architecture, mental model, request lifecycle, caching]
version_added: 1.2.5
version_updated: 1.2.5
level: beginner
related: [what-is-an-api, glossary, your-first-api-connection]
---

HuxxConnect works like the contacts app on your phone. You save a contact once — name, number, any access code — and from then on, every call is one tap; you never re-type the number. In HuxxConnect, the contact card is your [API](/docs/connect/explanation/glossary/#api) configuration, and the taps are shortcodes, PHP calls, and Pro syncs anywhere on your site.

## Configure once, use anywhere

Everything in HuxxConnect hangs off two saved things:

- An **API** — the service's base URL, its [credentials](/docs/connect/explanation/glossary/#credentials), and shared defaults. Credentials are encrypted before they are stored.
- Its **[endpoints](/docs/connect/explanation/glossary/#endpoint)** — one per kind of data, each with a path, HTTP method, [parameters](/docs/connect/explanation/glossary/#parameters), and a [cache duration](/docs/connect/explanation/glossary/#cache-duration-ttl).

Both get short IDs (like `demo_api` and `get_products`). Every other feature refers to those IDs, so changing a token or a URL happens in one place, and every page using it picks up the change.

<!-- screenshot-todo: apis-list--populated--demo-api-row | alt: APIs list screen with the Demo API (DummyJSON) configured and its endpoint count visible -->

## Two ways to use the data

**Display** shows API data live wherever the shortcode or PHP call runs — in a post, a template, a page builder.

Shortcode:

```text
[huxx_api api_id="demo_api" endpoint_id="get_products" keys="products.0.title"]
```

Output:

```html
<pre class="huxx-connect-response">Essence Mascara Lash Princess</pre>
```

PHP (in a theme template):

```php
<?php
$data = huxx_api( 'demo_api', 'get_products' );

if ( ! huxx_api_is_error( $data ) ) {
    echo esc_html( $data['products'][0]['title'] );
}
```

Output:

```text
Essence Mascara Lash Princess
```

**Sync** (Pro) goes the other direction: on a schedule, it pulls data from an endpoint and stores each item as a WordPress post, following your field mappings and [sync mode](/docs/connect/explanation/glossary/#sync-mode). Display is right for live, always-current values; sync is right when the data should become real content you can query, search, and theme like any other posts.

## The life of a request

Every display call — shortcode or PHP — runs the same pipeline:

```mermaid
flowchart TD
    A[Shortcode or PHP call] --> B[Look up the API and endpoint by ID]
    B --> C[Resolve authentication]
    C --> D[Build the request: URL, parameters, credentials]
    D --> E{Fresh cached copy?}
    E -- yes --> F[Return the cached response]
    E -- no --> G[Send the HTTP request]
    G --> H[Parse the response]
    H --> I[Cache it and log the request]
    I --> J[Return the data for display]
```

1. **Look up** the API and endpoint configurations by their IDs.
2. **Resolve authentication** — decrypt the credentials and pick the right auth handler for the API's type (Bearer token, API key, Basic Auth, and so on).
3. **Build the request** — combine base URL, path (with any [path variables](/docs/connect/explanation/glossary/#path-variable) filled in), parameters, and the credentials.
4. **Check the cache.** For GET requests on endpoints with a cache duration, a fresh stored copy is returned immediately — no HTTP request at all.
5. **Send the HTTP request** and time it.
6. **Parse the response** into usable data, then **log the request** (with credentials masked) so you can inspect it later.
7. **Cache the successful response** for the endpoint's cache duration, then return the data to whatever asked for it.

The practical upshot: repeat visitors don't each trigger a fresh API request, and slow or rate-limited APIs stop being a page-speed problem.

## When a request fails

A failed request — the API is down, the token expired, the network dropped — returns an error object instead of data. By default site visitors see nothing rather than an error dump; the details go to the request log, and administrators can turn on debug output to see them inline.

If the endpoint keeps a [stale-cache fallback](/docs/connect/explanation/glossary/#stale-cache-fallback) copy, HuxxConnect serves that older response instead, so a flaky API degrades to slightly-outdated data rather than a blank spot on the page.

## See it in practice

- [Your First API Connection](/docs/connect/tutorial/your-first-api-connection/) — build the DummyJSON example above yourself, start to finish.
- [Displaying API Data](/docs/connect/tutorial/displaying-api-data/) — go deeper on shortcodes, keys, and template functions.
- [Cache Endpoint Responses](/docs/connect/how-to/cache-endpoint-responses/) — tune cache duration and the stale-cache fallback.