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
Field	Type	Description
app_name	String	Application 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
Name	Type	Description
error_message	String	A description of the error encountered
status_code	Number	Status 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
Field	Type	Description
app_name	String	Application name
file	String	Application 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
Field	Type	Description
app_name	String	Application name
file_name	String	Name 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
Field	Type	Description
error_message	String	A description of the error encountered
status_code	Number	Status 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
Field	Type	Description
app_name	String	Application 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
Field	Type	Description
error_message	String	A description of the error encountered
status_code	Number	Status 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
Field	Type	Description
app_name	String	Application 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
Field	Type	Description
error_message	String	A description of the error encountered
status_code	Number	Status 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
Field	Type	Description
os_name	String	OS name
os_version	String	OS version
os_arch	String	OS 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
Field	Type	Description
update_identifier	String	Identifier 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
Field	Type	Description
last_os_upgrade	String	State 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
Field	Type	Description
update_identifier	String	An identifier associated with the update. Can be any string, as long as it is unique.
file_name	String	Name 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
Field	Type	Description
error_message	String	A description of the error encountered
status_code	Number	The 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
Field	Type	Description
error_message	String	A description of the error encountered
status_code	Number	Status 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
Field	Type	Description
sharedSecret	String	Shared secret
deviceId	String	Device identifier
enrollmentUrl	String	URL 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
Field	Type	Description
enrollment	String	"Certified enrollment success"

Success response example

{
    "enrollment": "Certificate enrollment success"
}

Table 18. Error 4xx
Field	Type	Description
error_message	String	A description of the error encountered
status_code	Number	The 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
Field	Type	Description
enrolled	Boolean	True if device is enrolled
deviceId	String	Device identifier
edgeManagerUrl	String	URL 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
Field	Type	Description
unit	String	Filter logs by the given UNIT (see --unit).
priority	String	Filter the logs by priority (See --priority).
useJSON	Boolean	Format output as JSON (See --output=json).
useUTC	Boolean	Format timestamps in UTC time (See --utc).
since	String	Filter logs before DATE (See --since).
until	String	Filter logs after DATE (See --until).
kernel	Boolean	Filter logs; only show kernel (See --kernel).
boot	String	Filter out logs before the given boot (See --boot).
applicationService	String	Filter logs on APPLICATION SERVICE.
lines	Integer	Number of log lines to print.
reverse	Boolean	Print 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
Field	Type	Description
log_text	String	Log 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
Field	Type	Description
error_message	String	A description of the error encountered
status_code	Number	The 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
Field	Type	Description
interface	String	Interface 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
Field	Type	Description
dhcp	Boolean	Indicates if DHCP is used or not
name	String	Interface name
type	String	Interface type

Success response example

{
    "dhcp": true,
    "name": "enp0s3",
    "type": "ethernet"
}

Table 25. Error 4xx
Field	Type	Description
error_message	String	A description of the error encountered
status_code	Number	The 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
Field	Type	Description
server	String	NTP 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
Field	Type	Description
interface	String	Name 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
Field	Type	Description
dhcp	Boolean	Indicates if DHCP is used or not
dns	String	DNS server IP address
gateway	String	Gateway IP address
ipv4	String	Interface IP address
name	String	Interface name
type	String	Interface 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
Field	Type	Description
error_message	String	A description of the error encountered
status_code	Number	The 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
Field	Type	Description
interfaces	Object	List of interfaces
dhcp	Boolean	Indicates if DHCP is used or not
dns	String	DNS server IP address
gateway	String	Gateway IP address
ipv4	String	Interface IP address
name	String	Interface name
type	String	Interface 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
Field	Type	Description
http	String	HTTP proxy IP address
https	String	HTTPS proxy IP address
no_proxy	String	Non-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
Field	Type	Description
server	String	IP 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
Field	Type	Description
server	String	IP address of an NTP server

Success response example

{
    "servers": [
        "192.168.233.228",
        "ntp.ubuntu.com",
        "time1.google.com"
    ]
}

Table 34. Error 4xx
Field	Type	Description
error_message	String	A description of the error encountered
status_code	Number	The 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
Field	Type	Description
ipv4	String	Network interface IP address
gateway	String	Gateway IP address
dns	String	DNS 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
Field	Type	Description
dhcp	Boolean	Indicates if DHCP is used or not
dns	String	DNS server IP address
gateway	String	Gateway server IP address
ipv4	String	IP network interface address
name	String	Network interface name
type	String	Network interface type

Table 37. Error 4xx
Field	Type	Description
error_message	String	A description of the error encountered
status_code	Number	The 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
Field	Type	Description
http	String	HTTP proxy IP address
https	String	HTTPS proxy IP address
no_proxy	String	Non-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
Field	Type	Description
proxy	String	"Proxy set successfully"

Success response example

{
    "proxy": "Proxy set successfully"
}

Table 40. Error 4xx
Field	Type	Description
error_message	String	A description of the error encountered
status_code	Number	The status code for the HTTP request

Error response example

{
    "error_message": "<errorMessage>",
    "status_code": 400
}