Skip to content

Commit bbd39ac

Browse files
authored
docs: clarify northbound and southbound URLs in Send TD feature (#190)
* docs: clarify northbound and southbound URLs in Send TD feature Signed-off-by: Pranav Ghorpade <pranavghorpade61@gmail.com> * style: apply prettier formatting to README --------- Signed-off-by: Pranav Ghorpade <pranavghorpade61@gmail.com>
1 parent 3c6c4ad commit bbd39ac

File tree

1 file changed

+29
-4
lines changed

1 file changed

+29
-4
lines changed

README.md

Lines changed: 29 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,8 @@ This project aims to make creating W3C Thing Description (TD) instances and Thin
1818
- Exporting the Thing Description / Thing Model from the visual representation into JSON-LD
1919
- Reading/writing exposed properties' values exposed by a proxy (anything that can translate a protocol to HTTP)
2020
- Contributing the Thing Model to a third-party catalog using the Thing Model Catalog (TMC) API.
21-
The detailed API specification is available [here](https://github.com/wot-oss/tmc/blob/main/api/tm-catalog.openapi.yaml).
21+
The detailed **Thing Model Catalog (TMC) OpenAPI specification** is available
22+
[here](https://github.com/wot-oss/tmc/blob/main/api/tm-catalog.openapi.yaml).
2223

2324
## Technologies
2425

@@ -86,14 +87,38 @@ A local repository folder will be created inside the tm-catalog directory
8687

8788
### Send TD feature
8889

89-
To use the **_Send TD_** feature, it is necessary to define in the Settings pop-up the Southbound URL and Northbound URL. The Send TD feature allows you to send your Thing Description to any service following [the WoT TD Directory specification](https://www.w3.org/TR/wot-discovery/#exploration-directory-api-things).
90+
#### Northbound and Southbound URLs
91+
92+
When using the **Send TD** feature, ediTDor communicates with a proxy that exposes
93+
an HTTP interface for interacting with a Thing.
94+
95+
- **Southbound URL**
96+
- Base _Things API collection endpoint_ of the proxy where ediTDor sends the original Thing Description
97+
- ediTDor performs a `POST` to this endpoint; the proxy assigns the Thing/TD identifier
98+
- Used internally by the proxy to reach the underlying Thing using protocol-specific bindings (e.g., Modbus)
99+
100+
- **Northbound URL**
101+
- Base _Things API collection endpoint_ exposed by the proxy after the Thing Description is registered
102+
- ediTDor appends the encoded Thing/TD identifier to this base URL to fetch or interact with the proxied Thing Description
103+
- The proxied TD contains HTTP `href`s that ediTDor can invoke
104+
105+
In practice, ediTDor always interacts with the Thing **through the proxy via the Northbound URL**, while the Southbound URL is used internally by the proxy to communicate with the actual Thing.
106+
To use the **_Send TD_** feature, it is necessary to define in the Settings pop-up the Southbound URL and Northbound URL. The Send TD feature allows you to send your Thing Description to any service following the WoT Discovery _Things API_ specification
107+
(https://www.w3.org/TR/wot-discovery/#exploration-directory-api-things).
90108
Afterwards, if the service proxies the TD, ediTDor can fetch the proxied TD containing HTTP `href`s to interact with the original Thing.
91109

92110
#### Configuration
93111

94112
1. Open the Settings pop-up from the main toolbar
95-
2. Enter your Southbound URL in the designated field (e.g., `http://localhost:8080`)
96-
3. Click Save to store the URL
113+
2. Enter the **Southbound URL** (Things API collection endpoint, e.g. `http://localhost:8080/things/`)
114+
3. Enter the **Northbound URL** (Things API collection endpoint exposed by the proxy)
115+
4. Click Save to store the URLs
116+
117+
> ⚠️ Important
118+
> Do **not** paste a full Thing or TD resource URL (e.g. `/things/{id}`).
119+
> Both Northbound and Southbound URLs must point to the **Things API collection endpoint**
120+
> (typically ending with `/things/`).
121+
> ediTDor automatically appends the Thing/TD identifier when sending or fetching data.
97122
98123
The proxy uses the TD sent to its southbound API endpoint to communicate with a Thing. This way, you can interact with a non-HTTP Thing from your ediTDor.
99124

0 commit comments

Comments
 (0)