General Information

What is PiWeb?

PiWeb is a quality data management system capable of saving, managing, retrieving and analyzing quality inspection data. All data is available at anytime and from anywhere through web-services. Thanks to real-time data analysis, it is possible to react quickly to any problems within production. Further information can be found at ZEISS PiWeb.

What is the PiWeb API?

The PiWeb API provides the public interface of the web service through which various requests can be sent to PiWeb Server. You can create, manage and remove data, or retrieve relevant files and information from PiWeb Server. The used architecture is based on REpresentational State Transfer (REST).

The API fulfils two purposes:

• Purpose 1: Writing new measurement data / connecting measurement software to the system
  The interface allows you to write new measurement data to the database from software other than PiWeb itself. This enables communication between various measuring instruments and PiWeb Server.

• Purpose 2: Custom evaluation of measurement data
  Furthermore, the API offers the possibility to query and retrieve measurement data according to certain criteria, in order to be able to process them in a special way. This means that customer-specific evaluations which are not provided by PiWeb itself can still be executed with custom software. You can find information about the structure of API requests in this documentation.

The PiWeb API actually consists of two APIs:

Both APIs are versioned independently.

Domain Model

This section gives you an overview of the PiWeb domain model and explains common terminology used for the PiWeb API.

Inspection plan and measurements

The following image provides an overview to the inspection plan and its relations to measurements and measured values.

Inspection plan

The inspection plan specifies the structure of parts, characteristics and possible sub-parts and sub-characteristics. Because the included elements are related hierarchically they are normally displayed in a tree structure.

Part and root part

A part can represent a simple component up to a complex assembly. It describes a workpiece in general, i. e. the workpiece type. This means that real parts that are later measured do not occur individually in the system, but are assigned to the workpiece in form of a measurement. It is also possible to assign sub-parts to a part which can be repeated numerous times.

The uppermost part is the root part which has no parent. It typically contains sub-nodes like parts and characteristics which again may contain sub-nodes. The connected PiWeb Server always provides a root node, from which any arbitrary part or characteristic can be reached.

Characteristic

A characteristic can be described as a distinctive or important property of a part. Examples are bores, curves or oblong holes, i. e. places where accuracy needs to be checked. A characteristic can itself contain sub-characteristics, which can be repeated many times. An example would be a hole that contains diameter and coordinates.

Types of characteristics:

• Characteristic
  The basic characteristic that can be assigned to parts and other characteristics.
• Measurement point
  A characteristic which represents a point to measure, including coordinates and tolerance. These can only belong to a part and not to another characteristic.
• Calculated characteristic
  A special type which is based on at least two other characteristics and a calculation rule to determine the value. It can contain other basic or calculated characteristics, but no measurement points.
• Calculated measurement point
  A special type of measurement point that can be used to calculate distance, symmetry or offset of two other points.

Measurement

A measurement is a specific measurement process that can affect several characteristics. For example, if an inspector measures a part and records one, several, or all existing characteristics, this procedure and its values describe a measurement. Not all characteristics need to be measured. A measurement always belongs to only one part, deleting the part also removes the measurements.

Measured value

A measured value describes an actual measured or recorded value that is assigned to a characteristic or attribute. Multiple measured values are collected in a measurement. Values can be numerical, e. g. a simple floating point number, attributive or enumerated.

Values of attributive characteristics can be categorized. An example would be the result of a quality inspection, which can either be passed or failed. These categories can be counted, so in this case the number would be two.

Enumerated characteristics are those that consider the number of a certain characteristic. If you examine a painted component for damaged spots, you can also count the occurrences. If the part has two damaged spots, this again represents a category, namely the parts with the exact number of two defects. These characteristics are therefore not “measurable” in the conventional sense.

Example of inspection plan with measurements

The following picture shows an example of an inspection plan and related measurements containing measured values. The inspection plan contains the target value while the measurements provide the actual measured values.

Entity details

In the following diagram the already explained domain terms part, characteristic, measurement and measured value are displayed with the more general term Entity. An entity is an object that has certain properties and interaction possibilities. Entities form the center of the logic that runs within the system.

Additional data

Additional data are files that can be attached to any entity in the inspection plan. This can be text files, images, log files, CAD models or any binary file. There is no limit to the number of files. They can be edited or removed as necessary.

Attribute value and catalog entry

Each entity can have several attribute values which can be seen as their properties. Such a value can have the data type string, integer, floating point, data and catalog. The last data type belongs to the specific attribute value, the catalog entry whose possible values are defined in a catalog.

Attribute

An attribute defines an attribute value including its data type and key. Each specific attribute defines where they can be used. For each of the four entities a separate type of attribute exists: part attribute, characteristic attribute, measurement attribute and measured value attribute. Examples for part attributes are: part ID, factory area and short description. Examples for characteristic attributes are: characteristic ID, upper limit and target value. Additionally it is also possible to specify attributes for a catalog entry which is an catalog attribute.

The unique key of an attribute is important, as it has the purpose of an identifier for PiWeb attributes. The time/date attribute as an example has the key K4. PiWeb already knows a lot of important attributes and their keys by default, which is why changing them is not advised.

Here are some examples for common attributes known by default:

• Measured value: K1
  The attribute of a measured value, which contains the actual value.
• Time/Date: K4
  The date of measurement.
• Target value: K2100
  The desired value a characteristic should have, to which the actual measured value should be as close as possible
• Lower/Upper limit: K2110/K2111
  The limit of acceptable tolerance between the target value and actual values.
• Lower/Upper control limit: K8012/K8013
  A limit that determines when actions regarding production should be taken based on the number of bad parts
• Lower/Upper warning limit: K8014/K8015
  A limit that determines when a warning about bad values should be triggered

Configuration

In the PiWeb configuration attributes can be defined ready to be used at parts, characteristics, measurements, measured values and catalog entries. The available catalogs and their contained catalog entries are specified as well.

Catalogs

Catalogs represent a collection of different values. An entry has a number and can have several other attributes. Catalogs are used to simplify decisions at certain points by specifying the available values. The user does not have to enter data by hand, and cannot cause unintended typing errors.

An example would be the machine catalog. This contains the different machines which could be used to measure a part. Additional information for each machine can be noted there too. Now an inspector selects the responsible machine from the catalog when entering a measurement, which makes things a lot easier. Other values than those stored in the catalog are not possible. Also simple variants, like the direction catalog, which contains directions like left and right, are possible.

Services

DataService

The REST DataService is the endpoint for everything related to PiWeb data like parts, characteristics, measurements, measured values, attributes and catalogs. Creating, managing and removing data is done using requests sent to this service.

The base address is:

http(s)://serverHost:port/instanceName/DataServiceRest

For further information see the DataService documentation

Raw Data Service

Use the RawDataService to fetch, create, update and delete additional data, i.e. raw data.

The base address is:

http(s)://serverHost:port/instanceName/RawDataServiceRest

For further information see the RawDataService documentation

instanceName and https are optional and depend on the server settings.

Versioning

How is the PiWeb API versioned?

PiWeb uses Semantic Versioning (SemVer) for its APIs. The REST API, its services and the .NET SDK are versioned independently. The version consists of three components in X.Y.Z format, e.g. 2.4.1. According to this order, the components are Major, Minor and Patch, which have the following meaning:

• Major: Incompatible Change (Breaking Change)
  If the major version changes, we implemented a change that is not compatible with older API versions. This means that the changed functionality is only supported as of this major release. Examples are changes in the behavior of methods, addition of non-optional parameters or changing data types.

• Minor: Compatible Change
  A change to the minor version indicates the addition of a backwards compatible feature. This means that existing features and their usages still return the expected results. Software with an older version can communicate with the newer version, unsupported features are marked as such.

• Patch: Compatible Bugfix
  The change of this version number indicates a patch, i.e. fixing of internal errors or bugs. This is downward compatible and has no relevance regarding the API interface.

A list of changes can be found in the release notes.

How do I get the API versions supported by PiWeb Server?

The .NET SDK has a global version, depending on your chosen NuGet package or GitHub source files.
The REST API instead doesn’t have a version as a whole, each service has its own version.
You can find out the supported service versions by making a GET request to its base URL:

http(s)://ServerHost:Port/instanceName/dataServiceRest
or
http(s)://ServerHost:Port/instanceName/rawDataServiceRest

Response:

{"supportedVersions":["1.4.4"]}

Formats

Input and output format

The input and output format is JSON. A sample JSON representation of a part in PiWeb:

{
    "path": "P:/metal part/",
    "charChangeDate": "2014-11-19T10:48:32.917Z",
    "attributes": { "1001": "4466", "1003": "mp" },
    "uuid": "05040c4c-f0af-46b8-810e-30c0c00a379e",
    "version": 0,
    "timestamp": "2012-11-19T10:48:32.887Z"
}

Encoding

Since PiWeb 7.8 the default encoding for strings like the part path is UTF-8. The Content-Type header of incoming messages indicates this as well:

Content-Type: application/json; charset=utf-8

For PiWeb versions before 7.8 the default encoding depends on the machine where the PiWeb Server is running, so it is necessary to use the correct encoding conversion according to your environment, if your chosen tool or script language does not work directly with present encoding.

Security

Access to PiWeb Server service might require authentication. Authentication can be either basic authentication based on username and password, Windows authentication based on Active Directory integration, certificate authentication or OpenID connect authentication. Our .NET SDK (C# API) offers convenient functionality to use all possible authentication methods, corresponding documentation can be found in the security section of the .NET SDK. When accessing the PiWeb API via REST using different clients (e.g. Python), it can be necessary to use 3rd party libraries or to implement authentication methods yourself. We do not offer detailed documentation on how to do this, instead you can find further information following provided links.

Basic authentication

If PiWeb Server is secured by basic authentication you have to pass the credentials in the HTTP authorization header. The authorization header must contain the Basic key word followed by base64 encoded user:password string:

Authorization: Basic QWRtaW5pc3RyYXRvcjphZG0hbiFzdHJhdDBy

Windows authentication

If PiWeb Server is secured by Windows authentication you have to follow the Kerberos protocol to authenticate your client. This is easy using our .NET SDK (C# API). For different clients (e.g. Python) this can be more complex, we suggest to use available libraries.

Certificate authentication

If PiWeb Server is secured by certificate authentication you have to provide a valid X.509 certificate of an authorized user along with the REST request.

OpenID connect authentication

If PiWeb Server is secured by OpenID connect authentication you have to obtain an access token and pass it in the HTTP authorization header. The access token can be obtained from an OpenID Issuer. The OpenID issuer URL is provided by a helper endpoint. Invoke a GET request on this endpoint without any authorization header.

http(s)://serverHost:port/instanceName/OAuthServiceRest/oauthTokenInformation

A JSON response with the following format will be returned.

{"openIdAuthority":"https://issuerHost:port/basePath"}

The OpenID issuer URL can be used together with the OpenID connect specifications to obtain an access token. You can use a OpenID connect client library to help dealing with all the details. Following a short description together with the PiWeb specifics.

First use OpenID connect discovery to get the URL of the authorization and token endpoints. Then you can use the OpenID connect specification to get an access token.

The authorization flow used by PiWeb is the Authorization Code Flow + PKCE. You need to specify the client id “f1ddf74a-7ed1-4963-ab60-a1138a089791” and the scope “piweb”. Additionally the scopes “profile”, “email” and “offline_access” are supported as well. The redirect_uri is “urn:ietf:wg:oauth:2.0:oob”.

The obtained authorization code, the PKCE code verifier and the client secret “d2940022-7469-4790-9498-776e3adac79f” are sent to the token endpoint which returns an access token.

The access token can be used to authenticate requests to PiWeb services. PiWeb server uses the authentication scheme “Bearer” for OpenID connect authentication. The HTTP authorization header must contain the scheme “Bearer” as well as the obtained access token.

GET /DataServiceRest/serviceInformation HTTP/1.1
Authorization: Bearer access_token

The access token is valid for 1 hour. When the access token has expired you need to obtain a new access token. The expiration date can be obtained by client from the access token itself. The access token is a JSON Web Token as defined in RFC7519 and contains the claim “exp” defining its expiration date.

URL and Parameter

You can restrict requests by attaching certain parameters to the webservice URL in the following format:

?parameter=value[&parameter=value]

Example:

?deep=true&order=4 asc

If the parameter contains lists of ids it needs to be surrounded by { and }, the values within the list are separated by ,.

Best practice: Encode the URL

As some parameter definitions may contain special characters like brackets, space or plus sign it is highly recommended to encode the URL before sending requests to prevent unexpected behaviors.

Status Codes

The following table shows different HTTP status codes and the possible reason that caused it.

Response

Every response consists either of the requested data or of an error message returned by the webservice. A typical error response looks as follows:

{
   "message": "Unable to insert inspection plan items. An item with path '/metal part/'
               [uuid: 05040c4c-f0af-46b8-810e-30c0c00a379e] does already exist."
}