Nachos

Introduction

Nachos is a new service which will replace the old configuration management (Nacoma). In the first iteration it will only replace the export part of Nacoma. The service will yield a response immediately and run the task in the background, which means you will not have to wait until the export has finished until you get a response. The status of the export process can be retrieved with an API request. Nachos is designed to be more maintainable and faster than Nacoma.

For a GUI user the visible differences is the export progress banners, status details and the save dialogue.

Nachos API definition

This section will explain how to start an export configuration using Nachos instead of Nacoma using Monitors external API. As Nachos behaves slightly different from Nacoma, the /api/config/change will remain unchanged and can be used to export with Nacoma.
The biggest difference of behaviour when saving with the two endpoints is that Nacoma will not return a response until the export has finished. The Nachos endpoint will return a response immediately, and the export will be executed in the background.

Error entity

Error responses follow this general structure and are returned as entities for all requests that do not result in 2xx or 3xx statuses.

The error will always contain a name and description of the error.

The error is a JSON entity

Example response

[
  {
     "name": "error_name",
     "description": "error_description",
  }
]

GET /v1/latestexport

Fetches details about latest executed export.

Example curl

curl -k -u 'your_username:your_password' https://localhost/api/nachos/v1/latestexport

Response

200 OK

If the export is retreied successfully

{
	"id": "123e4567-e89b-12d3-a456-426655440045",
	"creation_time": 1982549018,
       "status": "running",
	"status_details": [
	 {
	    "state": "backup",
	    "progress": 1.0,
	    "details": ""
	 },
	 {
	    "state": "config_generation",
	    "progress": 0.0,
	    "details": "writing hosts.cfg"
	 },
	 {
	    "state":"verification",
	    "progress":0.0,
	    "details":""
	 },
	 {
	    "state":"commit",
	    "progress":0.0,
	    "details":""
	 }
	 ],
	    "user": "your_username",
	    "export_type": "user_export"
}

GET /v1/exports Retrieves a list of existing exports, order by creation time.

curl -k -u 'your_username:your_password' https://localhost/api/nachos/v1/exports

Query parameters

limit integer

Limits the amount of exports returned.

For example /v1/exports?limit=20 returns the 20 latest exports.

sort_by string ( id | creation_time | status | user | export_type | details )

On what property the exports should be sorted on.

order string ( asc | desc )

If the exports should be sorted by ascending or descending order.

curl -k -u 'your_username:your_password' https://localhost/api/nachos/v1/exports?sort_by=status

Response

200 OK

If the list is retrieved successfully

Example Response

[
  {
    "creation_time": "2019-03-26T12:48:07.000000",
    "export_type": "full_export",   
    "id": "37cba483-6f01-4820-b663-6168a44e3771",     
    "status": "running",  
    "status_details": [
       {
		"details": "",
		"progress": 1,
		"state": "backup"
	},
	{
		"details": "",
		"progress": 0,
		"state": "config_generation"
	},
	{
		"details": "",
		"progress": 0,
		"state": "verification"
	},
	{
		"details": "",
		"progress": 0,
		"state": "commit"
	}
		      ],
		"user": "your_username"
	},
	{
		"creation_time": "2019-03-26T12:46:59.000000",
		"export_type": "full_export",
		"id": "1e0a04e7-5ad1-425b-b12b-6082ee07e1c6",
		"status": "success",
		"status_details": [
	                {
				"details": "",
				"progress": 1,
				"state": "backup"
			},
			{
				"details": "",
				"progress": 1,
				"state": "config_generation"
			},
			{
				"details": "",
				"progress": 0,
				"state": "verification"
		        },
			{
				"details": "",
				"progress": 1,
				"state": "commit"
			}
				],
	"user": "your_username"
   }
]

GET /v1/exports/<id>

Retrieves an existing export.

curl -k -u 'your_username:your_password' https://localhost/api/nachos/v1/exports/37cba483-6f01-4820-b663-6168a44e3771

Response

200 OK

If the export is retrieved successfully. Example Response

{
	"creation_time": "2019-03-26T12:48:07.000000",
	"export_type": "full_export",
	"id": "37cba483-6f01-4820-b663-6168a44e3771",
	"status": "success",
	"status_details": [
	  {
		"details": "",
		"progress": 1,
		"state": "backup"
	  },
	  {
		"details": "",
		"progress": 1,
		"state": "config_generation"
	  },
	  {
		"details": "",
		"progress": 0,
		"state": "verification"
	  },
	  {
		"details": "",
		"progress": 1,
		"state": "commit"
	  }
			  ],
	"user": "your_username"
}

POST /v1/exports

Creates a new export based on the supplied data (as JSON) in the request body The POST request must supply the header: Content-Type: application/json

Example request

{
  "user": "your_username",
  "export_type": "full_export"|"user_export"
}

Example curl

curl -H "Content-Type: application/json" -X POST -d '{"user": "your_username", "export_type": "full_export"}' -k -u 'your_username:your_password' https://localhost/api/nachos/v1/exports

Response

202 Accepted

On successful export creation, will return the created export in addition to supplying the Location header with a URL to the new export resource.

Example Response

{
	"export_type": "full_export",
	"status_details": [
	  {
		"state": "backup",
		"progress": 0,
		"details": ""
	  },
	  {
	        "state": "config_generation",
		"progress": 0,
		"details": ""
         },
	  {
	        "state": "verification",
		"progress": 0,
		"details": ""
	  },
	  {
		"state": "commit",
		"progress": 0,
		"details": ""
	  }
	                   ],
	"id": "6f568330-a79f-4f28-b258-6b1ab0fa745b",
	"creation_time": "2019-03-26T12:57:26.131865",
	"user": "administrator",
	"status": "pending"
}

Response

401 Unauthorized

If the provided username does not match the authenticated username, a 401 Unauthorized response is returned.

Example curl

curl -H "Content-Type: application/json" -X POST -d '{"user": "not_your_username", "export_type": "full_export"}' -k -u 'your_username:your_password' https://localhost/api/nachos/v1/exports

Response

503 Service Unavailable

If the service is busy exporting data. The Retry-After header will be set with a number of seconds.