Best Practice



This section will be kept up-to-date and extended over the time.

1. General information

Access and submit Life Cycle Business Objects in your software applications through our API (Application Programming Interface).

The API type is REST/JSON. Through this, session handling is avoided as each request contains needed authentication information and a high amount of requests can be handled.

This API is the one and only way to access this data. The API and the data model builds the base ouf our Netilion Hub.

The Life Cycle Business objects can be subject to the following actions :

  • Create (POST)
  • Read (GET)
  • Update (PATCH)
  • Delete (DELETE)

For traceability and functional reasons, each single modification of data is tracked. For any modification will be kept the following :

  • Old Value
  • Modification date
  • Modification event (create, update, delete)
  • User that initiated the modification
  • API-Key used to initiate the modification
  • Version count of modification

Object Attributes and values

Plant Business Objects which can be stored and accessed within the Data Information Hub are defined by specific attributes and values.

Let's take the example of an asset's attributes and values :

Definition : An asset represents a produced instance of a product issued a from defined manufacturer. It represents a good of a certain value and is defined by a serial number. The asset is identified by the combination of serial number and manufacturer.

Partly predefined values :

  • Asset ID : an unique system ID which is automatically assigned.
  • Asset Status : a status with which you can categorize your Asset, e.g. Undefined, Active, Inactive, Failure, Defective or any self-defined value.
  • Documents : asset-related files as PDFs, configuration XMLs, CAD drawings or whatever you want to upload.
  • Events : asset related incidents defined by a point of time as calibration, repair or more.
  • Nodes : self-defined plant structure as site, location, application, bus, loop and more.
  • Instrumentations : self-defined functional place within your plant, e.g. measuring point
  • Pictures

User-defined values :

  • Specifications : value detailing your asset in a specific way by a key-value pair, which allows a great flexibility, e.g. primary measuring value, communication type and whatever you may need to store, defined by your own key.



2. Data access and ownership (permission management)

The data you create within the NAME LCM Information Hub belongs to you. Therefore, there are strict regulations applied on the access to your data, in concordance with the EuroCloud StarAudit (find out more in the Terms of Service and Legal section).
This also means that the data you are able to access is restrained to yours, enriched with Endress+Hauser information. Consequently, the responsibility of the permission management is in your hands. Only you decide and set whom access to your data is given, whether to specific users or user groups (see example below for the Analytics app).

Initially, owner permissions are provided to the object creator, which means Read, Update, Delete, Permit. Access to created objects for other users can only be provided by the object's owner (creator). Therefore, all permissions provided to other users or user groups need to be assigned separately, this may be done through the API with the method Permission.

By the reverse way, if you would like to access others' objects, their owners will need to provide permissions on your account.

Different levels of permission exist:

  • Read : this permission only allows reading of the data set. No changes can be made on the data set by the specified user with "Read" permission.
  • Update : this permission reading and edition of the data set. Nevertheless, the data set can't be deleted by the specified user with "Update" permission.
  • Delete : this permission allows reading, edition and deletion of the data set.
  • Permit : this permission allows reading, edition and deletion of the data set. In addition, the specified user can also provide permissions to the data set to additional users.

Permission inheritance is also given.

The platform is designed for multi-tenancy. Each tenant (a group of users within a department, company or even cross-company) contains attributes and master data relative to the respective data sets created by users within this tenant. E.g. created manufacturers or products are available only within the tenant they have been created, with the exception of Endress+Hauser products.


3. Dependencies

When creating plant objects, often dependencies exist and some other objects are needed as a precondition (mainly attributes).

As an example : When a new product is created, it is necessary to have its manufacturer created first so that manufacturer can be assigned for the product creation.

Dependencies can also be seen for each object within the API documentation :

Some examples of mandatory attributes :

  • Manufacturer : NameTenant ID

    • Product : Manufacturer IDProduct

      • Asset : Product IDSerial Number

  • Documents : NameDocument Status

  • Event : NameStatusTypeAssets

  • Nodes : NameType




4. Test and validate your requests using the API Documentation

The API documentation offers full functionality of the API to test and run single requests.

Just try :

  • Set up your instrumentation (e.g. TAG F-112, flocculant dosage)
  • Create assets (e.g. Endress+Hauser flow measurement transmitter or Parker valve)
  • Structure your data using nodes. No limitation on the hierarchy (locations, buses...)
  • Add or access product and asset specifications (measuring ranges, certificates, documentation...)

Registration is necessary to get a valid API key for using the API documentation. Register here

Please keep in mind that object dependencies exist to ensure a consistent data structure, more information above.


Example of the possible methods and actions within the API Documentation :





5. Date and time format

Date and DateTime format have to be provided in ISO 8601 format (in both request and response).

  • Year : YYYY (e.g 2016)
  • Year and month : YYYY-MM (e.g 2015-06)
  • Complete date : YYYY-MMM-DD (e.g 2026-06-13)
  • Complete date plus hours and minutes : YYYY-MM-DDThh:mmTZD (e.g. 2016-06-13T19:20+01:00)
  • Complete date plus hours, minutes and seconds : YYYY-MM-DDThh:mm:ssTZD (e.g. 2016-06-13T19:20:30+01:00)

YYYY = four-digit year
MM = two-digit month (01=January, etc.)
DD = two-digit day of month (01 through 31)
hh = two digits of hour (00 through 23) (am/pm NOT allowed)
mm = two digits of minute (00 through 59)
ss = two digits of second (00 through 59)
TZD = time zone designator (Z or +hh:mm or -hh:mm)

DateTime should only be used if this detail is really needed, otherwise Date is sufficient. DateTime should always be stored as UTC (Universal Time Coordinated) in the database and UTC will also be used on all responses. Incoming POST/PUT requests with DateTime can have a timezone but will be converted to UTC before being saved.

Partial Dates

If the date can't be specified in every precision (e.g production_date on Asset), the Date will be saved as date Field in the database with an extra column defining the format of the date precision.

For example, if only the production month and year is known, the format should be saved as "%Y-%m". Before sending the date in a response, the date should be formatted according to this information. The model has to take care of the setting of the date format. This solution allows to benefit from the ActiveRecord/SQL capabilities, but enables the Netilion Hub to handle partial date information.

Querying Dates

When querying or filtering, partial dates should also be supported where suitable. The query format must match the date format in the database. For example, the query :

GET https://host/v1/assets?production_date=2016-06

should only return the assets, where the production date was set to 2016-06, not the the assets the have the additional day information available. If all assets, produced in June 2016 should be querried, the date range query

GET https://host/v1/assets?production_date_from=2016-06-01&production_date_to=2016-06-30

should be used.


6. Pagination

Requests that return multiple items will be paginated to 25 items by default. You can specify further pages with the page parameter. You can also set a custom page size up to 100 with the per_page parameter Page numbering is 1-based and that omitting the page parameter will return the first page.

The pagination link info is included in the response body and in the Link header.

See possible relation values:

  • next : The link relation for the immediate next page of results.
  • prev : The link relation for the immediate previous page of results.
  • first : The link relation for the first page of results.
  • last : The link relation for the last page of results.

Link: https://api.netilion.endress.com/v1/assets?page=3&per_page=100; rel="next",
https://api.netilion.endress.com/v1/assets?page=?page=50&per_page=100; rel="last"

Body :

{
  "pagination": {
      "next": "https://api.netilion.endress.com/v1/assets?page=3&per_page=100",
      "last": "https://api.netilion.endress.com/v1/assets?page=?page=50&per_page=100",
  }
}

<br>
<br>

Further pagination data

Beside the links the following information is provided concerning pagination in header and body :

  • total_count : Total items in the result collection
  • page_count : number of pages (only in body)
  • per_page : items per page
  • page : current page


7. Filtering (to be extended)

Endpoints that return a list of objects can be filtered by the objects fields (excepting the field description). As an example for product this would be name and product_code. Filters are appended as query parameters by name and search term.

/products?name=Liquiphant&product_code=FTL51

The search will return products that match the search terms ignoring its case. It is also possible to use wildcards (as asterisk) in the search term.

/products?name=liqui*&product_code=*A2B

This would provide products that have a name starting with "liqui" and the product_code ending with "a2b". Case of the search terms are also ignored.




8. Caching

Conditional HTTP Caching

It is not intended that a client blindly caches content. Instead the client should ask the server whether or not a resource has been updated. HTTP provides the ability to do this with conditional caching. A client can make a request to the server and check if the server has a new version of the resource available. If the resource did not change, the server will respond with http code 304 - Not Modified and no body. Otherwise the server will respond with http code 200 - Success and the up-to-date response within the body.

The Netilion Hub supports conditional caching on all endpoints that return a single resource (e.g. /v1/assets/{id}) and specification endpoints (e.g. /v1/assets/{id}/specifications)

Conditional HTTP Caching does not reduce the number of http requests by a client but due to the skipping of the rendering process of unmodified resources, the server can respond faster, the responses are much lighter (no body) and server load will be reduced.

There are two headers to support this:

  • ETag

When a response is returned by the server, it will include an ETag (entity tag) as HTTP response header. Subsequent HTTP requests asking whether the resource has changed since the last request can send the stored ETag via the If-None-Match header.

  • Last-Modified Timestamp

The second header is the Last-Modified header. This will return a timestamp of the last resource modification. The client can then include an If-Modified-Since header with the Last-Modified timestamp value to ask the server if the resource has been modified since the previous request.

  • Conditional Caching and includes

The verification whether the resource did change since the version, identified by ETag or Timestamp, only considers the resource itself, not the resource that may be included in the response by the include parameter.

For example, if the client requested the asset with ID 42 including the product via /v1/assets/42?include=product and uses the returned ETag in another request to the same URL, the server will send http code 304 - Not modified even if the name of the product did change in the meantime, as the requested resource (asset with ID 42) did not change. If the client wants to be sure that all the fields even from the included resources are up-to-date, no conditional cache header should be send within the request.

  • General response caching

The stale method is only implemented for the show methods. For any other GET request, the default handling of caching works as defined in the following. If the client sends an ETag, the server creates the response body and creates an ETag for this body. The calculated ETag of the server and the ETag from the client request are compared. If they match, the server returns http code 304 - Not modified. This way of caching is not as fast as the stale check as the response body must be created on the server, to build the correct ETag, even if it's not part of the response sent to the client.


9. Http Status codes

The Netilion Hub makes use of following HTTP status codes types:

•2xx for successful requests
•4xx for client side errors
•5xx for server errors

The creation/update of a resource with missing associations will return a 400 status code although a 404 could be expected:

  • JSON:API defines it with 400 http://jsonapi.org/format/#crud-updating-responses-404
  • mandatory 1:n errors can have different causes (e.g.: "sender is mandatory, no sender was given or the given sender was not found")

Request/Response Objects

When creating a new object, the linked objects should sent by using a sub-document with the referred id included. See:

{
  "name": "New child object",
  "parent": {
    "id": 4
  }
}
  • ids are always integer (int64) with possibly 19 digits.
  • querying a resource will respond with a list. If nothing was found with the given query-parameters, an empty list will be responded.