N|Solid Storage HTTP API 1.x

This document describes the HTTP API for N|Solid Storage for version 1.x. The API is described as a set of endpoints, which are an HTTP method and URI. The N|Solid Storage server runs at port 4000 by default.

Responses are generally in JSON or a stream of JSON lines, separated by a newline character.

Query string parameters start and end are time values, and can be provided as the following values:

Query string parameter interval can be specified as a duration string as described above, defaulting to 1 second.

HTTP endpoints

GET /api/v1/application

Returns information about the specified application

Query String Parameters

%%[query-string-parameters.GET.application]%%

Response

Returns a stream of JSON objects with the following shape:

  {
    "time": 1493100519240,
    "app": "nsolid-storage",
    "hostCount": 1,
    "processCount": 1,
    "processes": [
      {
        "id": "42af10301e60e77229ecd289990802ffca040676",
        "app": "nsolid-storage",
        "hostname": "my-server.example.com",
        "tags": [],
        "cpu": 0.0172,
        "heapUsed": 22044312,
        "title": "nsolid-storage",
        "uptime": 168.688,
        "pid": 13383,
        "processStart": 1493100349772,
        "packageCount": 97,
        "vulnerabilityCount": 0,
        "thresholds": {}
      }
    ],
    "vulnerabilities": [],
    "vulnerabilityCount": 0
  }



GET /api/v1/applications

Return information about the currently active applications.

Query String Parameters

%%[query-string-parameters.GET.applications]%%

Response

Returns a stream of JSON objects with the following shape:

{
  "time": 1493100607035,
  "applications": [
    {
      "processCount": 2,
      "vulnerabilityCount": 0,
      "vulnerabilityIds": [],
      "name": "nsolid-storage",
      "hosts": [
        "my-server.example.com"
      ],
      "tags": [],
      "pid": 13383,
      "hostCount": 1
    }
  ]
}



GET /api/v1/asset

Returns the asset specified by the query string parameter.

Query String Parameters

%%[query-string-parameters.GET.asset]%%

Response

The response is the asset data for the specified asset id. For example, a heap snapshot or cpu profile.

GET /api/v1/assets

Returns information about assets that match the query string parameters.

Query String Parameters

%%[query-string-parameters.GET.assets]%%

Response

Returns a stream of JSON objects with the following shape:

{
  "time": 1492721846838,
  "asset": "8d54b288-921f-4afb-9a50-a05879ecc71d",
  "type": "profile",
  "id": "eb886737c82f79eb99cdbf2be941264d1c77e45c",
  "app": "nsolid-storage",
  "hostname": "my-server.example.com",
  "tags": [],
  "size": 66865,
  "compressed": true,
  "pid": 48587,
  "title": "nsolid-storage"
}



POST /api/v1/async-activity

Returns async activity information for the specified processes.

Query String Parameters

%%[query-string-parameters.POST.async-activity]%%

Response

Returns a stream of JSON objects with the following shape:

  {
    "handles": [
      { async handle info },
      ...
    ],
    "id": "720f3e49705aed835c0d9cba7d00c2fabada2abe",
    "time": 1493101435151,
    "app": "nsolid-storage",
    "hostname": "my-server.example.com"
  }







POST /api/v1/custom

Runs the specified custom command in the specified process.

Query String Parameters

%%[query-string-parameters.POST.custom]%%

Response

The data returned by the custom command is determined by the custom command itself.




POST /api/v1/generate-keypair

Generates a new set of ZMQ keypairs.

Query String Parameters

%%[query-string-parameters.POST.generate-keypair]%%

Response

{
  "public": "zg)iP]toT%[rvSoO%Jut87D}uC>H1jV]D7kOz7R@",
  "private": "9mlHhWZJAb5?+iF?2r7(CPc)0FjoIJ:r2R$7brZc"
}



GET /api/v1/info

Returns info records for the specified processes.

Note that this API only returns info records for processes created between the start time and end time. It's generally not terribly useful. See the GET /api/v1/list API below for an alternative.

Query String Parameters

%%[query-string-parameters.GET.info]%%

Response

A stream of JSON objects with the following shape:

{
  "id": "d62ea00feee644a86ffca6a67221f55f08035218",
  "tags": [],
  "pid": 13879,
  "processStart": 1493101883305,
  "execPath": "/usr/local/nsolid/bin/nsolid",
  "main": "/Users/server/bin/bole.js",
  "arch": "x64",
  "platform": "darwin",
  "totalMem": 17179869184,
  "versions": {
    "http_parser": "2.7.0",
    "node": "6.10.2",
    "nsolid": "2.1.4",
    "v8": "5.1.281.98",
    "uv": "1.9.1",
    "zlib": "1.2.11",
    "ares": "1.10.1-DEV",
    "icu": "58.2",
    "modules": "48",
    "openssl": "1.0.2k",
    "nsolid_lib": {
      "v8_profiler": "nsolid-v5.6.5-fix1",
      "sodium": "nsolid-2.1.0",
      "cjson": "nsolid-2.0.0",
      "function_origin": "nsolid-v1.2.1",
      "nan": "v2.3.5",
      "cli": "v2.1.0",
      "agent": "v6.2.2",
      "zmq-bindings": "nsolid-2.15.4-fix1",
      "zmq": "nsolid-v4.2.0-fix4",
      "persistents_with_classid": "v1.1.1"
    }
  },
  "cpuCores": 8,
  "cpuModel": "Intel(R) Core(TM) i7-4870HQ CPU @ 2.50GHz",
  "time": 1493101928082,
  "app": "bole.js",
  "hostname": "my-server.example.com"
}

POST /api/v1/info

Returns info records for the specified processes. This endpoint is the same as the GET endpoint, except that it requests the most current data from the process, instead of using cached data.

Query String Parameters

%%[query-string-parameters.POST.info]%%

Response

Same as for the GET endpoint.













GET /api/v1/list

Return info and metrics records for the specified processes.

Query String Parameters

%%[query-string-parameters.GET.list]%%

Response

Returns a stream of JSON objects with the following shape:

{
  "id": "d7cabdb09c625941d6f5f29bf58695a2b791a5e3",
  "app": "npm",
  "hostname": "my-server.example.com",
  "tags": [],
  "info": {
    // see GET /api/v1/info for the shape of this object
  },
  "metrics": {
    // see GET /api/v1/metrics for the shape of this object
  }
}



GET /api/v1/metrics

Returns metrics records for the specified processes.

Query String Parameters

%%[query-string-parameters.GET.metrics]%%

Response

Returns a stream of JSON objects with the following shape:

{
  "time": 1493125170111,
  "uptime": 31337.626,
  "rss": 21282816,
  "heapTotal": 18911232,
  "heapUsed": 14860616,
  "activeRequests": 0,
  "activeHandles": 3,
  "title": "node",
  "user": "server",
  "cpu": 0.0014,
  "freeMem": 60362752,
  "systemUptime": 3101364,
  "load1m": 1.65478515625,
  "load5m": 1.697265625,
  "id": "cc436cc9f9ebc38c4fcc940e1cf9a48c0ca48a87",
  "load15m": 1.7353515625,
  "cpuSpeed": 2500,
  "app": "nsolid-storage",
  "hostname": "my-server.example.com",
  "percentCpuThreshold": -1,
  "percentHeapThreshold": -1,
  "totalHeapSizeExecutable": 5242880,
  "totalPhysicalSize": 18911232,
  "totalAvailableSize": 1480922440,
  "heapSizeLimit": 1501560832,
  "percentHostMemoryUsedByProcess": 0.0012,
  "percentHostMemoryUsed": 0.9965,
  "tags": []
}



POST /api/v1/metrics

Returns metrics records for the specified processes. This endpoint is the same as the GET endpoint, except that it requests the most current data from the process, instead of using cached data.

Query String Parameters

%%[query-string-parameters.POST.metrics]%%

Response

Same as for the GET endpoint.




POST /api/v1/packages

Returns the list of packages loaded by the specified process.

Query String Parameters

%%[query-string-parameters.POST.packages]%%

Response

A JSON object with the following shape:

{
  "packages": [
    {
      "path": "/Users/server/Projects/ns/nsolid-storage/node_modules/chalk",
      "name": "chalk",
      "version": "1.1.3"
    },
    ...
  ],
  "id": "cc436cc9f9ebc38c4fcc940e1cf9a48c0ca48a87",
  "time": 1493125247630
}



POST /api/v1/ping

Sends a "ping" to all the specified processes, and those processes respond with a "pong".

Query String Parameters

%%[query-string-parameters.POST.ping]%%

Response

Returns a stream of JSON objects with the following shape:

{
  "pong": true,
  "id": "cc436cc9f9ebc38c4fcc940e1cf9a48c0ca48a87",
  "time": 1493125405253
}



POST /api/v1/profile

Generates a CPU profile for the specified process. The profile can be obtained using the /api/v1/asset API, using the asset id returned from this API.

Query String Parameters

%%[query-string-parameters.POST.profile]%%

Response

A JSON object with the following shape:

{
  "id": "cc436cc9f9ebc38c4fcc940e1cf9a48c0ca48a87",
  "time": 1493125623142,
  "asset": "cf9c3eb2-ebe1-4fec-8a5e-bbe2b5f4da3f",
  "assetURL": "/api/v1/asset?asset=cf9c3eb2-ebe1-4fec-8a5e-bbe2b5f4da3f",
  "app": "nsolid-storage",
  "tags": [],
  "hostname": "my-server.example.com",
  "pid": 11247,
  "title": "node"
}

POST /api/v1/snapshot

Generates a CPU profile for the specified process. The snapshot can be obtained using the /api/v1/asset API, using the asset id returned from this API.

Query String Parameters

%%[query-string-parameters.POST.snapshot]%%

Response

A JSON object with the following shape:

{
  "id": "cc436cc9f9ebc38c4fcc940e1cf9a48c0ca48a87",
  "time": 1493125748822,
  "asset": "77198efd-ca5f-4bde-b87b-feed3b5d0e3b",
  "assetURL": "/api/v1/asset?asset=77198efd-ca5f-4bde-b87b-feed3b5d0e3b",
  "app": "nsolid-storage",
  "tags": [],
  "hostname": "my-server.example.com",
  "pid": 11247,
  "title": "node"
}

POST /api/v1/startup-times

Returns the startup times of the specified processes.

Query String Parameters

%%[query-string-parameters.POST.startup-times]%%

Response

Returns a stream of JSON objects with the following shape:

{
  "initialized_node": [ 0, 142981 ],
  "initialized_v8": [ 0, 354300 ],
  "loaded_environment": [ 0, 94062229 ],
  "id": "3011d78849cee41634a7874cef413314e202b794",
  "time": 1493125922677,
  "app": "bole.js",
  "hostname": "my-server.example.com"
}

Note the time values are specified as an array of [seconds, nanoseconds].










GET /api/v1/vulnerabilities

Returns information about security vulnerabilities found in running processes.

Query String Parameters

%%[query-string-parameters.GET.vulnerabilities]%%

Response

Returns a stream of JSON objects with the following shape:

{
  "time": 1493126695596,
  "vulnerabilities": [
    {
      "package": "moment",
      "title": "Regular Expression Denial of Service (DoS)",
      "published": "2016-02-01T19:00:03.862Z",
      "credit": [ "Adam Baldwin" ],
      "id": "npm:moment:20160126",
      "ids": {
        "CWE": [
          "CWE-400"
        ],
        "CVE": [],
        "NSP": 55,
        "ALTERNATIVE": [
          "SNYK-JS-MOMENT-10084"
        ]
      },
      "vulnerable": "<=2.11.1",
      "unaffected": ">2.11.1",
      "description": "[[markdown content here]]",
      "apps": [
        {
          "appname": "pkg-moment-2.11.0",
          "processes": [
            {
              "id": "e022e11f7b260ac4c16a614d8368710187840ff7",
              "hostname": "my-server.example.com",
              "pid": 17438,
              "loaded": [
                {
                  "version": "2.11.0",
                  "path": "/path/to/node_modules/moment"
                },
                {
                  "version": "2.11.1",
                  "path": "/path/to/node_modules/moment"
                },
              ]
            }
          ]
        }
      ],
      "patches": [
        "[[url to patch]]"
      ]
    },
    {
      // additional records for other vulnerabilities
    }
  ]
}