# i3X API

> Read the plant model, live values and history of a Proxus hub through the CESMII i3X 1.0 interface, so i3X clients work without custom code.

Source: https://proxus.io/docs/develop/i3x

The hub serves the plant through **CESMII i3X 1.0** (Industrial Information Interoperability eXchange), a vendor
neutral REST interface for manufacturing data. An i3X client reads the plant tree, the machine types, every device
in its type's shape, the latest values and their history. The interface is read only. The CESMII i3X conformance
suite rates it **1.0 Compatible**: every required behavior and streaming pass; writing values, which is optional, is not
offered.

The base address is `https://<hub>/api/i3x/v1`. `GET /info` answers without signing in; every other call needs a
token, the same as the [REST API](https://proxus.io/docs/develop/rest-api#step-1-get-a-token), in the `Authorization: Bearer` header. A
caller sees only what their role may see.

## What a client finds

| i3X | In Proxus |
| --- | --- |
| Namespaces | `urn:proxus:i3x` (plant levels, value types, relationships) and `urn:proxus:machinetypes` (the machine types). |
| Object types | Each [machine type](https://proxus.io/docs/organize/machine-types) as a JSON Schema: its fields with data type, unit (`x-unit`) and limits, the fields of the type it builds on and its components expanded. Plant levels and value types (`number`, `integer`, `boolean`, `string`) have types of their own. |
| Root objects | The top of the plant tree (enterprise, or site). Under each place are the places and devices below it (`HasParent` / `HasChildren`). |
| Devices | One object per device, typed by its machine type (`UnknownType` without one). Its components and mapped fields are composed children (`HasComponent` / `ComponentOf`). |
| Values | A field's value is the latest value of the tag it is mapped to, with its quality and time. A device's value is the object of its fields; `maxDepth` 0 or 2 also returns its components. |
| History | `POST /objects/history` returns a field's values in the range, from the stored readings. |
| Subscriptions | Sync: each `/subscriptions/sync` returns what changed since the last one, with sequence numbers to acknowledge. Stream: `/subscriptions/stream` opens Server-Sent Events that send each change as it is seen (the latest values are read every second); a new stream ends the open one, and sync waits until it is closed. |

Element ids stay the same: `place:<id>`, `device:<id>`, and `device:<id>/<field>` for a field (`device:4/Main/Speed`
for a component's field). Calculated fields are not offered yet.

## Try it

```bash
TOKEN=$(curl -s -X POST http://localhost:8080/api/Authentication/Authenticate \
  -H "Content-Type: application/json" -d '{"userName":"Admin","password":""}')
curl -s http://localhost:8080/api/i3x/v1/objects?root=true -H "Authorization: Bearer $TOKEN"
curl -s -X POST http://localhost:8080/api/i3x/v1/objects/value -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"elementIds":["device:5"],"maxDepth":0}'
```

## What's next

- [Machine types](https://proxus.io/docs/organize/machine-types): the types i3X serves.
- [REST API](https://proxus.io/docs/develop/rest-api): tokens and the hub's own API.
