Gateway Management API

Jan 1 2022 at 12:00 AM

APIs within the Gateway Management API

The Raptor™ gateway environment APIs, responsible for the manipulation and management of the driver services and core services.

APIs within the Gateway Management API

CertificateManagement

Controller for handling API calls for Raptor™ certificates.

API Calls

Online

Check if the Certificate Management Controller is online

Permission

No permission check

URL

https://community-vraptor.iotnxt.io/api/CertificateManagement/Online

URL Params

none

Data Params

none

Success Response

200 - Success

{
  "isError": false,
  "subResponses": []
}

Notes

None

RetrieveTrustedCertificates

Retrieve a list of all currently active trusted certificates issued by the Raptor™.

Permission

Bearer or API Key required

URL

https://community-vraptor.iotnxt.io/api/CertificateManagement/RetrieveTrustedCertificates

URL Params

none

Data Params

none

Success Response

200 - The trusted Raptor™ certificate results are in the response body.

{
  "Result": [
    {
      "SubjectName": "testservice.IoTnxt.io",
      "Domain": "domain",
      "DateIssued": "2020-08-28T04:54:02.2539121Z",
      "PublicKey": "key",
      "PrivateKey": "key",
      "ExpiresOn": "2024-08-28T04:54:02.2539175Z",
      "CertificateType": "type",
      "Password": "pass",
      "ServiceId": "testservice",
      "Issuer": "IoTnxt.io",
      "DigitalSignature": "signature"
    }
  ],
  "IsError": false,
  "SubResponses": []
}

Notes

None

UploadTrustedCertificate

Upload a Raptor™ trusted certificate and deploy it.

Permission

Bearer or API Key required

URL

https://community-vraptor.iotnxt.io/api/CertificateManagement/UploadTrustedCertificate

URL Params

none

Data Params

{
  "Domain": "domain",
  "CertificateType": "type",
  "PublicKey": "key",
  "PrivateKey": "key"
}

Success Response

200 - The uploaded certificate details are in the response body.

{
  "SubjectName": "serviceid.domain",
  "Domain": "domain",
  "DateIssued": "2020-08-28T04:54:02.4724297Z",
  "PublicKey": "key",
  "PrivateKey": "key",
  "ExpiresOn": "2022-08-28T04:54:02.4724229Z",
  "CertificateType": "type",
  "Password": "pass",
  "ServiceId": "serviceid",
  "Issuer": "iot",
  "DigitalSignature": "signature",
  "IsError": false,
  "SubResponses": []
}

Notes

None

RetrieveCaCertificates

Retrieves all the certificates for the Raptor™ Certificate Authority.

Permission

Bearer or API Key required

URL

https://community-vraptor.iotnxt.io/api/CertificateManagement/RetrieveCaCertificates

URL Params

none

Data Params

none

Success Response

200 - The trusted Raptor™ certificate results are in the response body.

{
  "RootCa": "Root CA",
  "RootCaContent": "crt",
  "SigningCa": "Signing CA",
  "SigningCaContent": "crt",
  "IsError": false,
  "SubResponses": []
}

Notes

None

GenerateCertificate

Generate a certificate issued by the Raptor™ and deploy it.

Permission

Bearer or API Key required

URL

https://community-vraptor.iotnxt.io/api/CertificateManagement/GenerateCertificate

URL Params

none

Data Params

{
  "ServiceId": "serviceid"
}

Success Response

200 - The generated certificate details are in the response body.

{
  "SubjectName": "serviceid.domain",
  "Domain": "domain",
  "DateIssued": "2020-08-28T04:54:02.5185851Z",
  "PublicKey": "key",
  "PrivateKey": "key",
  "ExpiresOn": "2021-08-28T04:54:02.5185865Z",
  "CertificateType": "type",
  "Password": "pass",
  "ServiceId": "serviceid",
  "Issuer": "iotnxt",
  "DigitalSignature": "signature",
  "IsError": false,
  "SubResponses": []
}

Notes

None

RetrieveClientCertificates

Retrieve all currently active certificates issued by the Raptor™ for clients.

Permission

Bearer or API Key required

URL

https://community-vraptor.iotnxt.io/api/CertificateManagement/RetrieveClientCertificates

URL Params

none

Data Params

none

Success Response

200 - The raptor client certificates results are in the response body.

{
  "Result": [
    {
      "SubjectName": "serviceid.domain",
      "Domain": "domain",
      "DateIssued": "2020-08-28T04:54:02.5345664Z",
      "PublicKey": "key",
      "PrivateKey": "key",
      "ExpiresOn": "2024-08-28T04:54:02.5345678Z",
      "CertificateType": "type",
      "Password": "pass",
      "ServiceId": "serviceid",
      "Issuer": "iot",
      "DigitalSignature": "signature"
    }
  ],
  "IsError": false,
  "SubResponses": []
}

Notes

None

RenewCertificates

Renew Raptor™ certificate(s) and deploy updates.

Permission

Bearer or API Key required

URL

https://community-vraptor.iotnxt.io/api/CertificateManagement/RenewCertificates

URL Params

none

Data Params

{
  "services": [
    "string"
  ]
}

Success Response

200 - Success

{
  "Result": [
    {
      "SubjectName": "serviceid.domain",
      "Domain": "domain",
      "DateIssued": "2020-08-28T04:54:02.5869709Z",
      "PublicKey": "key",
      "PrivateKey": "key",
      "ExpiresOn": "2024-08-28T04:54:02.5869725Z",
      "CertificateType": "type",
      "Password": "pass",
      "ServiceId": "serviceid",
      "Issuer": "iot",
      "DigitalSignature": "signature"
    }
  ],
  "IsError": false,
  "SubResponses": []
}

Notes

None

RevokeCertificates

Revoke Raptor™ certificate(s) and deploy updates.

Permission

Bearer or API Key required

URL

https://community-vraptor.iotnxt.io/api/CertificateManagement/RevokeCertificates

URL Params

none

Data Params

{
  "services": [
    "string"
  ]
}

Success Response

200 - Success

{
  "Result": [
    "serviceid"
  ],
  "IsError": false,
  "SubResponses": []
}

Notes

None

DeviceManagement

Defines the routes for a device management controller

API Calls

Online

Check if the Device Management Controller is online.

Permission

No permission check

URL

https://community-vraptor.iotnxt.io/api/DeviceManagement/Online

URL Params

none

Data Params

none

Success Response

200 - Success

{
  "isError": false,
  "subResponses": []
}

Notes

None

RetrieveServiceInfo

Retrieve a list of services and their device interfaces.

Permission

Bearer or API Key required

URL

https://community-vraptor.iotnxt.io/api/DeviceManagement/RetrieveServiceInfo

URL Params

none

Data Params

none

Success Response

200 - The service and device interfaces info are in the response body.

{
  "Services": [
    {
      "ServiceName": "serviceId",
      "ServiceDescription": "service descriptions",
      "LastUpdateUtc": "2020-08-28T04:54:02.7123873Z",
      "IconData": "some base 64 string",
      "Enabled": true,
      "HasErrors": false,
      "Devices": [
        {
          "ServiceName": "serviceid",
          "DeviceName": "device_name",
          "Enabled": true,
          "DisplayIcon": "some base 64 string",
          "LastChangedUtc": "2020-08-28T04:54:02.7123906Z"
        }
      ]
    }
  ],
  "IsError": false,
  "SubResponses": []
}

Notes

None

RetrieveConnectionInfo

Retrieve a list of services with their connection info such as ports, Urls and whether they are exposed.

Permission

Bearer or API Key required

URL

https://community-vraptor.iotnxt.io/api/DeviceManagement/RetrieveConnectionInfo

URL Params

none

Data Params

none

Success Response

200 - The services connection info are in the response body.

{
  "Services": {
    "serviceid": {
      "Ports": [
        {
          "InternalUrl": "https://serviceid.domain:6000",
          "ServiceName": "serviceid",
          "PortNumber": 6000,
          "Protocol": "Tcp",
          "IsExposed": false,
          "IsDevicePort": false
        },
        {
          "InternalUrl": "https://serviceid.domain:8000",
          "ExternalUrl": "https://serviceid.domain:8001",
          "ServiceName": "serviceid",
          "PortNumber": 800,
          "Protocol": "Tcp",
          "IsExposed": true,
          "IsDevicePort": false
        },
        {
          "InternalUrl": "https://serviceid.domain:14684",
          "ExternalUrl": "https://serviceid.domain:8002",
          "ServiceName": "serviceid",
          "PortNumber": 14684,
          "Protocol": "Tcp",
          "IsExposed": true,
          "IsDevicePort": true
        }
      ]
    }
  },
  "IsError": false,
  "SubResponses": []
}

Notes

None

DeleteService

Delete a service.

Permission

Bearer or API Key required

URL

https://community-vraptor.iotnxt.io/api/DeviceManagement/DeleteService

URL Params

none

Data Params

{
  "ServiceName": "serviceid"
}

Success Response

200 - The deletion result info is in the response body.

{
  "ServiceName": "serviceid",
  "Result": true,
  "IsError": false,
  "SubResponses": []
}

Notes

None

ToggleService

Toggle a service. (Off or On)

Permission

Bearer or API Key required

URL

https://community-vraptor.iotnxt.io/api/DeviceManagement/ToggleService

URL Params

none

Data Params

{
  "ServiceName": "serviceid",
  "State": true
}

Success Response

200 - The service toggle result info are in the response body.

{
  "ServiceName": "serviceid",
  "Result": true,
  "IsError": false,
  "SubResponses": []
}

Notes

None

DeleteDevice

Delete a device interface.

Permission

Bearer or API Key required

URL

https://community-vraptor.iotnxt.io/api/DeviceManagement/DeleteDevice

URL Params

none

Data Params

{
  "ServiceName": "serviceid",
  "DeviceName": "devicename"
}

Success Response

200 - The device interface deletion result info are in the response body.

{
  "ServiceName": "serviceid",
  "DeviceName": "devicename",
  "Result": true,
  "IsError": false,
  "SubResponses": []
}

Notes

None

ToggleDevice

Toggle a device interface. (Off or On)

Permission

Bearer or API Key required

URL

https://community-vraptor.iotnxt.io/api/DeviceManagement/ToggleDevice

URL Params

none

Data Params

{
  "ServiceName": "serviceid",
  "DeviceName": "devicename",
  "State": true
}

Success Response

200 - The service and device interfaces info are in the response body.

{
  "ServiceName": "serviceid",
  "DeviceName": "devicename",
  "Result": true,
  "IsError": false,
  "SubResponses": []
}

Notes

None

Deploy

Deploys a service with configuration.

Permission

Bearer or API Key required

URL

https://community-vraptor.iotnxt.io/api/DeviceManagement/Deploy

URL Params

none

Data Params

{
  "DriverConfig": {
    "Type": "ConfigSection",
    "Data": {
      "ConfigFileName.json": "stringified json"
    }
  },
  "ServiceInfo": {
    "Type": "ServiceSection",
    "ServiceName": "serviceid",
    "Description": "Description of service",
    "ServiceType": "servicetype",
    "PackageId": "NuGet_package_id",
    "RequiresAuthentication": true
  },
  "Interfaces": {
    "Type": "DeviceInterfaceSection",
    "DeviceConfigFile": "ConfigFileName.json",
    "RootPath": "root_json_path_to_device",
    "Devices": [
      {
        "DeviceName": "devicename",
        "Icon": "base64icon",
        "CertificatePublicKeyPath": "json_path_to_publickey_field_inside_device",
        "CertificatePrivateKeyPath": "json_path_to_privatekey_field_inside_device",
        "CertificatePfxPath": "json_path_to_pfx_field_inside_device",
        "CertificatePassPath": "json_path_to_pass_field_inside_device",
        "CertificateType": "Rsa/Ec",
        "RequiresCertificate": true,
        "CertificateFormat": "PEM/PFX"
      }
    ],
    "RemoveMissing": true
  },
  "DevicePorts": {
    "Type": "DevicePortsSection",
    "Ports": [
      {
        "DeviceName": "devicename",
        "Protocol": "Tcp",
        "UsageContext": "Other",
        "Scheme": "https",
        "PortNumber": 8000,
        "IngressPortNumber": 8001,
        "IsPublic": true
      }
    ],
    "RemoveMissing": true
  }
}

Success Response

200 - The resulting deployment info are in the response body.

{
  "Results": [
    {
      "Name": "Deployment Step",
      "IsHandled": true,
      "IsSuccessful": true,
      "Message": "Deployment step to deploy driver",
      "LogEntries": [
        "Started",
        "Busy",
        "Finished"
      ]
    }
  ],
  "IsError": false,
  "SubResponses": []
}

Notes

None

RetrieveConfig

Retrieve a service with it's config.

Permission

Bearer or API Key required

URL

https://community-vraptor.iotnxt.io/api/DeviceManagement/RetrieveConfig

URL Params

none

Data Params

{
  "ServiceName": "serviceid",
  "DeviceName": "devicename"
}

Success Response

200 - The service and config info are in the response body.

{
  "Result": {
    "DriverConfig": {
      "Type": "ConfigSection",
      "Data": {
        "ConfigFileName.json": "stringified json"
      }
    },
    "ServiceInfo": {
      "Type": "ServiceSection",
      "ServiceName": "serviceid",
      "Description": "Description of service",
      "ServiceType": "servicetype",
      "PackageId": "NuGet_package_id",
      "RequiresAuthentication": true
    },
    "Interfaces": {
      "Type": "DeviceInterfaceSection",
      "DeviceConfigFile": "ConfigFileName.json",
      "RootPath": "root_json_path_to_device",
      "Devices": [
        {
          "DeviceName": "devicename",
          "Icon": "base64icon",
          "CertificatePublicKeyPath": "json_path_to_publickey_field_inside_device",
          "CertificatePrivateKeyPath": "json_path_to_privatekey_field_inside_device",
          "CertificatePfxPath": "json_path_to_pfx_field_inside_device",
          "CertificatePassPath": "json_path_to_pass_field_inside_device",
          "CertificateType": "Rsa/Ec",
          "RequiresCertificate": true,
          "CertificateFormat": "PEM/PFX"
        }
      ],
      "RemoveMissing": true
    },
    "DevicePorts": {
      "Type": "DevicePortsSection",
      "Ports": [
        {
          "DeviceName": "devicename",
          "Protocol": "Tcp",
          "UsageContext": "Other",
          "Scheme": "https",
          "PortNumber": 8000,
          "IngressPortNumber": 8001,
          "IsPublic": true
        }
      ],
      "RemoveMissing": true
    }
  },
  "IsError": false,
  "SubResponses": []
}

Notes

None

TogglePort

Toggle a port.(Exposing or un-exposing on the ingress)

Permission

Bearer or API Key required

URL

https://community-vraptor.iotnxt.io/api/DeviceManagement/TogglePort

URL Params

none

Data Params

{
  "ServiceName": "serviceid",
  "PortNumber": 8001,
  "Protocol": "Tcp",
  "State": true
}

Success Response

200 - The toggle result info is in the response body.

{
  "ServiceName": "serviceid",
  "PortNumber": 8001,
  "Protocol": "Tcp",
  "Result": true,
  "IsError": false,
  "SubResponses": []
}

Notes

None

DevOpsManagement

Controller for handling API calls for Raptor™ DevOps Management.

API Calls

Online

Check if the DevOps Management Controller is online

Permission

No permission check

URL

https://community-vraptor.iotnxt.io/api/DevOpsManagement/Online

URL Params

none

Data Params

none

Success Response

200 - Success

{
  "isError": false,
  "subResponses": []
}

Notes

None

UpdateServiceContainer

Request to update or rollback a container to a specific container name.

Permission

Bearer or API Key required

URL

https://community-vraptor.iotnxt.io/api/DevOpsManagement/UpdateServiceContainer

URL Params

none

Data Params

Request body deserialized.

{
  "ServiceName": "collector",
  "ContainerName": "yourcontainerregistry.containername:4.0.1.1",
  "RunCommand": "dotnet collector.service.dll",
  "RunCommandArguments": [
    "arg1"
  ]
}

Success Response

200 - The result of the update is in the response body.

{
  "Result": true,
  "IsError": false,
  "SubResponses": []
}

Notes

None

RestartServices

Request to restart either a single service, a list of services or all services.

Permission

Bearer or API Key required

URL

https://community-vraptor.iotnxt.io/api/DevOpsManagement/RestartServices

URL Params

none

Data Params

A request object containing the services names to restart or if to restart all services.

{
  "RestartAll": false,
  "Services": [
    "collector"
  ]
}

Success Response

200 - Returns a key-value pair of service names and the result of their restart requests.

{
  "Result": {
    "collector": true
  },
  "IsError": false,
  "SubResponses": []
}

Notes

None

UpdateRawServiceConfig

Request to update a service's configs.

Permission

Bearer or API Key required

URL

https://community-vraptor.iotnxt.io/api/DevOpsManagement/UpdateRawServiceConfig

URL Params

none

Data Params

A request object containing the service’s name, whether to overwrite existing configs and a list of configs to update.

{
  "ServiceName": "collector",
  "ServiceConfigs": {
    "DataProtectionOptions.json": "{\"DataProtectionOptions\":{\"AllowInvalidCrl\":true,\"CertificateSubjectName\":\"collector.dev-vraptor\"}}",
    "IdentityClientOptions.json": "{\r\n  \"IdentityClientOptions\": {\r\n    \"IdentityServiceURL\": \"https://identity.dev-vraptor:8000\",\r\n    \"APIName\": \"RaptorRPC\",\r\n    \"EnableAspAuthentication\": true\r\n  }\r\n}"
  }
}

Success Response

200 - Returns the result of the service config update.

{
  "Result": true,
  "IsError": false,
  "SubResponses": []
}

Notes

None

FetchServices

Request to retrieve a collection of services currently deployed.

Permission

Bearer or API Key required

URL

https://community-vraptor.iotnxt.io/api/DevOpsManagement/FetchServices

URL Params

none

Data Params

Always specify what you are selecting: either a wildcard “*” for all service/type or specifically “mqtt” for the specific service/type.

Any service/type with “!” in front will be excluded regardless if you specified you want it.

{
  "ServiceTypeFilter": [
 "*",
 "!core"
  ],
  "ServiceNameFilter": [
 "*",
 "!mqtt",
 "!netclient"
  ]
}

Success Response

200 - Returns a list of services with a service overview.

{
  "Services": [
    {
      "ServiceName": "collector",
      "Status": true
    },
    {
      "ServiceName": "identity",
      "Status": false
    },
    {
      "ServiceName": "cloud",
      "Status": true
    },
    {
      "ServiceName": "deployment",
      "Status": false
    }
  ],
  "IsError": false,
  "SubResponses": []
}

Notes

None

Graphs

API Calls

metricsGraphs

Permission

No permissions check

URL

https://community-vraptor.iotnxt.io/metricsGraphs

URL Params

none

Data Params

none

Success Response

200 - A response containing the list of Devices

none

Notes

None

updateData

Permission

No permissions check

URL

https://community-vraptor.iotnxt.io/metricsGraphs/updateData

URL Params

none

Data Params

none

Success Response

200 - A response containing the list of Devices

none

Notes

None

Gateway Management API

APIs within the Gateway Management API

CertificateManagement

API Calls

DeviceManagement

API Calls

DevOpsManagement

API Calls

Graphs

API Calls

Continue reading

Community

Questions

Website