using the sort parameter in the API

[BladeWDR]

I'm using the zfs/snapshot API endpoint specifically, and I'd like to sort the resulting JSON chronologically.

What values does this parameter accept? I've tried "name", "date", assuming that it wants specific keys from the JSON data.

All of them come back with 422 Undocumented.

 

[anodos]

I'm using the zfs/snapshot API endpoint specifically, and I'd like to sort the resulting JSON chronologically.

What values does this parameter accept? I've tried "name", "date", assuming that it wants specific keys from the JSON data.

All of them come back with 422 Undocumented.

422 typically would mean that you submitted invalid payload. Exact behavior depends on whether you're using the websocket or REST API. In latter case you can look at our REST CI tests for code / payload samples.

middleware/tests/api2/test_438_snapshots.py at bcdbe80051faac5c2952f3de19872c3af8b1da2a · truenas/middleware

TrueNAS CORE/Enterprise/SCALE Middleware Git Repository - truenas/middleware

github.com

query-filters and query-options are covered in our existing API docs and should be carefully reviewed.

WARNING: if you're planning to poll on these interfaces you will need to do some serious testing / planning (querying snapshots willy-nilly is a sure way to kill performance).

 

[anodos]

The fastest way to sort in chronological order is to request only names and createtxg and order by the latter.

 

[BladeWDR]

The fastest way to sort in chronological order is to request only names and createtxg and order by the latter.

Appreciate the replies!

I'm testing this against my backup server so no worries.

I probably should have specified that I'm using the REST API, right.

This is going to be used for Nagios monitoring checks eventually, but right now I'm just playing around with the functions in the API I want to use to get a better idea of how they work.

This command works:

curl -vk -H "Content-Type: application/json" -H "Authorization: Bearer APIKEY" \ ─╯ -X GET "https://truenas.domain.com/api/v2.0/zfs/snapshot" \ -d '{"query-filters": [["dataset", "=", "Pool_1/personal"]],"query-options": { "extra": { "properties": "name, createtxg"}}}'

But adding the "sort" parameter makes it break, giving me a errno 22 response, "field was not expected."

curl -vk -H "Content-Type: application/json" -H "Authorization: Bearer APIKEY" \ ─╯ -X GET "https://truenas.domain.com/api/v2.0/zfs/snapshot" \ -d '{"query-filters": [["dataset", "=", "Pool_1/personal"]],"query-options": { "extra": { "properties": "name, createtxg"}, "sort": "createtxg"}}'

I also tried adding the parameter to the API URL like below, but same error.

https://truenas.domain.com/api/v2.0/zfs/snapshot?sort=createtxg

 

[anodos]

sort isn't a query-option. `order_by` is. C.f. documentation: https://github.com/truenas/middlewa...dlewared/apidocs/templates/websocket/query.md

 

[BladeWDR]

sort isn't a query-option. `order_by` is. C.f. documentation: https://github.com/truenas/middlewa...dlewared/apidocs/templates/websocket/query.md

That helps a lot, thanks.

This worked:

curl -vk -H "Content-Type: application/json" -H "Authorization: Bearer $apikey" \ -X GET "https://truenas.domain.com/api/v2.0/zfs/snapshot" \ -d '{"query-filters": [["dataset", "=", "Pool_1/personal"]],"query-options": { "extra": { "properties": "name, createtxg"}, "order_by": ["createtxg"]}}'

Bearing that in mind, what's the point of this "sort" parameter then? See the attached screenshot from the REST API documentation.

I don't see "order_by" referenced anywhere in those docs.

 

[anodos]

That helps a lot, thanks.

This worked:

curl -vk -H "Content-Type: application/json" -H "Authorization: Bearer $apikey" \ -X GET "https://truenas.domain.com/api/v2.0/zfs/snapshot" \ -d '{"query-filters": [["dataset", "=", "Pool_1/personal"]],"query-options": { "extra": { "properties": "name, createtxg"}, "order_by": ["createtxg"]}}'

Bearing that in mind, what's the point of this "sort" parameter then? See the attached screenshot from the REST API documentation.

I don't see "order_by" referenced anywhere in those docs.


View attachment 75941

Hmm... that might be some broken documentation.

That said, if this is in context for nagios checks, then you may want to use a persistent websocket connection (polling REST APIs is going to hurt performance as well).

 

[BladeWDR]

Hmm... that might be some broken documentation.

That said, if this is in context for nagios checks, then you may want to use a persistent websocket connection (polling REST APIs is going to hurt performance as well).

I was only going to have it check once every 12 hours or so, maintaining a connection for the websocket seemed wasteful.

The purpose of it is just to make sure that replication isn't for some reason falling behind. I also have alerts set up in TrueNAS itself, but I've learned the hard way not to rely on email.

I have been wondering if I should set up a passive check in Nagios instead, and use a cron job on the TrueNAS side to run a script that does all this just using zfs list and some bash, but using the API seemed more fun at the time. :D

 

[anodos]

I was only going to have it check once every 12 hours or so, maintaining a connection for the websocket seemed wasteful.

The purpose of it is just to make sure that replication isn't for some reason falling behind. I also have alerts set up in TrueNAS itself, but I've learned the hard way not to rely on email.

I have been wondering if I should set up a passive check in Nagios instead, and use a cron job on the TrueNAS side to run a script that does all this just using zfs list and some bash, but using the API seemed more fun at the time. :D

You can use nagios to query the alert.list endpoint as well. This will get you alerts from the NAS. BTW, alert.list is also a subscribable event and so you could have your monitoring solution subscribe to it and receive alerts in basically realtime (if you maintain a websocket connection).