Introduction to the API, part 3: set the current value of a parameter

Introduction

The first article in the API series involved requesting a single attribute, currentValue, from a parameter. This time, we will update the current value of the parameter. This can be a handy way to add a manual reading to a parameter, or to send test values to trigger alarms.

Step 1, get Postman

We will assume that Postman has already been set up; please see the first article in the API series if revision is required.

Step 2, get an API key with modify permission

The API key which we used the previous article was a modify key. As we now intend to update the current value of the parameter, we can reuse that same modify key. Therefore, our example API key for the rest of this article will be BBB777888999, but as before, any API key that you generate in your own account will actually look a lot longer and more random than this.

Step 3: identify a node ID

This step is exactly the same as the previous article. We will use the same temperature parameter as before, with a node ID of 613603901b5a610f7f5d8572. If you are going to use one of your own parameters, remember that when this API request is successful, you will have added to the historical data series. So be sure to use a test parameter, or be ready to delete the new value using data editing.

Step 4: create the API request with Postman

Create a new, untitled request:

In the field labeled Enter request URL, we need to enter the correct URL to access the parameter node. The API request we will use is titled Update node historic data with a single value in the documentation, and is described like this:

PUT /api/v1/nodes/:id/historic/now

This is a shorthand way for the documentation to tell us it will be a PUT request, and how to construct the URL. Our untitled request in Postman is currently a GET request, so we need to change that to a PUT request:

To construct the request URL, we always start with https://api.eagle.io and then add the specific request path from the documentation, which in this case is /api/v1/nodes/:id/historic/now However, the :id portion is shorthand for the real node ID of our parameter, so we need to substitute that. The full URL will therefore be:

https://api.eagle.io/api/v1/nodes/613603901b5a610f7f5d8572/historic/now

We must also enter the API key. This is done by clicking Headers, then entering a key of x-api-key and a value that matches your API key; in this example, it is BBB777888999.

After entering the request URL and the API key, Postman should look like this:

Since this is a PUT request, we also need to construct the body of the request. This represents the data that will be used to update the node. The body will be in JSON format, so click Body, then click raw, click Text, and choose JSON from the drop-down list:

In the window, we can now enter the JSON data which will comprise the body of the request. The simplest option is to just supply a value. In this example, the value will be 10, so the JSON body looks like this:

{
    "value": 10
}

In Postman, it will look like this:

Step 5: send the request

Now that we have the URL, API key and request body in place, it's time to send the request by clicking the Send button.

After sending the request, the first thing to check is the status of the response, which should be 202 Accepted:

We can then confirm that the current value of the parameter was updated by looking at the parameter in eagle.io list view:

Success!

Step 6: additional fields

The documentation for this API call shows us that additional fields can be sent as well as (or even instead of) the value field. The full list of fields are value, quality, annotation and timestamp. If timestamp is omitted (as it was in the previous example), the time the request was made will be used. If timestamp is specified, then any existing record with the same timestamp will be overwritten.

Lets make another API request, but this time specify all of the fields:

{
    "value": 11,
    "quality": 149,
    "annotation": "test value sent via API",
    "timestamp": "2022-08-24T08:00:00Z"
}

The request and response look like this in Postman:

We can then confirm the new current value of the parameter, as well as the quality code, by looking at the parameter in eagle.io list view:

If we also want to view the annotation, we can switch to chart view:

Note that the timestamp sent by the API request, 2022-08-24T08:00:00Z, was in UTC time zone, and is converted to the viewer's local time zone when shown in an eagle.io view.

Step 7: convert this Postman example to code

As with previous API articles, we can generate a code snipped by clicking the </> button. Since the previous articles both showed Python code, we'll change it up this time and look at a Ruby code snippet instead:

As usual, any auto-generated code such as this should be regarded as only an example or starting point, and doesn't replace the need to have an understanding of the coding language in general and HTTP clients in particular.

Further reading

For more details about updating a node with a single value, please see the full documentation for this API endpoint.