Magellan Autodiscovery API

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. For POST and PATCH requests it may contain a list of errors that need to be made on the request entity for the request to be successfull.

The error is a JSON entity:

{
    "name": <error_name>,
    "description": <error_description>,
    "errors": [
        Error entities...
    ]
}

Patch entity

A Patch entity follows the http://jsonpatch.com/ standard, which is specified in RFC 6902 from the IETF.

It is an entity describing a sequence of changes to be made on a resource.

Valid operations:

replace - Changes the value identified by path with the newly supplied value
add - Adds the supplied value to a resource identified by path
remove - Removes a key/value pair from the resource identified by path

Example patch entity:

[
    { "op": "replace", "path": "/baz", "value": "boo" },
    { "op": "add", "path": "/hello", "value": ["world"] },
    { "op": "remove", "path": "/foo"}
]

Job API

Manages discovery jobs that may later be executed

GET /v1/jobs

Retrieves all existing jobs as a list

The list is a JSON encoded structure:

[
    {
        "id": <job_id>,
        "name": <job_name>,
        "description": <job_description>,
        "method": <job_method>,
        "options": <job_options>,
        "timeout": <job_timeout>,
        "created_at": <job_create_time>,
        "updated_at": <job_update_time>
    }
    ...
]

Excluded IP list data

This endpoint does not return any job data for /options/ip_list. The IP list data is excluded because it can potentially be very large, and is typically not of immediate interest when fetching all existing jobs.

Responses

200 OK - If the list is retrieved successfully.

400 Bad Request - If the request is not valid. The response entity should be an Error.

406 Not Acceptable - If the request has an Accept header and it is not equal to application/json. The response entity should be an Error.

POST /v1/jobs

Creates a new autodiscovery job based on the supplied data (as JSON) in the request body

The POST request must supply header: Content-Type: application/json

Request:

name - string
description - string
method - what method to use - "seed_router", "ip_range", "ip_list"
options - JSON object, what options to send to backend (selected by method)
- seed_router:
  - seed_router - ipv4_address to seed router
  - snmp - JSON object with SNMP options
    - SNMPv1 and SNMPv2c:
      - version - string ("v1" or "v2c")
      - community - string (optional, defaults to "public")
    - SNMPv3:
      - version - string ("v3")
      - secname - string
      - authpass - string (optional, unless privpass is given)
      - privpass - string (optional)
- ip_range:
  - ip_range - ip range/CIDR string
- ip_list:
  - ip_list - string with ip addresses or ranges separated by newline or space characters.
timeout - int - Timeout in seconds before a job execution should be automatically cancelled. Optional, defaults to 3600 seconds (1 hour).

Example

Job that performs a seed router discovery from 172.27.87.120.

{
    "name": "my-job",
    "description": "This job discovers my favorite network",
    "method": "seed_router",
    "options": {
        "seed_router": "172.27.87.120",
        "snmp": {
            "version": "v2c",
            "community": "public"
        }
    }
}

Responses

201 Create - On successfull job creation, should return an entity consisting of the URL to the newly created job in addition to supplying the Location header with a URL to the job endpoint.

400 Bad Request - If the request is not valid, such as when the entity sent does not contain all required fields or when a field fails validation. The response entity should be an Error.

406 Not Acceptable - If the request has an Accept header and it is not equal to application/json. The response entity should be an Error.

409 Conflict - If the name of the new job already exists. The response entity should be an Error.

415 Unsupported Media Type - If the content-type header is not application/json. The response entity should be an Error.

GET /v1/jobs/<job_id>

Retrieves a specific job with a given job_id (UUID)

The job is a JSON encoded structure:

{
    "id": <job_id>,
    "name": <job_name>,
    "description": <job_description>,
    "method": <job_method>,
    "options": <job_options>,
    "timeout": <job_timeout>,
    "created_at": <job_create_time>,
    "updated_at": <job_update_time>
}

Responses

200 OK - If the job is retrieved successfully.

400 Bad Request - If the request is not valid. The response entity should be an Error.

404 Not Found - If the supplied job_id does not exist. The response entity should be an Error.

406 Not Acceptable - If the request has an Accept header and it is not equal to application/json. The response entity should be an Error.

PATCH /v1/jobs/<job_id>

Updates an existing autodiscovery job based on the supplied data (as JSON) in the request body. The entity should be a Patch entity, a list of operations to perform on the resource.

The PATCH request must supply header: Content-Type: application/json

Fields available for patching:

name - string
description - string
method - string
options - object
timeout - integer

The entity is a JSON encoded structure:

[
    {"op": <patch_operation>, "path": <patch_field>, "value": <patch_value>}
    ...
]

Example:

[
    {"op": "replace", "path": "/name", "value": "New job name"}
]

Responses

200 OK - If the job was updated successfully.

400 Bad Request - If the request is not valid. The response entity should be an Error.

404 Not Found - If the supplied job_id does not exist. The response entity should be an Error.

406 Not Acceptable - If the request has an Accept header and it is not equal to application/json. The response entity should be an Error.

409 Conflict - If the update attempts to give the job the same name as that of an another existing job. The response entity should be an Error.

415 Unsupported Media Type - If the content-type header is not application/json. The response entity should be an Error.

DELETE /v1/jobs/<job_id>

Removes a job from the database

Responses

204 No Content - If the job was deleted successfully. The response contains no body.

400 Bad Request - If the request is not valid. The response entity should be an Error.

404 Not Found - If the supplied job_id does not exist. The response entity should be an Error.

GET /v1/jobs/<job_id>/executions

Retrieves all existing executions for a job_id as a list

The list is a JSON encoded structure:

[
    {
        "id": <execution_id>,
        "job_id": <job_id>,
        "name": <execution_job_name>,
        "description": <execution_job_description>,
        "status": <execution_job_status>,
        "created_at": <execution_job_create_time>,
        "updated_at": <execution_job_update_time>,
        "complete_time": <execution_job_complete_time>,
    }
    ...
]

Responses

200 OK - If the list is retrieved successfully.

400 Bad Request - If the request is not valid. The response entity should be an Error.

404 Not Found - If the supplied job_id does not exist. The response entity should be an Error.

406 Not Acceptable - If the request has an Accept header and it is not equal to application/json. The response entity should be an Error.

Execution API

Manages discovery jobs executions

GET /v1/executions

Retrieves all existing executions as a list

The list is a JSON encoded structure:

[
    {
        "id": <execution_id>,
        "job_id": <job_id>,
        "name": <execution_job_name>,
        "description": <execution_job_description>,
        "status": <execution_job_status>,
        "created_at": <execution_job_create_time>,
        "updated_at": <execution_job_update_time>,
        "complete_time": <execution_job_complete_time>
    }
    ...
]

Responses

200 OK - If the list is retrieved successfully.

400 Bad Request - If the request is not valid. The response entity should be an Error.

406 Not Acceptable - If the request has an Accept header and it is not equal to application/json. The response entity should be an Error.

POST /v1/executions

Creates a new autodiscovery job execution based on the supplied data (as JSON) in the request body.

The execution of the job will be done as soon as possible.

The POST request must supply header: Content-Type: application/json

Request:

job_id - string
description - string
name - string

Example

Start autodiscovery job execution based on job_id definition.

{
    "job_id": "78cc910c-1102-40ee-af99-d7e416f54c0a",
    "name": "Bulk rescan",
    "description": "Provisioned 20 new hosts, rescanning",
}

Responses

201 Create - On successful job execution creation, should return an entity consisting of the URL to the newly created job execution in addition to supplying the Location header with a URL to the job execution endpoint.

400 Bad Request - If the request is not valid, such as when the entity sent does not contain all required fields or when a field fails validation. The response entity should be an Error.

404 Not Found - If the supplied job_id does not exist. The response entity should be an Error.

406 Not Acceptable - If the request has an Accept header and it is not equal to application/json. The response entity should be an Error.

415 Unsupported Media Type - If the content-type header is not application/json. The response entity should be an Error.

503 Service Unavailable - If there already is a running execution associated with the supplied job_id. The response entity should be an Error.

GET /v1/executions/<execution_id>

Retrieves all information about an execution

The entity is a JSON encoded structure:

{
    "id": <execution_id>,
    "job_id": <job_id>,
    "name": <execution_job_name>,
    "description": <execution_job_description>,
    "status": <execution_job_status>,
    "created_at": <execution_job_create_time>,
    "updated_at": <execution_job_update_time>,
    "complete_time": <execution_job_complete_time>
}

Responses

200 OK - If the entity is retrieved successfully.

400 Bad Request - If the request is not valid. The response entity should be an Error.

404 Not Found - If the supplied execution_id does not exist. The response entity should be an Error.

406 Not Acceptable - If the request has an Accept header and it is not equal to application/json. The response entity should be an Error.

DELETE /v1/executions/<execution_id>

Removes an execution job from the database

Responses

204 No Content - If the job was deleted successfully. The response contains no body.

400 Bad Request - If the request is not valid. The response entity should be an Error.

404 Not Found - If the supplied execution_id does not exist. The response entity should be an Error.

PUT /v1/executions/cancel/<execution_id>

Cancels the ongoing discovery process of an execution job

Responses

202 Accepted - If the attempt to cancel the execution has been accepted. This response will not wait for the execution to actually stop.

400 Bad Request - If the request is not valid. The response entity should be an Error.

404 Not Found - If the supplied execution_id does not exist. The response entity should be an Error.

GET /v1/executions/<execution_id>/devices

Retrieves all devices found by an execution

The entity is a JSON encoded structure:

[
    {
        "address": <device_ip_address>,
        "details": <device_details>,
        "neighbours": [<device_ip_addresses>],
    },
    ...
]

Responses

200 OK - If the entity is retrieved successfully.

400 Bad Request - If the request is not valid. The response entity should be an Error.

404 Not Found - If the supplied execution_id does not exist. The response entity should be an Error.

406 Not Acceptable - If the request has an Accept header and it is not equal to application/json. The response entity should be an Error.