This section will be kept up-to-date and extended over the time.
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 :
For traceability and functional reasons, each single modification of data is tracked. For any modification will be kept the following :
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 :
User-defined values :
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:
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.
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 :
Name
Tenant ID
Manufacturer ID
Product
Product ID
Serial Number
Name
Document Status
Name
Status
Type
Assets
Name
Type
The API documentation offers full functionality of the API to test and run single requests.
Just try :
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 :
Date and DateTime format have to be provided in ISO 8601 format (in both request and response).
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.
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.
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.
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:
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>
Beside the links the following information is provided concerning pagination in header and body :
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.
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:
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.
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.
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.
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.
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:
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
}
}
querying a resource will respond with a list. If nothing was found with the given query-parameters, an empty list will be responded.