Skip to content

Commit a8e7df5

Browse files
AMasyuninAMasyunin
committed
Updated overview to provide more clear business-context. Added separate Authentication description.
1 parent 4ee4807 commit a8e7df5

File tree

4 files changed

+435
-59
lines changed

4 files changed

+435
-59
lines changed

‎assets/images/Flow-example.png

57.4 KB
Loading

‎docs/Overview.md

+166-58
Original file line numberDiff line numberDiff line change
@@ -6,90 +6,198 @@ stoplight-id: ie3rt9xv91kie
66

77
<!-- theme: warning -->
88
> *BETA Version!* <br>
9-
>Now the easrly access of IoT Logic's API is implemented, which means possible changes in the near future. Feel free to try the functionality, however, you may need to introduce changes in your applications reflecting the API functionality updates. Stay tuned!
9+
>Now the early access of IoT Logic's API is implemented, which means possible changes in the near future. Feel free to try the functionality, however, you may need to introduce changes in your applications reflecting the API functionality updates. Stay tuned!
1010
1111
## Introduction
1212

13-
The Navixy IoT Logic API provides a powerful way to manage data flows from your IoT devices. This API allows you to:
13+
**Navixy IoT Logic** is a no-code/low-code tool that enables seamless IoT data processing and integration. Its API provides programmatic access to create, manage, and optimize data flows between IoT devices and destination systems without requiring extensive development resources.
1414

15-
- Create custom data processing pipelines
16-
- Transform raw device data into meaningful business metrics
17-
- Route processed data to external systems
18-
- Configure and manage data endpoints
19-
- Build complex IoT data workflows through a flexible node system
15+
### Purpose and core capabilities
2016

21-
This guide will help you navigate the various API endpoints and create your own IoT data flows, starting with the most common use case - sending your device data to an external system.
17+
**Navixy IoT Logic** functions as a data flow manager that:
2218

23-
## API Overview
19+
- Receives information from devices connected to the platform
20+
- Decodes and converts data in real-time
21+
- Sends processed data to other platforms and services
22+
- Enables building complex flows with nodes responsible for specific data processing tasks
23+
- Standardizes telematics data through the [Navixy Generic Protocol](https://docs.navixy.com/iot-logic/ngp)
2424

25-
The Navixy IoT Logic API is organized around **Flows** - data processing pipelines.
25+
The **IoT Logic API** allows developers and system integrators to programmatically implement these capabilities, making it effective for organizations that need to:
2626

27-
Each flow consists of:
28-
- **Nodes** - Processing elements (data sources, transformations, outputs)
29-
- **Transitions** (**Edges**) - Connections between nodes that define the data path
27+
- Work efficiently with decoded device data
28+
- Apply flexible data transformation to match specific business needs
29+
- Monitor and troubleshoot data streams
30+
- Create consistent data flows across multiple devices and protocols
3031

31-
### API Response Structure
32+
### Key concepts
3233

33-
All API responses follow a consistent pattern:
34+
**Navixy IoT Logic** operates based on two fundamental components that work together to process device data:
3435

35-
* Success responses include a `success: true` field
36-
* Error responses include `success: false` and a `status` object with:
37-
* `code`: Numeric error code
38-
* `description`: Human-readable error description
36+
#### Flow
3937

40-
### Flow Architecture
38+
A **Flow** is the foundation for all data logic in the product. It defines how data moves through stages of reception, enrichment, and transmission. Each flow consists of connected nodes that determine what happens to the data at each processing stage.
4139

42-
Flows in Navixy IoT Logic follow a directed graph architecture:
40+
Key characteristics of flows:
41+
- Flows can be enabled or disabled to control data processing
42+
- Every flow requires at least one data source and one output endpoint
43+
- Each device can only be assigned to one flow at a time
44+
- Flows process data in real-time as it arrives from devices
4345

44-
* Every flow must have at least one data source node (input)
45-
* Every flow must have at least one output endpoint node (termination point)
46-
* Each node has a unique ID within its flow (not globally unique)
47-
* Edges define directional data flow between nodes
48-
* Nodes can have multiple incoming and outgoing connections
49-
* Circular references are not supported
46+
#### Nodes
5047

51-
## Getting Started
48+
**Nodes** are the functional elements of a **flow**, with each node handling a specific stage of the data lifecycle. There are three primary types of nodes:
5249

53-
### Authentication
50+
- **Data Source node**: Receives data from M2M devices and serves as the entry point for all device data
51+
- **Initiate Attribute node**: Processes and enriches incoming data, including creating new calculated attributes trough mathematical operations in [Navixy IoT Logic Expression Language](https://docs.navixy.com/iot-logic/navixy-iot-logic-expression-language)
52+
- **Output Endpoint node**: Transmits data to target systems using the [Navixy Generic Protocol](https://docs.navixy.com/iot-logic/ngp). This node can be configured to use different endpoint types:
53+
- **Default endpoint**: Pre-configured destination for sending data to the Navixy platform
54+
- **MQTT endpoint**: Configurable connection for sending data to third-party systems and services
5455

55-
All API requests require an API key in the header:
56+
Nodes are connected through transitions (`edges`) that define the path data follows through the flow.
5657

57-
```
58-
Authorization: NVX your_api_key_here
59-
```
58+
### Data flow architecture
6059

61-
The API key must be prefixed with "NVX " (note the space after NVX). This is a custom Bearer format used by Navixy.
60+
The following screenshot from IoT Logic UI illustrates the basic architecture of a flow in IoT Logic:
6261

63-
According to the API specification:
62+
![Flow-example.png](../assets/images/Flow-example.png)
6463

65-
```
66-
"securitySchemes": {
67-
"api_key": {
68-
"description": "Enter an API key with the \"NVX: \" prefix, e.g. \"NVX 123456abcdefg\"",
69-
"example": "NVX 123456abcdefg",
70-
"type": "apiKey",
71-
"name": "Authorization",
72-
"in": "header",
73-
"bearerFormat": "NVX "
74-
}
75-
}
76-
```
7764

78-
### Base URLs
65+
This represents a simple linear flow where:
66+
1. The **Data Source** node collects telemetry from selected devices
67+
2. The **Initiate Attribute** node processes and enriches this data
68+
3. The **Default Output Endpoint** node delivers the transformed data to its destination - Navixy platform
69+
70+
More complex architectures can be created by:
71+
- Adding multiple data source nodes to process different device types
72+
- Chaining multiple attribute nodes for multi-stage data processing
73+
- Including several output endpoints to deliver data to multiple destinations outside Navixy simultaneously
74+
75+
## Quick start for IoT Logic API
7976

80-
Two regional servers are available:
81-
- Europe: `https://api.eu.navixy.com/`
82-
- Americas: `https://api.us.navixy.com/`
77+
To ensure a clear picture of the basic IoT Logic API capabilities, let's create your first flow.
8378

84-
### HTTP Methods
79+
The following example demonstrates how to create a complete flow with three nodes that sends data to Navixy. This flow will:
80+
1. Collect data from specified devices
81+
2. Calculate temperature in Fahrenheit from Celsius readings
82+
3. Send the enriched data to the Navixy platform
8583

86-
The API uses specific HTTP methods for different operations:
87-
- `GET`: For retrieving information (flow list, flow details)
88-
- `POST`: For creating, updating, and deleting resources
84+
### Step 1: Authentication
8985

90-
### Content Type
86+
First, authenticate to obtain a session token. To do it, send a POST request to the user authentication endpoint `{baseURL}/v2/user/auth` providing your account's login and passord as parameters:
9187

92-
All requests and responses use JSON format:
88+
```bash
89+
curl -X POST "https://your.server.com/v2/user/auth" \
90+
-H "Content-Type: application/json" \
91+
-d '{
92+
"login": "your_email_or_username",
93+
"password": "your_password"
94+
}'
9395
```
94-
Content-Type: application/json
96+
97+
Response (example):
98+
```jsonResponse
99+
{
100+
"success": true,
101+
"hash": "22eac1c27af4be7b9d04da2ce1af111b"
102+
}
103+
```
104+
105+
Copy the `hash` value from the response.
106+
107+
> For more details on how to authenticate your requests, see [Authentication](auth/Authentication.md).
108+
109+
### Step 2: Create a complete flow with nodes and connections
110+
111+
Create a flow with all nodes and connections in a single request:
112+
113+
```bash
114+
curl -X POST "https://your.server.com/iot/logic/flow/create" \
115+
-H "Content-Type: application/json" \
116+
-H "Authorization: NVX hash_value" \
117+
-d '{
118+
"flow": { # Flow entity creation
119+
"title": "Basic Temperature Monitoring",
120+
"enabled": true, # If true, the flow starts to process data immediately after creation
121+
"nodes": [ # Node entity creation right inside new flow
122+
{
123+
"id": 1, # First node creation with an ID unique within a flow
124+
"type": "data_source",
125+
"enabled": true,
126+
"data": { # Node-specific parameters, depend on node type
127+
"title": "Fleet Vehicles",
128+
"sources": [394892, 394893, 394894] # Actual data sources from your accountm can be found in Devices and Settings
129+
},
130+
"view": { # First node postion, defining the display in UI
131+
"position": {
132+
"x": 50,
133+
"y": 100
134+
}
135+
}
136+
},
137+
{ # Second node creation
138+
"id": 2,
139+
"type": "initiate_attributes",
140+
"data": {
141+
"title": "Temperature Conversion",
142+
"items": [
143+
{
144+
"name": "temperature_f",
145+
"value": "value(\"temperature\")*1.8 + 32",
146+
"generation_time": "genTime(\"temperature\", 0, \"valid\")",
147+
"server_time": "now()"
148+
}
149+
]
150+
},
151+
"view": { # Second node postion, defining the display in UI
152+
"position": {
153+
"x": 300,
154+
"y": 100
155+
}
156+
}
157+
},
158+
{
159+
"id": 3, # third node creation
160+
"type": "output_endpoint",
161+
"enabled": true,
162+
"data": {
163+
"title": "Navixy Platform",
164+
"output_endpoint_type": "output_navixy"
165+
},
166+
"view": { # Third node postion, defining the display in UI
167+
"position": {
168+
"x": 550,
169+
"y": 100
170+
}
171+
}
172+
}
173+
],
174+
"edges": [ # Transitions that connect nodes in a flow
175+
{
176+
"from": 1, # Notice, that nodes are referenced by their IDs
177+
"to": 2
178+
},
179+
{
180+
"from": 2,
181+
"to": 3
182+
}
183+
]
184+
}
185+
}'
186+
```
187+
188+
Response (example):
189+
```json
190+
{
191+
"success": true,
192+
"id": 123
193+
}
95194
```
195+
<!-- theme: success -->
196+
> This single request creates a complete flow that:
197+
> 1. Collects data from three specific devices (IDs: 394892, 394893, 394894)
198+
> 2. Converts temperature values from Celsius to Fahrenheit
199+
> 3. Transmits all data, including the new calculated attribute, to the Navixy platform
200+
>
201+
> The success response includes the ID of the newly created flow, which you can use for future operations like updating the flow or adding additional nodes.
202+
>
203+
> You can expand this example by adding more devices, creating additional calculated attributes, or configuring MQTT endpoints to send data to external systems.

0 commit comments

Comments
 (0)