# HTTP Server/Node The HTTP Server resource offers access to data points through a HTTP/REST interface. * This server will accept JSON data via POST or PUT and forwarding that data to corresponding MQTT topic. * User access and authentication can be configured using the existing connectware functionalities for HTTP permissions. * The listening port is the same port 443 which is also used for HTTPS access to the other REST interfaces of Connectware, where each request with the path `/data` refers to the internal HTTP server for data access. The HTTP server can be configured using the `Cybus::Server::Http` resource. The server resource defines an optional base path prefix in addition to the standard `/data` prefix. Each HTTP route is described by a `Cybus::Node::Http` resource that defines the path and http method as parameters to specify the route. For configuration reference, see: * [HTTP Server Properties](/2-4-0/connectors/servers/http-server/httpserver.md) * [HTTP Node Properties](/2-4-0/connectors/servers/http-server/httpnode.md) ## Permissions Connectware controls access to HTTP endpoints using the existing role and permission system. For more information, see [Roles](/2-4-0/documentation/user-management/roles.md) and [Permissions](/2-4-0/documentation/user-management/permissions.md). For the example below where the user should PUT or POST to the route `data/cybustest/postRoute`, the user must be granted matching write permissions, for example `data/cybustest/#` or `data/+/postRoute`. ## Sending Data to the HTTP Server ### JSON If the server receives a request with the `Content-Type: application/json` header, it parses the HTTP message body as JSON and wraps it in the `value` property of the internal message convention. **Example** {% code lineNumbers="true" %} ```json // Original message sent to HTTP server { "machineState": "okay", "temperature": 23, "logs": ["message1", "message2"] } ``` {% endcode %} The resulting output at the MQTT broker: {% code lineNumbers="true" %} ```json // Message received by MQTT broker { "timestamp": 12391238123, // milliseconds since epoch "value": { "machineState": "okay", "temperature": 23, "logs": ["message1", "message2"] } } ``` {% endcode %} If the request body is not valid JSON, the server drops it and does not forward it to the MQTT broker. ### Other Formats Other supported MIME types in the `Content-Type` header are: * application/octet-stream * text/plain * text/xml * text/csv In all of these cases, the server forwards the HTTP message body to the specified topic without further modification — no `timestamp` or `value` wrapping is applied. ## Receiving Data from the HTTP Server ### JSON Each node with `method: GET` has an internal cache that stores the latest value written to it via the `*/write` topic (depth of 1). The response is always a JSON object containing `value` and `timestamp`. If no `timestamp` is provided, one is generated. If no data is available, the server responds with HTTP 204. For example, if the following message is published to the MQTT broker: {% code lineNumbers="true" %} ```json // Original message sent to MQTT broker { "value": "Cybus" } ``` {% endcode %} Resulting protocol-mapper output at the MQTT broker {% code lineNumbers="true" %} ```json { "timestamp": 12391238123, // milliseconds since epoch "value": "Cybus" } ``` {% endcode %} ## Service Commissioning File Example The endpoints from the service commissioning file can be accessed using the following `curl` commands. These assume Connectware is configured for basic auth authentication and that the user has sufficient HTTP permission to write to the path `data/cybustest/postRoute`. The POST based demo endpoint: {% code lineNumbers="true" %} ```bash curl --location --request POST 'https://example.com/data/cybustest/postRoute' \ --header 'Authorization: Basic ${BASIC_AUTH_TOKEN}' \ --header 'Content-Type: application/json' \ --data-raw '{ "test1": "testdata send via POST Route" }' ``` {% endcode %} The PUT based demo endpoint: {% code lineNumbers="true" %} ```bash curl --location --request PUT 'https://example.com/data/cybustest/putRoute' \ --header 'Authorization: Basic ${BASIC_AUTH_TOKEN}' \ --header 'Content-Type: application/json' \ --data-raw '{ "test2": "testdata send via PUT Route" }' ``` {% endcode %} The GET based demo endpoint: {% code lineNumbers="true" %} ```bash curl --location --request GET 'https://example.com/data/cybustest/getRoute' \ --header 'Authorization: Basic ${BASIC_AUTH_TOKEN}' ``` {% endcode %} Replace `${BASIC_AUTH_TOKEN}` with your base64-encoded credentials. {% file src="/files/RO30Q4g86vWjxvfLYtis" %} {% code title="http-server-example.yml" lineNumbers="true" expandable="true" %} ```yaml --- description: Provides a demonstration structure for a http server configured in the protocol mapper metadata: name: Definition By Example for HTTP Endpoints parameters: {} resources: httpServer: type: Cybus::Server::Http properties: basePath: /cybustest postRoute: type: Cybus::Node::Http properties: parent: !ref httpServer method: POST route: /postRoute putRoute: type: Cybus::Node::Http properties: parent: !ref httpServer method: PUT route: /putRoute getRoute: type: Cybus::Node::Http properties: parent: !ref httpServer method: GET route: /getRoute httpMapping: type: Cybus::Mapping properties: mappings: - subscribe: endpoint: !ref postRoute publish: topic: output/postroute - subscribe: endpoint: !ref putRoute publish: topic: output/putroute - subscribe: topic: input/getRoute publish: endpoint: !ref getRoute ``` {% endcode %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.cybus.io/2-4-0/connectors/servers/http-server.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.