Edge Core API

Edge Core API

The Edge Core API allows users to interact with the system utilizing the same underlying functionality as Edge Manager or the Predix Technician Edge Console (PETC). The API is accessible from inside the device when logged into a terminal via a Unix domain socket. The API can be used for development purposes to manage applications, configure the network, perform host updates, retrieve logs, etc.

The API is not accessible from outside the device and is subject to change in future releases.

Applications

Info

Gets details about the specified application.

GET

http://localhost/api/v1/applications/<app_name>
Curl example
curl http://localhost/api/v1/applications/my-app \
    --unix-socket /var/run/edge-core/edge-core.sock
Success response example
{
    "container_app_info": {
        "application": {
            "name": "my-app",
            "service": [
                {
                    "current_state": "Running 24 hours ago",
                    "desired_state": "Running",
                    "error_message": "",
                    "id": "fuz7x5vjru8w1li11fhgcixuu",
                    "image": "eh-server",
                    "name": "my-app_app2.1"
                },
                {
                    "current_state": "Running 24 hours ago",
                    "desired_state": "Running",
                    "error_message": "",
                    "id": "aiznk23c3mfpi7ltbk54hx5yp",
                    "image": "ds-server",
                    "name": "my-app_app1.1"
                }
            ],
            "version": ""
        }
    },
    "platform_name": "Docker",
    "platform_version": "Docker version 17.05.0-ce, build 89658be"
}
Unsuccessful response example
{
    "error_message": "application not found: my-appx",
    "status_code": 400
}

Delete

Deletes a deployed application.

DELETE

http://localhost/api/v1/applications/<app_name>
Table 1. Paramater
FieldTypeDescription
app_nameStringApplication name
Curl example
curl http://localhost/api/v1/applications/my-app \
    --unix-socket /var/run/edge-core/edge-core.sock \
    -X DELETE
Table 2. Error 4xx
NameTypeDescription
error_messageStringA description of the error encountered
status_codeNumberStatus code for the HTTP request
Error response example
{
    "error_message": "<errorMessage>",
    "status_code": 400
}

Deploy Configuration

Deploys the configuration of an application.

POST

http://localhost/api/v1/applications/<app_name>/configuration
Table 3. Parameters
FieldTypeDescription
app_nameStringApplication name
fileStringApplication configuration file
Curl example
curl http://localhost/api/v1/applications/my-app/configuration \
    --unix-socket /var/run/edge-core/edge-core.sock \
    -X POST \
    -F "[email protected]/mnt/data/downloads/my-app-config.zip"
Success response example
{
    "app_config_deploy": "App configuration deployment successful."
}
Error response example
{
  "error_message": "Application with id my-app does not exist.
   Unable to deploy configs.",
  "status_code": 400
}

Deploy Application

Deploys an application

POST

http://localhost/api/v1/applications
Table 4. Parameters
FieldTypeDescription
app_nameStringApplication name
file_nameStringName of the application deployment file
Curl example
curl http://localhost/api/v1/applications \
    --unix-socket /var/run/edge-core/edge-core.sock \
    -X POST \
    -F "[email protected]<file_name>" \
    -H "app_name: my_app"
Success response example
{
    "app_deploy": "Application deployment successful."
}
Error response example
{
  "error_message": "gzip: stdin: unexpected end of file tar:
   Child returned status 1 tar: Error is not recoverable:
   exiting now",
  "status_code": 400
}

Get List

Gets a list of applications.

GET

http://localhost/api/v1/applications
Curl example
curl http://localhost/api/v1/applications \
    --unix-socket /var/run/edge-core/edge-core.sock
Success response example
{
    "applications": [
        "my-app",
        "web-server",
        "database"
    ]
}
Table 5. Error 4xx
FieldTypeDescription
error_messageStringA description of the error encountered
status_codeNumberStatus code for the HTTP request
Error response example
{
    "error_message": "<errorMessage>",
    "status_code": 400
}

Start an Application

Starts an application.

POST

http://localhost/api/v1/applications/<app_name>/start
Table 6. Parameter
FieldTypeDescription
app_nameStringApplication name
Curl example
curl http://localhost/api/v1/applications/my-app/start \
    --unix-socket /var/run/edge-core/edge-core.sock \
    -X POST
Table 7. Error 4xx
FieldTypeDescription
error_messageStringA description of the error encountered
status_codeNumberStatus code for the HTTP request
Error response example
{
    "error_message": "<errorMessage>",
    "status_code": 400
}

Stop an Application

Stops an application.

POST

http://localhost/api/v1/applications/<app_name>/stop
Table 8. Parameter
FieldTypeDescription
app_nameStringApplication name
Curl example
curl http://localhost/api/v1/applications/my-app/stop \
    --unix-socket /var/run/edge-core/edge-core.sock \
    -X POST
Table 9. Error 4xx
FieldTypeDescription
error_messageStringA description of the error encountered
status_codeNumberStatus code for the HTTP request
Error response example
{
    "error_message": "<errorMessage>",
    "status_code": 400
}

Device

Get OS Info

Gets the OS information of the device.

GET

http://localhost/api/v1/host/os
Curl example
curl --unix-socket /var/run/edge-core/edge-core.sock \
     http://localhost/api/v1/host/os
Table 10. Success 200
FieldTypeDescription
os_nameStringOS name
os_versionStringOS version
os_archStringOS architecture
Success response example
{
    "os_name": "Edge OS",
    "os_version": "2.0.0-beta.8",
    "os_arch": "x86_64"
}

Get Update State

Gets the state of an update.

State is kept for the most recent update attempt, so querying with an older update_identifier will return “NO UPGRADE OCCURRED”. Note: update_identifier is required because there is a brief lag between the start of an update and the actual upgrade process running. So if a client starts an update and then immediately tries to get the ‘state’ before the upgrade process has started, without the id they would get the state of the previous update, an incorrect result.

GET

http://localhost/api/v1/host/state?update_identifier=<identifier>
Table 11. Parameter
FieldTypeDescription
update_identifierStringIdentifier of the update
Curl example
curl --unix-socket /var/run/edge-core/edge-core.sock \
    http://localhost/api/v1/host/state?update_identifier=<identifier>
Table 12. Success 200
FieldTypeDescription
last_os_upgradeStringState of the update associated with the identifier: "PASS", "FAIL", INPROGRESS" or "NO UPGRADE OCCURRED"
Success response example
{
    "last_os_upgrade": "PASS"
}

Reboot

Reboots the device.

POST

http://localhost/api/v1/host/reboot
Curl example
curl --unix-socket /var/run/edge-core/edge-core.sock \
     -X POST http://localhost/api/v1/host/reboot

Upon successful completion of the operation, the box will reboot.

Update

Updates the Predix Edge OS and Edge Agent.

POST

http://localhost/api/v1/host/update
Table 13. Parameters
FieldTypeDescription
update_identifierStringAn identifier associated with the update. Can be any string, as long as it is unique.
file_nameStringName of the Predix Edge OS/Edge Agent update image file.
Curl example
curl --unix-socket /var/run/edge-core/edge-core.sock \
     -X POST -H "update_identifier: <identifier>" -F "[email protected]<file_name>" \
     http://localhost/api/v1/host/update

If the update is successfully applied, the device will reboot to complete the update.

Table 14. Error 4xx
FieldTypeDescription
error_messageStringA description of the error encountered
status_codeNumberThe status code for the HTTP request
Error response example
{
    "error_message": "<errorMessage>",
    "status_code": 500
}

Enrollment

Delete

Delete enrollment information for an enrolled device.

A reboot is required after removing enrollment information to ensure the device is no longer connected/enrolled to the Edge Manager. This does not unenroll a device from Edge Manager. A user will need to manually delete the device from Edge Manager.

DELETE

http://localhost/api/v1/host/enroll/
Curl example
curl http://localhost/api/v1/host/enroll \
    --unix-socket /var/run/edge-core/edge-core.sock \
    -X DELETE
Table 15. Error 4xx
FieldTypeDescription
error_messageStringA description of the error encountered
status_codeNumberStatus code for the HTTP request
Error response example
{
    "error_message": "<errorMessage>",
    "status_code": 400
}

Enroll Device

Enrolls the device with the Edge Manager.

POST

http://localhost/api/v1/host/enroll
Table 16. Parameters
FieldTypeDescription
sharedSecretStringShared secret
deviceIdStringDevice identifier
enrollmentUrlStringURL for the enrollment
Curl example
curl http://localhost/api/v1/host/enroll \
    --unix-socket /var/run/edge-core/edge-core.sock \
    -X POST \
    -H "Content-Type: application/json" \
    -d '{
            "sharedSecret": "secret",
            "deviceId": "some-device-id",
            "enrollmentUrl": "https://some-enrollment-url"
        }'
Table 17. Success 200
FieldTypeDescription
enrollmentString"Certified enrollment success"
Success response example
{
    "enrollment": "Certificate enrollment success"
}
Table 18. Error 4xx
FieldTypeDescription
error_messageStringA description of the error encountered
status_codeNumberThe status code for the HTTP request
Error response example
{
    "error_message": "<errorMessage>",
    "status_code": 400
}

Get Enrollment Status

Gets enrollment details from the specified device.

GET

http://localhost/api/v1/host/enroll
Curl example
curl http://localhost/api/v1/host/enroll \
    --unix-socket /var/run/edge-core/edge-core.sock
Table 19. Success 200
FieldTypeDescription
enrolledBooleanTrue if device is enrolled
deviceIdStringDevice identifier
edgeManagerUrlStringURL for the device manager
Enrolled device example
{
    "enrolled": true,
    "deviceId": "some-device-id",
    "edgeManagerUrl": "https://edgemanager-sysint.predix.io"
}
Unenrolled device example
{
    "enrolled": false
}

Logs

Get Log

Use journalctl to retrieve logs. The parameter descriptions reference sections in man journalctrl.

GET

http://localhost/api/v1/host/logs
Table 20. Parameters
FieldTypeDescription
unitStringFilter logs by the given UNIT (see --unit).
priorityStringFilter the logs by priority (See --priority).
useJSONBooleanFormat output as JSON (See --output=json).
useUTCBooleanFormat timestamps in UTC time (See --utc).
sinceStringFilter logs before DATE (See --since).
untilStringFilter logs after DATE (See --until).
kernelBooleanFilter logs; only show kernel (See --kernel).
bootStringFilter out logs before the given boot (See --boot).
applicationServiceStringFilter logs on APPLICATION SERVICE.
linesIntegerNumber of log lines to print.
reverseBooleanPrint the newest entries first.
Curl example
curl --unix-socket /var/run/edge-core/edge-core.sock \
     http://localhost/api/v1/host/logs?since=1+hour+ago&useUTC=true
Table 21. Success 200
FieldTypeDescription
log_textStringLog content
Success response example
{
    "log_text": "Nov 28 11:04:40 machine-name kernel: sd 2:0:0:0: [sda] \
                 Assuming drive cache: write through\\n"
}
Table 22. Error 4xx
FieldTypeDescription
error_messageStringA description of the error encountered
status_codeNumberThe status code for the HTTP request
Error response example
{
    "error_message": "<errorMessage>",
    "status_code": 400
}

Network

Enable DHCP

Enables DHCP on a network interface.

PUT

http://localhost/api/v1/host/network/interfaces/<interface>/dhcp
Table 23. Parameter
FieldTypeDescription
interfaceStringInterface name
Curl example
curl --unix-socket /var/run/edge-core/edge-core.sock \
     -X PUT http://localhost/api/v1/host/network/interfaces/enp0s3/dhcp
Table 24. Success 200
FieldTypeDescription
dhcpBooleanIndicates if DHCP is used or not
nameStringInterface name
typeStringInterface type
Success response example
{
    "dhcp": true,
    "name": "enp0s3",
    "type": "ethernet"
}
Table 25. Error 4xx
FieldTypeDescription
error_messageStringA description of the error encountered
status_codeNumberThe status code for the HTTP request
Error response example
{
    "error_message": "Invalid Interface",
    "status_code": 400
}

Get NTP Information

Gets NTP information.

GET

http://localhost/api/v1/host/network/ntp
Curl example
curl --unix-socket /var/run/edge-core/edge-core.sock \
     http://localhost/api/v1/host/network/ntp
Table 26. Success 200
FieldTypeDescription
serverStringNTP server IP address
Success response example
{
    "servers": [
        "192.168.233.228",
        "ntp.ubuntu.com",
        "time1.google.com"
    ]
}

Get Network Interface

Gets information for a specific network interface.

GET

http://localhost/api/v1/host/network/interfaces/<interface>
Table 27. Parameter
FieldTypeDescription
interfaceStringName of the interface
Curl example
curl --unix-socket /var/run/edge-core/edge-core.sock \
     http://localhost/api/v1/host/network/interfaces/enp0s3
Table 28. Success 200
FieldTypeDescription
dhcpBooleanIndicates if DHCP is used or not
dnsStringDNS server IP address
gatewayStringGateway IP address
ipv4StringInterface IP address
nameStringInterface name
typeStringInterface type
Success response example
{
    "dhcp": true,
    "dns": "10.0.2.3,8.8.8.8",
    "gateway": "10.0.2.2",
    "ipv4": "10.0.2.15/24",
    "name": "enp0s3",
    "type": "ethernet"
}
Table 29. Error 4xx
FieldTypeDescription
error_messageStringA description of the error encountered
status_codeNumberThe status code for the HTTP request
Error response example
{
    "error_message": "<errorMessage>",
    "status_code": 400
}

Get Network Interfaces

Gets information for the device’s network interfaces.

GET

http://localhost/api/v1/host/network/interfaces
Curl example
curl --unix-socket /var/run/edge-core/edge-core.sock \
     http://localhost/api/v1/host/network/interfaces
Table 30. Success 200
FieldTypeDescription
interfacesObjectList of interfaces
dhcpBooleanIndicates if DHCP is used or not
dnsStringDNS server IP address
gatewayStringGateway IP address
ipv4StringInterface IP address
nameStringInterface name
typeStringInterface type
Success response example
{
    "interfaces": [
        {
            "dhcp": true,
            "dns": "10.0.2.3,8.8.8.8",
            "gateway": "10.0.2.2",
            "ipv4": "10.0.2.15/24",
            "name": "enp0s3",
            "type": "ethernet"
        }
    ]
}

Get Proxy Information

Gets network proxy information.

GET

http://localhost/api/v1/host/network/proxy
Curl example
curl --unix-socket /var/run/edge-core/edge-core.sock \
     http://localhost/api/v1/host/network/proxy
Table 31. Success 200
FieldTypeDescription
httpStringHTTP proxy IP address
httpsStringHTTPS proxy IP address
no_proxyStringNon-proxy servers
Success response example
{
    "http": "http://3.3.3.3:80",
    "https": "http://5.5.5.5:88",
    "no_proxy": "*.ge.com, *.google.com"
}

Set NTP Information

Sets the NTP server address.

PUT

http://localhost/api/v1/host/network/ntp
Table 32. Parameter
FieldTypeDescription
serverStringIP address of an NTP server
Curl example
curl http://localhost/api/v1/host/network/ntp \
    --unix-socket /var/run/edge-core/edge-core.sock \
    -X PUT \
    -H "Content-Type: application/json" \
    -d '{
          "servers" : ["192.168.233.228", "ntp.ubuntu.com", "time1.google.com"]
        }'
Table 33. Success 200
FieldTypeDescription
serverStringIP address of an NTP server
Success response example
{
    "servers": [
        "192.168.233.228",
        "ntp.ubuntu.com",
        "time1.google.com"
    ]
}
Table 34. Error 4xx
FieldTypeDescription
error_messageStringA description of the error encountered
status_codeNumberThe status code for the HTTP request
Error response example
{
    "error_message": "<errorMessage>",
    "status_code": 400
}

Set Network Interface

Manually configures a network interface.

PUT

http://localhost/api/v1/host/network/interfaces/<interface>/manual
Table 35. Parameters
FieldTypeDescription
ipv4StringNetwork interface IP address
gatewayStringGateway IP address
dnsStringDNS server IP address
Curl example
curl http://localhost/api/v1/host/network/interfaces/enp0s3/manual \
    --unix-socket /var/run/edge-core/edge-core.sock \
    -X PUT \
    -H "Content-Type: application/json" \
    -d '{
            "ipv4": "192.168.233.228/24",
            "gateway": "192.168.233.2",
            "dns": "192.168.233.2"
        }'
Table 36. Success 200
FieldTypeDescription
dhcpBooleanIndicates if DHCP is used or not
dnsStringDNS server IP address
gatewayStringGateway server IP address
ipv4StringIP network interface address
nameStringNetwork interface name
typeStringNetwork interface type
Table 37. Error 4xx
FieldTypeDescription
error_messageStringA description of the error encountered
status_codeNumberThe status code for the HTTP request
Error response example
{
    "error_message": "<errorMessage>",
    "status_code": 400
}

Set Proxy Information

Sets network proxy information. A reboot is required for the new proxy setting(s) to take effect. All running Edge applications will be redeployed automatically during the next reboot to pickup the new proxy values.

PUT

http://localhost/api/v1/host/network/proxy
Table 38. Parameters
FieldTypeDescription
httpStringHTTP proxy IP address
httpsStringHTTPS proxy IP address
no_proxyStringNon-proxy servers
Curl example
curl http://localhost/api/v1/host/network/proxy \
    --unix-socket /var/run/edge-core/edge-core.sock \
    -X PUT \
    -H "Content-Type: application/json" \
    -d '{
            "http" : "http://192.168.223.228:80",
            "https" : "http://192.168.233.229:80",
            "no_proxy": "google.com"
        }'
Table 39. Success 200
FieldTypeDescription
proxyString"Proxy set successfully"
Success response example
{
    "proxy": "Proxy set successfully"
}
Table 40. Error 4xx
FieldTypeDescription
error_messageStringA description of the error encountered
status_codeNumberThe status code for the HTTP request
Error response example
{
    "error_message": "<errorMessage>",
    "status_code": 400
}