Node service RESTful API (20)

Download OpenAPI specification:Download

Perinet product openAPI definition of the basic node service. The basic node service is implemented by all perinet products.

NodeService

The generic Node Service, available on all Perinets products

NodeInfo object

Provides meta information for the node service. This includes various product information as manufacturer, serial number as well as product variant

Authorizations:
cookieAuthmTLS

Responses

Response samples

Content type
application/json
{
  • "api_version": "20",
  • "config": {
    },
  • "life_state": "PRODUCED",
  • "services": [
    ]
}

NodeConfig object

Authorizations:
cookieAuthmTLS

Responses

Response samples

Content type
application/json
{
  • "application_name": "StarterKitPlus-sernm",
  • "element_name": "distance"
}

NodeInfo Object. application_name only

Update designated properties of the NodeInfo object. Currently, only application_name will be accepted.

Authorizations:
cookieAuthmTLS
Request Body schema: application/json
application_name
string
Default: ""
element_name
string
Default: ""

Responses

Request samples

Content type
application/json
{
  • "application_name": "StarterKitPlus-sernm",
  • "element_name": "distance"
}

Production Info Object

Provides meta information of the product, which are set during production. I.e. manufacturer, serial number, production batch identifier.

Authorizations:
cookieAuthmTLS

Responses

Response samples

Content type
application/json
{
  • "manufacturer": "Perinet GmbH",
  • "mpn": "PRN.000.001",
  • "serial_number": "sernm",
  • "product_version": "7",
  • "product_variant": "distance",
  • "batch_number": "2020-47",
  • "product_name": "periCORE",
  • "hostname": "periCORE-sernm"
}

Production Info Object

Set production information of the product. I.e. manufacturer, serial number, production batch identifier.

Authorizations:
cookieAuthmTLS
Request Body schema: application/json
manufacturer
string
mpn
string

Manufacturer Part Number

serial_number
string
product_version
string
product_variant
string
batch_number
string

Manufacturer production batch identification

product_name
string
hostname
string
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "manufacturer": "Perinet GmbH",
  • "mpn": "PRN.000.001",
  • "serial_number": "sernm",
  • "product_version": "7",
  • "product_variant": "distance",
  • "batch_number": "2020-47",
  • "product_name": "periCORE",
  • "hostname": "periCORE-sernm"
}

Services collection available

Provides a list of available services.

Authorizations:
cookieAuthmTLS

Responses

Response samples

Content type
application/json
[
  • "node",
  • "lifecycle",
  • "security",
  • "mqtt-client"
]

Service_Internal

Services collection available

Provides a list of available services.

Authorizations:
None
Request Body schema: application/json
Array
string

Responses

Request samples

Content type
application/json
[
  • "node",
  • "lifecycle",
  • "security",
  • "mqtt-client"
]

Update the Life state of a node

Provides a list of available element names.

Authorizations:
None
Request Body schema: application/json
string (NodeLifeState)
Enum: "PRODUCED" "UPDATED" "PRE_PRODUCED"
  • PRODUCED, is the OEM-manufacturer default state, as it left the manufacturing site
  • UPDATED, after any change. E.g. firmware update, configuration change
  • PRE_PRODUCED state, before the PRODUCED state. E.g. in this state changes to the production data are accepted. Note: The state PRE_PRODUCED is not recommended for end customers.

Responses

Request samples

Content type
application/json
"PRODUCED"

PEM encoded PublicCertificate info object

Provides an PEM encoded {certificate} info object for ().

Authorizations:
cookieAuthmTLS

Responses

PEM encoded private key object

Provides an PEM encoded private key paired to {certificate}.

Authorizations:
cookieAuthmTLS
path Parameters
certificate
required
string
Enum: "host_cert" "client_cert"

Certificates to authenticate the node.

Responses

SET Advertised DNS-SD Service Info object

Authorizations:
cookieAuthmTLS
path Parameters
service_name
required
string (DNSSDServiceName)
Example: _https._tcp

DNS-SD service name

Request Body schema: application/json
ttl
integer
Default: 300
port
number
Default: 443
hostname
string
Array of IPv6Address (string) or IPv4Address (string) (NetworkAddress)
object (DNSSDTXTRecord)

Responses

Request samples

Content type
application/json
{
  • "ttl": 300,
  • "port": 443,
  • "hostname": "periNODE-sernm.local",
  • "addresses": [
    ],
  • "txt_record": {
    }
}

DELETE Advertised DNS-SD Service Info object

Authorizations:
cookieAuthmTLS
path Parameters
service_name
required
string (DNSSDServiceName)
Example: _https._tcp

DNS-SD service name

Responses

SecurityService

Security Service

Client Security Login

Client login (with username password) to receive api_key for further acces.

Authorizations:
None
Request Body schema: application/json
username
string
Default: "admin"
password
string (SecurityAdminPassword)

Responses

Request samples

Content type
application/json
{
  • "username": "admin",
  • "password": "aB3d5s7ant"
}

Client Security Password

Change client login password.

Authorizations:
cookieAuthmTLS
Request Body schema: application/json
username
string
Default: "admin"
password
string (SecurityAdminPassword)

Responses

Request samples

Content type
application/json
{
  • "username": "admin",
  • "password": "aB3d5s7ant"
}

SecurityInfo object

Provides meta information of the security service.

Authorizations:
cookieAuthmTLS

Responses

Response samples

Content type
application/json
{
  • "api_version": "20",
  • "config": {
    }
}

SecurityConfig object

Provides meta information of the security configuration.

Authorizations:
cookieAuthmTLS

Responses

Response samples

Content type
application/json
{
  • "client_auth_method": "mTLS",
  • "minimal_level": "ENCRYPTED",
  • "credentials": [
    ]
}

Update Security Config

Change the security config.

Authorizations:
cookieAuthmTLS
Request Body schema: application/json
client_auth_method
string (SecurityAuthMethod)
Enum: "NONE" "mTLS" "API_KEY"

Defines a security scheme for client authentication. Specification

minimal_level
string (SecurityLevel)
Enum: "UNSECURED" "ENCRYPTED" "AUTHENTICATED" "ACCESS_CONTROLLED"

The security level enforced by the Perinet node.

  • UNSECURED: (Level-0) no connection encryption nor authentication of the remote entity
  • ENCRYPTED: (Level-1) TLS, but no verification of the authenticity of the remote entity. E.g. allow connection to an MQTTs broker without the verification of the server host certificate
  • AUTHENTICATED: (Level-2) TLS, with the verification of the authenticity of the remote entity. E.g. refuse connection to an MQTTs broker where the the verification of the server host certificate has failed
  • ACCESS_CONTROLLED: (Level-3) mTLS, same as AUTHENTICATED plus sending the client TLS certificate.
Array of objects (SecurityLoginCredentials)

Responses

Request samples

Content type
application/json
{
  • "client_auth_method": "mTLS",
  • "minimal_level": "ENCRYPTED",
  • "credentials": [
    ]
}

delete PEM encoded PublicCertificate

delete PEM encoded PublicCertificate

Authorizations:
cookieAuthmTLS
path Parameters
certificate
required
string
Enum: "host_cert" "client_cert"

Certificates to authenticate the node.

Responses

PEM encoded PublicCertificate info object

Provides an PEM encoded {certificate} info object for ().

Authorizations:
cookieAuthmTLS
path Parameters
certificate
required
string
Enum: "host_cert" "client_cert"

Certificates to authenticate the node.

Responses

exchange PEM encoded PublicCertificate

Stores a pem encoded certificate, including the private key if applicable

Authorizations:
cookieAuthmTLS
path Parameters
certificate
required
string
Enum: "host_cert" "client_cert"

Certificates to authenticate the node.

Request Body schema: application/x-pem-file
One of
string (PublicCertificate)

Responses

Collection of stored trust anchors

Authorizations:
cookieAuthmTLS

Responses

Response samples

Content type
application/json
[
  • "application_name",
  • "firmware_sign",
  • "perinet"
]

PEM encoded PublicCertificate info object

Provides an PEM encoded {certificate} info object for ().

Authorizations:
cookieAuthmTLS
path Parameters
trust_anchor
required
string

Certificates currently supported are, host_cert, root_ca_cert, client_cert, fw_ca_cert, default_host_cert.

Responses

exchange PEM encoded PublicCertificate

Stores a pem encoded certificate.

Authorizations:
cookieAuthmTLS
path Parameters
trust_anchor
required
string

Certificates currently supported are, host_cert, root_ca_cert, client_cert, fw_ca_cert, default_host_cert.

Request Body schema: application/x-pem-file
string (PublicCertificate)

Responses

Remove former stored trust anchor certificate

Remove a pem encoded certificate.

Authorizations:
cookieAuthmTLS
path Parameters
trust_anchor
required
string

Certificates currently supported are, host_cert, root_ca_cert, client_cert, fw_ca_cert, default_host_cert.

Responses

LifeCycleService

LifeCylce Service

LifeCycle Service meta information

Provides meta information on the lifeCycle service of a device.

Authorizations:
cookieAuthmTLS

Responses

Response samples

Content type
application/json
{
  • "api_version": "20",
  • "state": "PRODUCED"
}

Exchange the production firmware image

Update the production firmware image of the periNODE. NOTE: This function might conflict with the state of the periNODE. In the case of a periCORE based product, only with the periCORE firmware the update of the production firmware image is not in conflict with the product state. Please be refered to the product specific datasheet.

Authorizations:
cookieAuthmTLS
Request Body schema: application/vnd-perinet-fwimage
string <binary> (FirmwareImage)

A signed firmware image. The firmware image is a posix tar file. The order of the files is important. The first file has to be the certs.pem with the certificate chain used to sign the files, except the root CA itself. All other files are files are added with their signatures. The signatures have to be saved as files with the extension .sig.

Responses

exchange the firmware update image

Authorizations:
cookieAuthmTLS
Request Body schema: application/vnd-perinet-fwimage
string <binary> (FirmwareImage)

A signed firmware image. The firmware image is a posix tar file. The order of the files is important. The first file has to be the certs.pem with the certificate chain used to sign the files, except the root CA itself. All other files are files are added with their signatures. The signatures have to be saved as files with the extension .sig.

Responses

perform a soft reboot

The device reboot process is invoked.

Authorizations:
cookieAuthmTLS
Request Body schema: */*

Empty body

any

Responses

factory reset

Restores the factory default settings of the device.

Authorizations:
cookieAuthmTLS
Request Body schema: */*

Empty body

any

Responses

DNS-SD Service

The DNS Service Discovery service can be used to discover remote network services or advertise local services to the network. Services are discovered via the IPv6 mDNS broadcast protocol, which reaches services in the link local domain only. Means, it will not discover services beyond a routing node.

NOTE: The service discovery feature must be initiated via the API and times out after 30s

Get DNS-SD Service Info object

Provides meta information of the DNS-SD service.

Authorizations:
cookieAuthmTLS

Responses

Response samples

Content type
application/json
{
  • "api_version": "20",
  • "services": [
    ]
}

GET Advertised DNS-SD Services

A list of names of the advertised dns-sd services from the node.

Authorizations:
cookieAuthmTLS

Responses

Response samples

Content type
application/json
[
  • "_https._tcp",
  • "_mbaps._tcp"
]

GET Advertised DNS-SD Service Info object

Authorizations:
cookieAuthmTLS
path Parameters
service_name
required
string (DNSSDServiceName)
Example: _https._tcp

DNS-SD service name

Responses

Response samples

Content type
application/json
{
  • "domain": "local.",
  • "priority": 0,
  • "weight": 0,
  • "ttl": 300,
  • "port": 443,
  • "hostname": "periNODE-sernm.local",
  • "addresses": [
    ],
  • "txt_record": {
    }
}

Start Discovery of DNS-SD Service Type

Start mDNS / DNS-SD service browsing for topic {service_name}. The browsing will stop after a timeout of 30 seconds and the resource will be deleted. Another call before the timeout exceeds, will extend the timeout to 30 seconds.

Authorizations:
cookieAuthmTLS
Request Body schema: application/json
service_name
string (DNSSDServiceName)

DNS label pair according to rfc6763.

Responses

Request samples

Content type
application/json
{
  • "service_name": "_https._tcp"
}

Response samples

Content type
application/json
{
  • "id": "89de59aa-6211-41d7-a890-d3e6bb65c656"
}

GET Discovered DNS-SD Service Type Info objects

Get list of found services for {id}. The browsing have to be started first with DNSSDServiceInfoDiscoverSet and the request have to be send before the timeout exceed.

Authorizations:
cookieAuthmTLS
path Parameters
id
required
string (DNSSDBrowseID)
Example: 89de59aa-6211-41d7-a890-d3e6bb65c656

UUIDv4 or similar

Responses

Response samples

Content type
application/json
[
  • {
    }
]

PKI2goService

PKI2go Service implement the security management

PKI2goInfo object

Provides meta information of the pki configuration.

Authorizations:
cookieAuthmTLS

Responses

Response samples

Content type
application/json
{
  • "application_name": "app_test",
  • "auto_renew_certificates": true
}

PKI2goConfig object

Provides PKI2go configuration.

Authorizations:
cookieAuthmTLS

Responses

Response samples

Content type
application/json
{
  • "application_name": "app_test",
  • "auto_renew_certificates": true
}

PKI2goConfig object

Provides meta information of the pki configuration.

Authorizations:
cookieAuthmTLS
Request Body schema: application/json
[application_name]
required
string
[auto_renew_certificates]
required
boolean

Responses

Request samples

Content type
application/json
{
  • "application_name": "app_test",
  • "auto_renew_certificates": true
}

PKI2goHosts object

Return a list of hosts that is included in the PKI2go.

Authorizations:
cookieAuthmTLS

Responses

Response samples

Content type
application/json
"periNODE-serno"

PKI2goHosts object

Add new Host to the PKI2go application.

Authorizations:
cookieAuthmTLS
Request Body schema: application/json
string (PKI2goHostname)

Hostname or the Common Name(CN) of the entity.

Responses

Request samples

Content type
application/json
"periNODE-serno"

PKI2goHosts object

Delete Host to the PKI2go application. Revoke the host certificate.

Authorizations:
cookieAuthmTLS
Request Body schema: application/json
Array
string (PKI2goHostname)

Hostname or the Common Name(CN) of the entity.

Responses

Request samples

Content type
application/json
[
  • "periNODE-serno, periMICA-serno"
]

PKI2goUsers object

Return a list of users that is included in the PKI.

Authorizations:
cookieAuthmTLS

Responses

Response samples

Content type
application/json
[
  • "user1, user2"
]

PKI2goUsers object

Add new User to the PKI2go application.

Authorizations:
cookieAuthmTLS
Request Body schema: application/json
[username]
required
any
[role]
required
any

Responses

Request samples

Content type
application/json
{ }

PKI2goUsers object

Delete User to the PKI2go application. Revoke the user certificate.

Authorizations:
cookieAuthmTLS
Request Body schema: application/json
[username]
required
any
[role]
required
any

Responses

Request samples

Content type
application/json
{ }

PKI2go_Info_Set

Provides meta information of the pki configuration.

Authorizations:
cookieAuthmTLS

Responses

PKI2go_Certificate_Get

Provides certificate to a specific common name.

Authorizations:
cookieAuthmTLS

Responses

PKI2goClientCertificateRequest object

Return the list of client certificate requests.

Authorizations:
cookieAuthmTLS

Responses

PKI2goClientCertificateRequest object

Add client certificate request.

Authorizations:
cookieAuthmTLS
Request Body schema: application/json
[RequestID]
required
string
[User]
required
any
[PasswordP12]
string

Responses

Request samples

Content type
application/json
{ }

PKI2go_Client_Certificate_Request_Status_Get

Provides the status of a client certificate request.

Authorizations:
cookieAuthmTLS

Responses

PKI2goClientCertificateRequest object

Add client certificate request.

Authorizations:
cookieAuthmTLS
Request Body schema: application/json
[RequestID]
required
string
[User]
required
any
[PasswordP12]
string

Responses

Request samples

Content type
application/json
{ }