Generic HTTP - Communication Profile

This page describes the Generic HTTP Communication Profile (CP), which templates an unsecure request-response based network communication using the Hypertext Transfer Protocol.

Characteristics

Overview
ID	generic_http
Transfer protocol	HTTP 1.1
Data Encryption	N/A
Data Compression	N/A
Payload Format	JSON / Text

Service Interface Template

This section lists the interface properties that are necessarry to apply the Generic HTTP - CP as Service interface and that Interface Design Descriptions (IDD) and/or the service registration should include.

Access Address List

List of unique identifiers assigned to the same device or node on a network where the given Service is hosted from. An access address can be a hostname, an IPv4 address or an IPv6 address. It is mandatory to publish them (at least one) in the Local Cloud.

Access Port

A numerical identifier within a device or node on a network where the given Service can be accessed. Valid port number range is 1-65535. It is mandatory to publish it in the Local Cloud.

Base Path

The root URL segment that serves as a common prefix for a given Service that goups a set of service-operations (endpoints). It is mandatory to specify it in IDDs and to publish in the Local Cloud.

Operations

Set of endpoints, each of them is performing some kind of action related to the given Service. An operation constists of a method and a path. It is mandatory to specify them in IDDs and is optional to publish in the Local Cloud.

Method

An HTTP method, that applies to the given service-operation.

Path

The service-operation specific URL segment.

Authorization Header

HTTP Authorization request header with Bearer scheme must be used for providing identity or access related data if required in case of a given Service. It is mandatory to specify it in IDDs if authentication or access validation is required by a given service instance.

Identity

If requester identity is required to be proven, then an Identity Info or Identiy Token should be provided in this header. The exact Identity data to be provided is depending on the applied Authentication Policy.

Access

If the access right is required to be proven, then an Access Token should be provided in this header.

Payload

The data to be transmitted to or from a given service-operation (endpoint). In case of hierarchical data, the payload must be in JSON data format and must be placed into the HTTP Meassage Body. In case of non-hierarchical data, text data format can be used and placed into the HTTP Meassage Body or into the request URI as URI encoded path variable or query parameter. It is mandatory to specify it in IDDs.

Response Status

The HTTP Response Status that indicates the result of a service-operation. It is mandatory to specify it in IDDs.

Examples

Request

<METHOD> /<basepath>/<operation-path>/<path-variable>?<query-parameter-key>=<query-parameter-value> HTTP/1.1
Host: <access-address>:<access-port>
Accept: application/json
Authorization: Bearer <access-token>
Content-Type: application/json

<body>

POST /temperatureInfo/query-temperature/sensor-abc?scale=celsius HTTP/1.1
Host: 192.168.0.103:4132
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsI.eyJzdWIiOiIxMjM0NTY3ODkw.SflKxwRJSMeKKF2QT4fwpMeJ
Content-Type: application/json

{
    "from": "2025-02-01T00:00:00Z",
    "to": "2025-02-06T23:59:00Z",
    "moreThan": 12,
    "lessThan": 24
}

Response

HTTP/1.1 <STATUS>
Date: <response-date>
Content-Type: application/json; charset=UTF-8

<body>

HTTP/1.1 200 OK
Date: Wed, 07 Feb 2025 12:00:00 GMT
Content-Type: application/json; charset=UTF-8

[
    {
        "timestamp": "2025-02-03T12:31:00Z",
        "celsius": 13,
    },
    {
        "timestamp": "2025-02-05T12:10:00Z",
        "celsius": 14
    }
]