IPFabric API (v1)

API Endpoint

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC-2119.

URL Prefix

API URL has the following structure:

https://<hostname>/api/v1/<endpoint>

Status Codes

This API uses HTTP status codes to communicate with the API consumer.

  • 200 OK - response to a successful GET, PUT, PATCH or DELETE request,

  • 201 Created - response to a POST request that results in the creation of a resource,

  • 204 No Content - response to a successful request that won’t be returning a body,

  • 400 Bad Request - response to a request that is malformed or it does not follow this documentation,

  • 401 Unauthorized - response to a request with invalid authentication details,

  • 403 Forbidden - response to a request made by an authenticated user but with no access to the requested resource,

  • 404 Not Found - response to request a non-existing endpoint or resource,

  • 405 Method Not Allowed - response to requesting an existing endpoint that does not support the used method,

  • 406 Not Acceptable - response to a request that could not satisfy the Accept header,

  • 409 Conflict - response to a request that causes a conflict with the current state of the target resource.

  • 422 Unprocessable Entity - response to a request that provided invalid input to the existing endpoint.

  • 500 Internal Server Error - response to a request that caused an unexpected behaviour.

Authentication

The application offers local and LDAP authentication. Both authentication strategies behave same from the API viewpoint.

The API offers two HTTP authentication methods:

  • basic authentication,

  • token-based authentication.

In both methods, a request contains a header field of the form Authorization: <data>.

Basic Authentication

Basic HTTP Authentication as per RFC-7617 (excluding Digest) is supported. A request contains a header field of the form Authorization: Basic <credentials>, where credentials is the Base64 encoding of username and password joined by a colon character. It is RECOMMENDED to use this authentication method only for API exploration/testing since the API has to fetch user data from a database on every single request.

Token Authentication

Token authentication consists of two tokens:

Access Token

An access token is JSON Web Token (JWT) as per RFC-7519 signed using SHA-256 with RSA encryption.

The token expires in 30 minutes since being generated and it can’t be revoked during its lifetime. It consists of three parts separated by dots:

  • header,

  • payload,

  • signature.

The payload contains an object with the following fields:

  • id - a user ID,

  • eula - a boolean value whether a user approved EULA or not,

  • exp - a token expiration time (in seconds since Unix epoch),

  • iat - a token issued time (in seconds since Unix epoch),

  • scope - an array of strings representing granted user access (more in authorization),

  • username - a string.

Refresh Token

A refresh token is a token that can be used to obtain a renewed access token.

It can be requested for new access tokens until the refresh token is revoked (blacklisted) or expired. A refresh token expires after 24 hours of not being used for generation of a new access token.

Refresh tokens must be stored securely by an application because they essentially allow a user to remain authenticated forever.

When consuming the API programmatically, it is recommended to create a new user account in user management with a restricted scope. It is REQUIRED to log in using the account into the application frontend and accept EULA, after creating the account. The account can be used to consume the API programmatically only after EULA is accepted.

It is RECOMMENDED to follow these steps when authenticating a user programmatically:

  1. Login user (more).
  2. Safely store a refresh token and use an access token in any requests that require authentication.
  3. When a request returns API_EXPIRED_ACCESS_TOKEN error, get a new access token using the stored refresh token (more).
  4. Repeat steps 2-4 until the refresh token is valid. If the refresh token expires, new login is necessary.

Errors

The API returns an object with a machine-readable error code and a human-readable error message in response body when an error is encountered:

{
    "code": "API_NOT_FOUND",
    "message": "Requested Resource Not Found"
}

Common Errors

  • API_MISSING_EULA_APPROVAL - This error occurs when a user hasn’t approved EULA. It is REQUIRED to login using the user’s credentials into the application user interface and accept EULA.

  • API_EXPIRED_ACCESS_TOKEN - The provided access token (from Authorization header) is expired.

  • API_INVALID_ACCESS_TOKEN - The provided access token (from Authorization header) is invalid.

  • API_INVALID_REFRESH_TOKEN - The provided refresh token (typically sent in the request body) is revoked (blacklisted) or expired.

  • API_NOT_FOUND - The requested resource does not exist.

Authorization

Every user has its granted scope that allows him to access a different part of the application. The available access scope follows:

scope name description
read Access to read-only data
settings Right to change global settings
team Access into user management
write Right to start network discovery process

If a user does not have any granted authorization scope, he is considered inactive, and he is unable to log into the system. It is recommended to choose the most restrictive scopes possible to any user.

Authentication

Login User

POST /auth/login
RequestsExample
Body
{
  "username": "admin",
  "password": "password"
}
Schema
{
  "type": "object",
  "properties": {
    "username": {
      "type": "string"
    },
    "password": {
      "type": "string"
    }
  },
  "required": [
    "username",
    "password"
  ],
  "$schema": "http://json-schema.org/draft-04/schema#"
}
Responses200401
Headers
Content-Type: application/json
Body
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eGdOyqN-VUPhSvnQv54BHQaA9vcr_UliFYGi..."
}
Headers
Content-Type: application/json
Body
{
  "code": "API_INVALID_CREDENTIALS",
  "message": "Invalid Credentials"
}

Retrieve Refresh and Access Token
POST/auth/login

Retrieve access and refresh token using username and password.


Token Actions

POST /auth/token
RequestsExample
Body
{
  "refreshToken": "eGdOyqN-VUPhSvnQv54BHQaA9vcr_UliFYGi..."
}
Schema
{
  "type": "object",
  "properties": {
    "refreshToken": {
      "type": "string"
    }
  },
  "required": [
    "refreshToken"
  ],
  "$schema": "http://json-schema.org/draft-04/schema#"
}
Responses200401
Headers
Content-Type: application/json
Body
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
Headers
Content-Type: application/json
Body
{
  "code": "API_INVALID_REFRESH_TOKEN",
  "message": "Invalid Refresh Token"
}

Generate Access Token
POST/auth/token

Generate an access token using a refresh token.


DELETE /auth/token
RequestsExample
Headers
Content-Type: application/json
Authorization: <data>
Body
{
  "refreshToken": "eGdOyqN-VUPhSvnQv54BHQaA9vcr_UliFYGi..."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "refreshToken": {
      "type": "string"
    }
  },
  "required": [
    "refreshToken"
  ]
}
Responses204401
This response has no content.
Headers
Content-Type: text/plain
Body
Unauthorized

Revoke Refresh Token
DELETE/auth/token

Only an authorized user with team scope can revoke a refresh token.


Logout User

POST /auth/logout
RequestsExample
Headers
Content-Type: application/json
Authorization: <data>
Responses200401
Headers
Content-Type: application/json
Body
{
  "success": true
}
Headers
Content-Type: application/json
Body
{
  "code": "API_EXPIRED_ACCESS_TOKEN",
  "message": "Expired JWT Access Token"
}

Logout User
POST/auth/logout

Only an authorized user can log out.


Tables

Table documentation can be found directly in the platform by clicking on the question mark button in the header of a table. The documentation contains an API endpoint and an object structure required for a successful request. It also contains a request body of a current table state.

A request body used by the platform to retrieve table data can be seen by clicking on the “Table description” button in the header of a table.

API Documentation in IP Fabric

Request Payload

A JSON object with the following properties:

  • snapshot [required]: a string with a snapshot ID or one of the following variables:

    • $last: the latest snapshot,
    • $prev: the second last snapshot,
    • $lastLocked: the latest locked snapshot,
  • columns [required]: an array of strings representing data that should be retrieved (more info),

  • filters [optional]: more info,

  • pagination [optional]: more info,

  • sort [optional]: more info,

  • reports [optional]: more info.

Columns

An array of strings that represents fields for each record that should be returned. Only the listed fields are returned.

Filter Structure

A filter object is an object with the following structure:

{
    [column]: [<operator>, <value>],
    "or": <array of filter objects>,
    "and": <array of filter objects>
}

An example of a filter is:

{
    "family": ["eq", "cisco"],
    "or": [
        {"hostname": ["eq", "HWLAB-01"]},
        {"hostname": ["eq", "HWLAB-02"]},
    ]
}

Pagination

An optional object that contains number of records to be returned (limit) and an offset (start).

The following example returns 10 records starting from 20th record.

{
    "limit": 10,
    "start": 10
}

Sort

An optional object that contains a column that is being sorted on and an order (asc for asceding or desc for descending order).

Example:

{
    "column": "uptime",
    "order": "desc"
}

Reports

The reports property accepts two data types:

  • an array of colour report IDs,

  • a string of frontend URL where the reports are displayed (for example "/inventory/devices" for Inventory/Devices table).

If a valid value is specified, the response for a particular column returns data in a form of {"data": "value", "severity": 0}, where severity can either be:

  • 0 - green colour,

  • 10 - blue colour,

  • 20 - yellow colour,

  • 30 - red colour.

Generated by aglio on 17 Nov 2019