This article describes how to use APIs to call Nightingale interfaces. There are mainly two types of APIs: one is page-operation APIs, which use APIs to mimic user operations on the page; the other is data-push APIs, for example, if your own program collects monitoring data and wants to push it to Nightingale.

Page-Operation APIs

Page-operation APIs mainly simulate user operations on the page, such as creating alert rules, modifying machine labels, modifying machine notes, adjusting the business group to which a machine belongs, etc. Any user operation on the page can be done using APIs, and you can use these interfaces to implement automated operations.

Obviously, calling the API requires two prerequisites:

• Sort out authentication
• Understand what interfaces are available and what parameters each interface has

Sort Out Authentication

This article directly explains the authentication method for versions above v8.0.0-beta.5, namely the personal center token method, which is the simplest.

1. Modify Configuration File

Modify the Nightingale configuration file etc/config.toml, ensure that HTTP.TokenAuth is configured and Enable = true is set, as shown below:

...
[HTTP.RSA]
OpenRSA = false

[HTTP.TokenAuth]
Enable = true

[DB]
...

2. Get Token

Log into Nightingale, click the avatar in the top right, enter the personal info page, click the “Token Management” tab, then click “Create Token”, give it any name, and you will get a Token.

3. Use Token

When calling the API, you need to add an X-User-Token field to the HTTP request header, with the value being the Token you just created. Example of using cURL to call the API:

curl -s -X GET "http://<NIGHTINGALE_HOST><API_URL_PATH>" \
-H "X-User-Token: <YOUR_TOKEN>" \
-H "Content-Type: application/json"

Let’s test the interface for getting personal info:

curl -s -H "X-User-Token: e6897d32-c237-4d27-a0fc-786345b682ea" -H "Content-Type: application/json" 'http://10.99.1.106:8003/api/n9e/self/profile' | python3 -m json.tool
{
    "dat": {
        "id": 1,
        "username": "root",
        "nickname": "Root",
        "phone": "",
        "email": "qinxiaohui@flashcat.cloud",
        "portrait": "/image/avatar1.png",
        "roles": [
            "Admin"
        ],
        "contacts": {
            "wecomid": "qinxiaohui"
        },
        "maintainer": 0,
        "create_at": 1733229739,
        "create_by": "system",
        "update_at": 1749811268,
        "update_by": "root",
        "belong": "",
        "admin": true,
        "user_groups": null,
        "busi_groups": null,
        "last_active_time": 1749811088
    },
    "err": ""
}

As above, content was returned normally, indicating success. If you want to write a program to call the API, you need to verify:

• Whether the HTTP status code returned by Nightingale is 200. If the status code is not 200, the request failed. At this point, you can print the Response Body to see the specific error message.
• If the status code is 200, the Response Body is definitely JSON. At this point, you also need to verify whether the err field in the JSON data is empty. If it is not empty, there is a problem.

Understand What Interfaces Are Available

View the API documentation, or open the Nightingale page directly with Chrome, press F12 to open developer tools, switch to the Network tab, then perform operations on the page, such as creating an alert rule or modifying machine labels. You will see many API requests in the Network panel, which are Nightingale’s API interfaces. For example:

• Under Headers, you can see the Request Method and URL
• Under Response, you can see the returned content

The interface above does not have any query string parameters. If there are query string parameters, they are usually displayed in the URL. Additionally, if it is a POST request, you need to study the format of the Request Body. At that time, a Payload tab will appear, and the content format of the Request Body can be seen under Payload.

This method is much better than API documentation. API documentation is often forgotten to be updated, and differences between versions are often forgotten to be explained, but by looking at it through Chrome this way, the information is absolutely 100% accurate. What interfaces are available and what parameters are needed is clear at a glance. Every ops engineer and backend developer should know this method.

Data-Push APIs

When your own program exposes monitoring data, there are usually two methods: one is to embed a Prometheus SDK, expose the /metrics interface, and then have Prometheus or Categraf scrape it (called PULL mode); the other is to directly call Nightingale’s API interface to push monitoring data (called PUSH mode). Nightingale supports multiple data-receiving interfaces, including OpenTSDB, Open-Falcon, PrometheusRemoteWrite, Datadog, and other protocols.

Push Sample

Taking OpenTSDB protocol as an example, the Nightingale interface path is /opentsdb/put, the HTTP Method is POST, and the monitoring data you want to report is placed in the Request Body. The format example is as follows:

[
	{
		"metric": "cpu_usage_idle",
		"timestamp": 1637732157,
		"tags": {
			"cpu": "cpu-total",
			"ident": "c3-ceph01.bj"
		},
		"value": 30.5
	},
	{
		"metric": "cpu_usage_util",
		"timestamp": 1637732157,
		"tags": {
			"cpu": "cpu-total",
			"ident": "c3-ceph01.bj"
		},
		"value": 69.5
	}
]

Obviously, the outermost layer of the JSON is an array. If you only report one monitoring data point, you can omit the outer brackets and report the object structure directly:

{
  "metric": "cpu_usage_idle",
  "timestamp": 1637732157,
  "tags": {
    "cpu": "cpu-total",
    "ident": "c3-ceph01.bj"
  },
  "value": 30.5
}

The server will check whether the first character is [ to determine whether the reported data is an array or a single object, and automatically perform the corresponding Decode. If you feel that the content being reported takes up too much bandwidth, you can also do gzip compression on the Request Body in your program, and at the same time add the Content-Encoding: gzip header in the HTTP Header.

The meaning of each field can be Googled or asked GPT, with the keyword “meaning of fields in OpenTSDB data format”. I’ll briefly explain here:

• metric: The name of the monitoring metric, usually an English word with multiple words connected by underscores, such as cpu_usage_idle
• timestamp: Timestamp, in seconds, indicating the time when the monitoring data was collected
• tags: Labels, usually a map structure where the key is the label name and the value is the label value, used to describe various dimension information or meta-information of the metric
• value: The value of the monitoring data, usually a number, indicating the numerical value of the metric

🟢 Note the ident label. ident is an abbreviation for identity, indicating the unique identifier of the device. If there is an ident label among the tags, n9e considers that this monitoring data comes from a certain machine and will automatically obtain the value of ident and register it in Nightingale’s machine list.

Other commonly used interface paths:

• /openfalcon/push: Open-Falcon data receiving interface
• /prometheus/v1/write: Prometheus Remote Write data receiving interface

How to Authenticate

If your Nightingale is exposed to the public network, anyone can push monitoring data to you, which is obviously insecure. Therefore, we recommend:

• Do not expose Nightingale to the public network
• If you must expose it to the public network, use HTTPS protocol and enable Basic Auth authentication

How to enable Basic Auth authentication? Configure it in etc/config.toml:

[HTTP.APIForAgent]
Enable = true
[HTTP.APIForAgent.BasicAuth]
user001 = "Pa55word01"
user002 = "Pa55word02"

When your own program calls Nightingale’s interface to report monitoring data, your program acts as an agent, so it is related to the configuration of HTTP.APIForAgent.

• Enable under HTTP.APIForAgent must first be set to true to enable the related interfaces, otherwise calling those data reporting interfaces will return a 404 Not Found error.
• The configuration under HTTP.APIForAgent.BasicAuth is username and password, in the format username = "password". You can set multiple users. The authentication method for these users is Basic Auth. If no user is configured under HTTP.APIForAgent.BasicAuth, it means no authentication is required and anyone can push data.

🔴 Note: Right next to HTTP.APIForAgent there is also a HTTP.APIForService configuration section, used to provide some interfaces for n9e-edge, namely the edge data center deployment mode of Nightingale. If you don’t use n9e-edge, be sure to Disable HTTP.APIForService, that is, set Enable under HTTP.APIForService to false, to avoid security risks.