<commit_before>---
layout: documentation
---

{% include base.html %}

# REST API

## Introduction

The REST API of Eclipse SmartHome serves different purposes. It can be used to integrate with other system as it allows read access to items and item states as well as status updates or the sending of commands for items. Furthermore, it gives access to things, links, sitemaps, etc., so that it is the main interface to be used by remote UIs (e.g. fat clients or HTML5 web applications).

The REST API is complemented by support for server sent events (SSE), so you can subscribe  on change notification for certain resources.

## Configuration Options

By default, the REST API is registered on the HTTP service under `rest`. This configuration can be changed through configuring the property `root` of the service pid 
`com.eclipsesource.jaxrs.connector` through the Configuration Admin service.

## REST Endpoints

The details about available REST urls, their parameters, etc. can be found [here](../../rest/index.html).

## Server Sent Events (SSE)

In order to receive notice of important events outside of the Eclipse SmartHome framework they are exposed using the Server Sent Events (SSE) standard.

To subscribe to events a developer can listen to `/rest/events`. In general any SSE Consumer API can be used (for example HTML5 EventSource Object) to read from the event stream.

### Events

The framework broadcasts all events on the Eclipse SmartHome event bus also as an SEE event. A complete list of the framework event types can found in the [Event chapter](events.html).

All events are represented as JSON objects on the stream with the following format:

```json
{
    "topic": "smarthome/inbox/yahooweather:weather:12811438/added",
    "type": "InboxAddedEvent",
    "payload": "{
        "flag": "NEW",
        "label": "Yahoo weather Berlin, Germany",
        "properties": {
            "location": "12811438"
        },
        "thingUID": "yahooweather:weather:12811438"
    }"
}
```

* `topic`: the event topic (see also [Runtime Events](events.html))
* `type`: the event type (see also [Runtime Events](event-type-definition.html))
* `payload`: String, which contains the payload of the Eclipse SmartHome event. For all core events, the payload will be in the JSON format. For example the `smarthome/items/item123/added` event will include the new item that was added and the `smarthome/items/item123/updated` event will include both old and new item.
  
### Filtering

By default when listening to `/rest/events` a developer will receive all events that are currently broadcasted. In order to listen for specific events the `topics` query parameter can be used.

For example while listening to `/services/events?topics=smarthome/items/*` a developer would receive notifications about item events only. The wildcard character (\*) can be used replacing one (or multiple) parts of the topic.
<commit_msg>fixed typos (#2744)<commit_after>---
layout: documentation
---

{% include base.html %}

# REST API

## Introduction

The REST API of Eclipse SmartHome serves different purposes. It can be used to integrate with other system as it allows read access to items and item states as well as status updates or the sending of commands for items. Furthermore, it gives access to things, links, sitemaps, etc., so that it is the main interface to be used by remote UIs (e.g. fat clients or HTML5 web applications).

The REST API is complemented by support for server sent events (SSE), so you can subscribe  on change notification for certain resources.

## Configuration Options

By default, the REST API is registered on the HTTP service under `rest`. This configuration can be changed through configuring the property `root` of the service pid 
`com.eclipsesource.jaxrs.connector` through the Configuration Admin service.

## REST Endpoints

The details about available REST urls, their parameters, etc. can be found [here](../../rest/index.html).

## Server Sent Events (SSE)

In order to receive notice of important events outside of the Eclipse SmartHome framework they are exposed using the Server Sent Events (SSE) standard.

To subscribe to events a developer can listen to `/rest/events`. In general any SSE Consumer API can be used (for example HTML5 EventSource Object) to read from the event stream.

### Events

The framework broadcasts all events on the Eclipse SmartHome event bus also as an SSE event. A complete list of the framework event types can be found in the [Event chapter](events.html).

All events are represented as JSON objects on the stream with the following format:

```json
{
    "topic": "smarthome/inbox/yahooweather:weather:12811438/added",
    "type": "InboxAddedEvent",
    "payload": "{
        "flag": "NEW",
        "label": "Yahoo weather Berlin, Germany",
        "properties": {
            "location": "12811438"
        },
        "thingUID": "yahooweather:weather:12811438"
    }"
}
```

* `topic`: the event topic (see also [Runtime Events](events.html))
* `type`: the event type (see also [Runtime Events](event-type-definition.html))
* `payload`: String, which contains the payload of the Eclipse SmartHome event. For all core events, the payload will be in the JSON format. For example the `smarthome/items/item123/added` event will include the new item that was added and the `smarthome/items/item123/updated` event will include both old and new item.
  
### Filtering

By default when listening to `/rest/events` a developer will receive all events that are currently broadcasted. In order to listen for specific events the `topics` query parameter can be used.

For example while listening to `/services/events?topics=smarthome/items/*` a developer would receive notifications about item events only. The wildcard character (\*) can be used replacing one (or multiple) parts of the topic.

{'fraction_non_alphanumeric': 0.07797304214297901, 'fraction_numerical': 0.011602115679918102, 'mean_word_length': 4.124125874125874, 'pattern_counts': {'":': 16, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2958640', 'n_tokens_mistral': 1565, 'n_tokens_neox': 1465, 'n_words': 789}