API News

Permission Inheritance

Nodes, instrumentations and assets automatically get their parents' permissions. Furthermore all permissions in the hierarchy of node, tags, assets and documents will be passed down.

  • instrumentations, assets and documents inherit permissions from nodes they are linked to
  • assets and documents inherit permissions from instrumentations they are linked to
  • documents inherit permissions from the assets they are linked to

As a consequence of this, to connect nodes, instrumentations assets and documents with each other, the user needs update permission on the parent object and permit permission on the child object (e.g. to link an asset to a node, the user needs update permission on the node and permit permission on the asset)


Translations For Master Data

We have updated our API to provide translatable master data across all life-cycle-objects:

  • Statuses
  • Types
  • Categories
  • Classifications
  • Products
  • Documents

When you post a new instance the properties name and description are stored as English texts by default. In order to create a translation for name or description set the content-language in the request header and send the translated attribute in the body of a normal patch call on the instance. Use the new property code to identify the resource.

To get language specific content set accept-language in the request header to e.g. de. You can set several languages to indicate the desired order (e.g. ja, fr) to receive contents in Japanese and if not available, then in French. The fallback language is English. Currently we offer the predefined master data in English.

This feature is available as of now on the staging environment and on production from the 5th of November.

Switch from name to code

For the above listed objects we are about to publish translations for German. Translatable properties are name and description and the new property code is introduced to identify the resources. There is one exception, of course: The Products identifier is still the product_code.

If your application works with a specific name of one of the above listed resources, please switch to code to identify the resource. The code is by default the English name in lower snake-case. (e.g. Name: 'Out of Specification', code: 'out_of_specification')

We will add the German translations on staging environment on the 14th of November and on production on the 28th of November.


SSL certificate replacement

Due to security changes in Google's Chrome browser which will become effective on April 17th 2018, we will replace our SSL certificates on April 9th 2018 with Let's encrypt certificates.
https://letsencrypt.org/

Please ensure that your applications using our API can handle this certificate replacement before April 9th, 2018.

Test your applications against our staging environment that already features a Let's encrypt certificate:
https://api.netilion.endress.com/

In case you access the API via other URLs than these below, please be aware they will become unavailable soon.

Official URLs to use :

  • Staging: https://api.staging-env.netilion.endress.com/
  • Production: https://api.netilion.endress.com/


Order By

Asset, Instrumentation and Node endpoints now have an order_by parameter. The result list can be sorted by the following attributes:

  • Assets: id, serial number, updated_at and created_at
  • Instrumentations: id, tag, updated_at and created_at
  • Nodes: id, name, updated_at and created_at

    By default the sorting order is ascending. For descending order add a "-" before the attribute.

  • Assets ordered by serial number ascending: /assets?order_by=serial_number
  • Assets ordered by serial number descending: /assets?order_by=-serial_number

Parent Filter

For objects that can have a parent as Assets, Instrumentations, Nodes, etc the parent filter now supports null and not null values:

  • Return all nodes without parent: /nodes?parent_id=null
  • Return all nodes with parent: /nodes?parent_id=!null

Deployed on April 17th 2018


Vector data

A new feature to store and historicise data, additional to the existing Asset Specifications is available on the 20th February 2018: the API now offers as new format for Asset Specifications:

 { "event": {
  "source_timestamp": "2022-01-01T00:00:00",
"unit": "vector",
"value": [
   {
     "FLOW_Out1Value_1": {
      "value": "47.33",
      "unit": "l"
    }
   },
   {
     "SU_MassFlow_1": {
       "value": "4"
     }
   }
  ]
 }
}

In order to save vector data the unit of the specification object must be "vector" as shown in the example above.

Vector data is suitable to store at once several values of a measurement event e.g. HeartBeat data. Over time the collection of Vector Data Objects can be visualised and used for further evaluation of the measurement values.

It is a compatible change in the API that will be available on production environment on Tuesday, 20th of February 2018. The change is available on the staging environment as of now.


Data privacy

Due to privacy and security issues we will deploy a change in the API on Tuesday, 12th of December 2017.

It affects the response body of the following endpoints:

GET /v1/usergroups/:id/users GET /v1/userroles/:id/users GET /v1/tenants/:id/users GET /v1/tenants/:id/admins

Currently the response body contains detail information of the users, including email, post address etc. After the change the response will contain only id, first name, last name and the links to further user resources.

Additionally the ability to filter by email address on the affected endpoints will be removed.

These changes will bring additional security to our API and prevent misuse.