# Fabric API - Events

The Kafka and REST connections for an eventstream endpoint, every field of each.

An eventstream's custom endpoint accepts Kafka and REST clients, so the connections below are Zato's Kafka and REST connections configured for Fabric. The [events](https://zato.io/docs/dev/examples/cloud/fabric/events.html) page uses them in services. Eventhouses are queried with the Fabric connection's [query\_events](https://zato.io/docs/dev/examples/cloud/fabric/api/queries.html#query_events).

## Where the values come from {#where-the-values-come-from}

All values on this page come from the Details pane of the eventstream's custom endpoint, on the SAS Key Authentication page of its Kafka tab, whether the endpoint is a source (Zato sends) or a destination (Zato receives):

| In Fabric | Used as |
| --- | --- |
| Bootstrap server | The Kafka address, `<namespace>.servicebus.windows.net:9093` |
| Topic name | The Kafka topic, and the `<topic name>` in the REST address |
| Connection string-primary key | The password of a Basic Auth definition for the `PLAIN` mechanism |
| Consumer group | The Kafka channel's consumer group, on the Basic page of the destination |

The namespace is the first part of the bootstrap server, up to `.servicebus.windows.net`.

## Security definitions {#security-definitions}

Two kinds of definition sign a Kafka connection in, and both are created under `Security` in the Dashboard:

| Mechanism | Definition | Fields |
| --- | --- | --- |
| `OAUTHBEARER` | Bearer token | Username the application (client) ID, Password the client secret, Auth endpoint `https://login.microsoftonline.com/<tenant ID>/oauth2/v2.0/token`, Scopes `https://<namespace>.servicebus.windows.net/.default` |
| `PLAIN` | Basic Auth | Username `$$ConnectionString`, Password the connection string |

The username is entered as `$$ConnectionString` because a value starting with a single `$` names an environment variable, and doubling it gives the literal `$ConnectionString`.

An environment holds one Bearer token definition per client ID, so the Kafka scope and the REST scope each sign in as an app registration of their own, added to the workspace as a Contributor.

## Kafka outgoing connection {#kafka-outgoing-connection}

Under `Connections → Message queues → Kafka → Outgoing connections`:

| Field | Value |
| --- | --- |
| Name | Any, used as `self.out.kafka[name]` |
| Address | The bootstrap server |
| Topic | The topic name |
| SSL | On |
| Security | The Bearer token or Basic Auth definition |
| SASL mechanism | `OAUTHBEARER` or `PLAIN`, matching the definition |

```yaml
outgoing_kafka:
  - name: Fabric Events
    address: <namespace>.servicebus.windows.net:9093
    topic: <topic name>
    security: Fabric Events Token
    sasl_mechanism: OAUTHBEARER
    ssl: true
```

A dict passed to `send` is JSON-encoded before it leaves:

```python
event = {
    'event_type': 'admission',
    'location': 'Riverside',
    'admission_id': 'ADM-1041',
}

self.out.kafka['Fabric Events'].send(event)
```

## Kafka channel {#kafka-channel}

Under `Connections → Message queues → Kafka → Channels`:

| Field | Value |
| --- | --- |
| Name | Any |
| Address | The bootstrap server |
| Topic | The topic name |
| Consumer group | The group created for Zato on the destination |
| Service | The service to run for each event |
| SSL | On |
| Security | The Bearer token or Basic Auth definition |
| SASL mechanism | `OAUTHBEARER` or `PLAIN`, matching the definition |

```yaml
channel_kafka:
  - name: Fabric Alerts
    address: <namespace>.servicebus.windows.net:9093
    topic: <topic name>
    group_id: zato
    service: fabric.notify-purchasing
    security: Fabric Events Token
    sasl_mechanism: OAUTHBEARER
    ssl: true
```

The eventstream sends events in batches, as a JSON list, which the service receives parsed in `self.request.input`:

```python
for event in self.request.input:
    item_id = event['item_id']
```

## REST alternative for sending {#rest-alternative-for-sending}

The same endpoint also takes events over HTTPS. Under `Connections → REST → Outgoing connections`:

| Field | Value |
| --- | --- |
| Host | `https://<namespace>.servicebus.windows.net` |
| URL path | `/<topic name>/messages` |
| Data format | JSON |
| Security | A Bearer token definition with Scopes `https://eventhubs.azure.net/.default` |

The body is a list of events, each wrapped in `Body`, sent with the endpoint's own content type:

```python
body = json.dumps(event)
payload = [{'Body': body}]
headers = {'Content-Type': 'application/vnd.microsoft.servicebus.json'}

self.rest['Fabric Events REST'].post(payload, headers=headers)
```

## See also {#see-also}

- [Fabric events](https://zato.io/docs/dev/examples/cloud/fabric/events.html) - Services that send, receive and read events with these connections
- [Fabric API - Queries](https://zato.io/docs/dev/examples/cloud/fabric/api/queries.html) - query\_events, KQL queries against an eventhouse through the Fabric connection
- [Fabric API - Connection](https://zato.io/docs/dev/examples/cloud/fabric/api/connection.html) - The app registration the Kafka definition signs in as

## Learn more {#learn-more}

- [Development documentation](https://zato.io/docs/dev/) - The complete reference for writing services
- [Requests and responses](https://zato.io/docs/dev/request-response/) - What a service receives, what it returns and how both are structured
- [Integration examples](https://zato.io/docs/dev/examples/) - Ready-made code for the systems you are likely to connect to
- [IDE and debugging](https://zato.io/docs/dev/ide/) - Write services in the Dashboard or in your own editor
- [Data models](https://zato.io/docs/dev/model/) - Declare inputs and outputs and have them validated for you
- [In-depth API tutorial](https://zato.io/tutorials/main/01.html) - The full platform tutorial, from installation to production patterns