# 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. ## Permissions User access and authentication can be configured using the existing connectware functionalities for HTTP permissions, see [Roles](https://docs.cybus.io/documentation/user-management/roles) and [Permissions](https://docs.cybus.io/documentation/user-management/permissions). 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, e.g. `data/cybustest/#` or `data/+/postRoute`. ## Service Commissioning File Specifics [Custom Server Properties](https://docs.cybus.io/connectors/servers/http-server/httpserver) [Custom Node Properties](https://docs.cybus.io/connectors/servers/http-server/httpnode) ### Sending Data to the HTTP Server #### JSON If the server receives a messages with the header `Content-type=application/json`, it will parse the HTTP message body in JSON format, then transform the content into the internal message convention where the message body is in the `value` property. Example: {% code lineNumbers="true" %} ```yaml // Original message sent to HTTP server { "machineState": "okay", "temperature": 23, "logs": [ "message1", "message2" ] } // Resulting protocol-mapper output at the MQTT broker { "timestamp": 12391238123, // milliseconds since epoch "value": { "machineState": "okay", "temperature": 23, "logs": [ "message1", "message2" ] } } ``` {% endcode %} If the request sent to the server is not parseable as JSON, it will be dropped and not forwarded 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 HTTP message body is forwarded to the specified topic without any further modification (no *timestamp*, no *value* property). ### Receiving Data from the HTTP Server #### JSON Each Node with `method = GET` has an internal cache, which will store any date written to it using the `*/write` topic. The cache has a depth of 1, so only the latest data is being stored. Data will always be in the format of a JSON object containing *value* and *timestamp*. If no *timestamp* is provided, one will be generated. If no data is available, the server will respond with status of *204*. {% code lineNumbers="true" %} ```yaml // Original message sent to MQTT broker { "value": "Cybus" } // Resulting protocol-mapper output at the MQTT broker { "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. It is assumed that Connectware is configured so that the data route is accessible by *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" %} ```yaml curl --location --request POST 'https://my.connectwareurl.com/data/cybustest/postRoute' \ --header 'Authorization: Basic ' \ --header 'Content-Type: application/json' \ --data-raw '{ "test1": "testdata send via POST Route" }' ``` {% endcode %} The PUT based demo endpoint: {% code lineNumbers="true" %} ```yaml curl --location --request PUT 'https://my.connectwareurl.com/data/cybustest/putRoute' \ --header 'Authorization: Basic ' \ --header 'Content-Type: application/json' \ --data-raw '{ "test2": "testdata send via PUT Route" }' ``` {% endcode %} The GET based demo endpoint: {% code lineNumbers="true" %} ```yaml curl --location --request GET 'https://my.connectwareurl.com/data/cybustest/getRoute' \ --header 'Authorization: Basic ' ``` {% endcode %} {% file src="" %} {% code title="http-server-example.yml" lineNumbers="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/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.