Data Service

Release Notes

1.3.0
Features
  • Endpoint for getting characteristics was changed: Restriction by part uuids was removed and restriction by characteristic uuids was added.
  • Until now to change catalog's valid attributes, the catalog needed to be deleted an re-created again. This can be done by calling update endpoint, now.
  • Endpoint for fetching measurements was extended by mergeAttributes parameter.
  • New endpoint for searching measurement attributes.
  • Added HTTP caching to inspection plan search.
  • Added caching logic on server to increase performance on fetching configuration or catalog(s).
Bugfixes
  • Characteristics containing measurement values can be moved, now if parent part has not changed.
  • If versioning enabled all attributes were deleted if a characteristics was moved.
  • It was possible to create a catalog with an empty uuid.
  • Path names colid extend maximum length of database cloumn.
  • It was not possible to delete mlitiple catalogs at once.
  • Restriction by LastModified parameter on fetching measurements did not work.

Interface Information

Endpoints

Information about supported interface version can be fetched calling the root endpoint of DataService:

Example Example: Get interface version for Data Service
Request
GET /dataServiceRest/ HTTP/1.1
Response
{"supportedVersions":["1.4.2"]}

Object Structure

Interface information returns the highest available minor version of each major version. This lets the user decide which features can be used. As a minor version is backwards compatible to all previous minor versions, there is no point in enumerating them all. An user want to know which revision of each major version is available as that means they can work around possible bugs of older revisions.

Service Information

Endpoints

The service information can be fetched using the following endpoint. This endpoint doesn’t provide filter parameters.

Example Example: Get Service Information for a given connection
Request
GET /dataServiceRest/serviceInformation HTTP/1.1
Response
{
   "serverName": "PiWeb Server",
   "version": "5.6.2.0",
   "securityEnabled": false,
   "edition": "PiWebDB",
   "versionWsdlMajor": "2",
   "versionWsdlMinor": "9",
   "partCount": 4,
   "characteristicCount": 125,
   "measurementCount": 20,
   "valueCount": 900,
   "featureList":
   [
      "MeasurementAggregation",
      "DistinctMeasurementSearch"
   ],
   "inspectionPlanTimestamp": "2014-11-24T16:08:58.812964+01:00",
   "measurementTimestamp": "2014-11-03T10:27:28.3461853+01:00",
   "configurationTimestamp": "2014-11-03T10:27:27.5245116+01:00"
}

Object Structure

Service information requests always have the smallest response time and are therefore well suited for checking the connection. Fetching the service information doesn’t require authentication.

The returned ServiceInformation object has the following properties:

Property Description
string serverName The name of the PiWeb server as specified in the server settings
string version The version number of the PiWeb server
bool securityEnabled Indicates whether authentication is required by the server
string edition The database edition. Usually this is “PiWebDB”
string versionWsdlMajor The major version number of the interface
string versionWsdlMinor The minor version number of the interface
int partCount The estimated number of parts stored on the server
int characteristicCount The estimated number of characteristics stored on the server
int measurementCount The estimated number of measurements stored on the server
int valueCount The estimated number of measured values stored on the server
Features featureList A list of features supported by the server. This can be MeasurementAggregation or DistinctMeasurementSearch
DateTime inspectionPlanTimestamp Timestamp of the last inspection plan modification
DateTime measurementTimestamp Timestamp of the last measurement modification
DateTime configurationTimestamp Timestamp of the last configuration modification
DateTime catalogTimestamp Timestamp of the last catalog modification

Configuration

Endpoints

The configuration can be fetched, created, updated and deleted using the following endpoints. These endpoints do not provide filter parameters.

Example Example: Fetching the configuration including all attributes
Request
GET /dataServiceRest/configuration HTTP/1.1
Response
{
       "partAttributes":
       [
        [
            "key":1001,
            "description":"partNumber",
            "length":30,
            "type":"AlphaNumeric",
            "definitionType":"AttributeDefinition"
        ],
        ...
       ],
       "characteristicAttributes":
       [
        [
            "key":2001,
            "description":"characteristicNumber",
            "length":20,
            "type":"AlphaNumeric",
            "definitionType":"AttributeDefinition"
        ],
        ...
       ],
       "measurementAttributes":
       [
             "key": 8,
             "description": "inspector",
             "catalog": "8c376bee-ffe3-4ee4-abb9-a55b492e69ad",
             "definitionType": "CatalogAttributeDefinition"
       ...
       ],
       "valueAttributes":
       [
       ...
       ],
       "catalogAttributes":
       [
       ...
       ]
}

Creates the attribute definitions transfered within the body of the request for the given :pluralizedEntityType which must be part of the uri

Example Example: Adding a part attribute with the key 1001 to the configuration
Request
POST /dataServiceRest/configuration/parts HTTP/1.1
[
  {
    "key":1001,
    "description":"partNumber",
    "length":30,
    "type":"AlphaNumeric",
    "definitionType":"AttributeDefinition"
  }
]
Response
HTTP/1.1 201 Created

Updates the attribute definitions transfered within the body of the request for the given :pluralizedEntityType which must be part of the uri

Example Example: Updating the part attribute with key 1001 - change length from 30 to 50
Request
PUT /dataServiceRest/configuration/parts HTTP/1.1
[
  {
    "key":1001,
    "description":"partNumber",
    "length":50,
    "type":"AlphaNumeric",
    "definitionType":"AttributeDefinition"
  }
]
Response
HTTP/1.1 200 Ok
Example Example: Delete all attributes of the current configuration
Request
DELETE /dataServiceRest/configuration HTTP/1.1
Response
HTTP/1.1 200 Ok

Deletes all attribute definitions of which the id is in the :attributeIdList for the specified :pluralizedEntityType. If :attributeIdList is not specified, the request deletes all attributes of the :pluralizedEntityType.

Example Example: Delete the part attributes with the keys 1001 and 1002
Request
DELETE /dataServiceRest/configuration/part/{1001, 1002} HTTP/1.1
Response
HTTP/1.1 200 Ok


If at least one entry with value for the given key exists HTTP status code 204 otherwise 404 is returned.

Object Structure

The PiWeb configuration consists of a list of attributes for each entity type. The different entity types are:

  • part,
  • characteristic,
  • measurement,
  • value and
  • catalog.

The attributes are either AttributeDefinition or CatalogAttributeDefinition.

AttributeDefinition

Property Description
ushort key The attribute’s key, which serves as a unique id
string description The attribute’s name or a short description
AttributeType type The attribute’s type. AlphaNumeric, Integer, Float or DateTime
ushort length The attribute’s maximum length. Only set if the type is AlphaNumeric
string definitionType Always has the value ‘AttributeDefinition’ and is used to differentiate between AttributeDefinition and CatalogAttributeDefinition

CatalogAttributeDefinition

Property Description
ushort key The attribute’s key, which serves as a unique id
string description The attribute’s name or a short description
Guid catalog The id of the catalog that contains the possible attribute values
string definitionType Always has the value ‘CatalogAttributeDefinition’ and is used to differentiate between AttributeDefinition and CatalogAttributeDefinition

Catalogs

Endpoints

Catalogs and catalog entries can be fetched, created, updated and deleted using the following endpoints.

Example Example: Fetching all catalogs
Request
GET /dataServiceRest/catalogs HTTP/1.1
Response
[
   {
      "uuid": "d7291afb-0a67-4c1e-8bcc-6fc455bcc0e5",
      "name": "direction catalog",
      "validAttributes": [ 2009 ],
      "catalogEntries":
      [
         {
            "key": 0,
            "attributes": { "2009": "undefined" }
         },
         {
            "key": 1,
            "attributes": { "2009": "right" }
         },
         {
            "key": 2,
            "attributes": { "2009": "left" }
         }
      ]
   },
   {
      "uuid": "8c376bee-ffe3-4ee4-abb9-a55b492e69ad",
      "name": "InspectorCatalog",
      "validAttributes": [ 4092, 4093 ],
      "catalogEntries":
      [
         {
            "key": 0,
            "attributes": { "4092": "n.def.", "4093": "n.def." }
         },
         {
            "key": 1,
            "attributes": { "4092": "21", "4093": "Smith" }
         },
         {
            "key": 2,
            "attributes": { "4092": "20", "4093": "Miller" }
         },
         {
            "key": 3,
            "attributes": { "4092": "23", "4093": "Williams" }
         }
      ]
   },
   ...
]
Example Example: Fetching the catalog with the uuid 8c376bee-ffe3-4ee4-abb9-a55b492e69ad
Request
GET /dataServiceRest/catalogs/8c376bee-ffe3-4ee4-abb9-a55b492e69ad HTTP/1.1
Response
[
    {
        "uuid": "8c376bee-ffe3-4ee4-abb9-a55b492e69ad",
        "name": "InspectorCatalog",
        "validAttributes": [ 4092, 4093 ],
        "catalogEntries":
        [
            {
                "key": 0,
                "attributes": { "4092": "n.def.", "4093": "n.def." }
            },
            {
                "key": 1,
                "attributes": { "4092": "21", "4093": "Smith" }
            },
            {
                "key": 2,
                "attributes": { "4092": "20", "4093": "Miller" }
            },
            {
                "key": 3,
                "attributes": { "4092": "23", "4093": "Williams" }
            }
         ]
     }
]

To create a new catalog, the catalog object must be transmitted in the request’s body. A valid request contains a unique identifier, the catalog name and the valid attributes. Catalog entries are optional. All valid attributes must be added as catalog attributes beforehand (see Configuration).

Info If no catalog entries are specified, an empty catalog entry with key ‘0’ and attribute value(s) ‘not defined’ ( in case of alphanumeric attributes ) is created by default.

Example Example: Adding the catalog InspectorCatalog
Request
POST /dataServiceRest/catalogs HTTP/1.1
[
  {
           "uuid": "8c376bee-ffe3-4ee4-abb9-a55b492e69ad",
           "name": "InspectorCatalog",
           "validAttributes": [ 4092, 4093 ],
           "catalogEntries":
           [
               {
                   "key": 0,
                   "attributes": { "4092": "n.def.", "4093": "n.def." }
               },
               {
                   "key": 1,
                   "attributes": { "4092": "21", "4093": "Smith" }
               },
               {
                   "key": 2,
                   "attributes": { "4092": "20", "4093": "Miller" }
               },
               {
                   "key": 3,
                   "attributes": { "4092": "23", "4093": "Williams" }
               }
            ]
        }
]
Response
HTTP/1.1 201 Created

To add entries to an existing catalog they need to be specified in the request body. Each new entry must consist of a unique key. Each entry attribute must be listed as a valid attribute in the catalog definition.

Example Example: Adding a catalog entry - add the inspector ‘Clarks’
Request
POST /dataServiceRest/catalogs/8c376bee-ffe3-4ee4-abb9-a55b492e69ad HTTP/1.1
 [
   {
       "key": 4,
       "attributes": { "4092": "22", "4093": "Clarks" }
   }
 ]
Response
HTTP/1.1 201 Created

Update a catalog when you want to:

  • rename the catalog and/or
  • update existing catalog entries.

To update a catalog, the whole object, including the valid attributes, needs to be transmitted in the body of the HTTP request. Updating a catalog essentially replaces the current catalog entries with the new one (delete followed by an add) in a single transaction.

Warning All attribute entries for existing entities are set to undefined!

Example Example: Rename the catalog from ‘InspectorCatalog’ to ‘Inspectors’ and change the inspector’s name from ‘Smith’ to ‘Clarks’
Request
PUT /dataServiceRest/catalogs HTTP/1.1
[
  {
           "uuid": "8c376bee-ffe3-4ee4-abb9-a55b492e69ad",
           "name": "Inspectors",
           "catalogEntries":
           [
               {
                   "key": 0,
                   "attributes": { "4092": "n.def.", "4093": "n.def." }
               },
               {
                   "key": 1,
                   "attributes": { "4092": "21", "4093": "Clarks" }
               },
               {
                   "key": 2,
                   "attributes": { "4092": "20", "4093": "Miller" }
               },
               {
                   "key": 3,
                   "attributes": { "4092": "23", "4093": "Williams" }
               }
            ]
        }
]
Response
HTTP/1.1 200 Ok
Example Example: Delete all catalogs
Request
DELETE /dataServiceRest/catalogs HTTP/1.1
Response
HTTP/1.1 200 Ok
Example Example: Delete the catalog with uuid 8c376bee-ffe3-4ee4-abb9-a55b492e69ad
Request
DELETE /dataServiceRest/catalogs/8c376bee-ffe3-4ee4-abb9-a55b492e69ad HTTP/1.1
Response
HTTP/1.1 200 Ok
Example Example: Delete all entries from the catalog with uuid 8c376bee-ffe3-4ee4-abb9-a55b492e69ad
Request
DELETE /dataServiceRest/catalogs/8c376bee-ffe3-4ee4-abb9-a55b492e69ad/ HTTP/1.1
Response
HTTP/1.1 200 Ok
Example Example: Delete the entries with key 1 and 3 from the catalog with uuid 8c376bee-ffe3-4ee4-abb9-a55b492e69ad
Request
DELETE /dataServiceRest/catalogs/8c376bee-ffe3-4ee4-abb9-a55b492e69ad/{1,3} HTTP/1.1
Response
HTTP/1.1 200 Ok

Object Structure

Each catalog describes a list of entries. All entries have the same defined set of attributes, called valid attributes. All valid attributes must be created as catalog attributes beforehand. Catalog and CatalogEntryhave the following structures:

Catalog

Property Description
Guid uuid Identifies the catalog uniquely
string name The name of the catalog
ushort[] validAttributes A list of attribute keys that are valid for this catalog
CatalogEntry catalogEntries A list of catalog entries

CatalogEntry

Property Description
short key Specifies the entry’s order within the catalog
Attribute[] attributes A list of attributes which consists of key and value. The keys must be in the validAttributes list.

Parts and Characteristics

Endpoints

You can fetch, create, update and delete parts and characteristics using the following endpoints:

Parts

You can fetch all parts or certain parts. Possible filter uri parameters are:

Parameter name Description
Guid list partUuids
 Restricts the query to the parts with these uuids.
Path partPath Restricts the query to the part with this path.
ushort depth
default: 1		 Determines how many levels of the inspection plan tree hierarchy should be fetched. Setting depth=0 means that only the entity itself should be fetched, depth=1 means the entity and its direct children should be fetched. Please note that depth is treated relative of the path depth of the provided part.
bool withHistory
default: false		 Determines whether the version history should be fetched or not. This only effects the query if versioning is activated on the server side.
All, None, ID list requestedPartAttributes
default: All		 Restricts the query to the attributes that should be returned for parts, for example requestedPartAttributes={1001, 1008}.
Example Example: Fetch the part at path /metal part without child parts and only get the values for attributes 1001 and 1003
Request
GET /dataServiceRest/parts?partPath=/metal%20part&depth=0&requestedPartAttributes={1001,1003} HTTP/1.1
Response
[
   {
        "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"
    }
]

You can fetch a certain part by its :partUuid. The result can be restricted by the following uri parameters:

Parameter name Description
bool withHistory
default: false		 Determines whether the version history should be fetched or not. This only effects the query if versioning is activated on the server side.
All, None, ID list requestedPartAttributes
default: All		 Restricts the query to the attributes that should be returned for parts, for example requestedPartAttributes={1001, 1008}.
Example Example: Fetch the part ‘/metal part’ by its guid
Request
GET /dataServiceRest/parts/05040c4c-f0af-46b8-810e-30c0c00a379e HTTP/1.1
Response
[
   {
        "path": "P:/metal part/",
        "charChangeDate": "2014-11-19T10:48:32.917Z",
        "attributes": {},
        "uuid": "05040c4c-f0af-46b8-810e-30c0c00a379e",
        "version": 0,
        "timestamp": "2012-11-19T10:48:32.887Z"
    }
]

To create a new part, you must send its JSON representation in the request body. Values for uuid and path are required, attributes and comment are optional. The attribute keys must be valid part attributes as specified in the Configuration.

Info The comment is only added if versioning is enabled in the server settings.

Example Example: Adding the ‘metal part’ part with the uuid 05040c4c-f0af-46b8-810e-30c0c00a379e
Request
POST /dataServiceRest/parts HTTP/1.1
[
  {
    "uuid": "05040c4c-f0af-46b8-810e-30c0c00a379e",
    "path": "/metal part",
    "attributes": { "1001": "4466", "1003": "mp" }       
  }
]
Response
HTTP/1.1 201 Created

If you update a part you might want to:

  • Rename/move parts or
  • change attributes of parts.

Info If versioning is activated on the server side, every update creates a new version entry. If versioning is set to ‘Controlled by the client’ on server side it can be contolled by the following parameter:

Parameter name Description
bool versioningEnabled
default: false		 Determines whether a version entry should be created or not. This only effects the query if versioning is set to ‘Controlled by the client’ on server side.
Example Example: Change the metal part’s attributes
Request
PUT /dataServiceRest/parts HTTP/1.1
[
  {
     "path": "/metal part",
     "attributes": { "1001": "4469", "1003": "metalpart" }       
     "uuid": "05040c4c-f0af-46b8-810e-30c0c00a379e",
  }
]
Response
HTTP/1.1 200 Ok

There are two ways to delete parts, either by their path or by their uuids. This means that either the filter parameter partPath or partUuids has to be set:

Parameter name Description
Guid list partUuids
 Restricts the query to the parts with these uuids.
Path partPath Restricts the query to the part with this path.

In both cases the request deletes the part itself as well as all its child parts and child characteristics. If both parameters are set only the partUuids parameter will be considered.

Example Example: Delete the part ‘metal part’ and its children.
Request
DELETE /dataServiceRest/parts?partPath=/metal%20part HTTP/1.1
Response
HTTP/1.1 200 Ok

Deleting a part also deletes all its children.

Example Example: Delete the part ‘metal part’ and all entities beneath it by the part’s guid
Request
DELETE /dataServiceRest/parts/05040c4c-f0af-46b8-810e-30c0c00a379e HTTP/1.1
Response
HTTP/1.1 200 Ok

Characteristics

You can fetch all characteristics or only the characteristics described by the uri parameters. Possible filter uri parameters are:

Parameter name Description
Guid list charUuids
 Restricts the query to the characteristics with these uuids.
Path partPath
default: /		 Restricts the query to the part with this path. The charUuids parameter takes precedence over this parameter.
ushort depth
default: 65.536		 Determines how many levels of the inspection plan tree hierarchy should be fetched. Setting depth=0 means that only the entity itself should be fetched, depth=1 means the entity and its direct children should be fetched. Please note that depth is treated relative of the path depth of the provided part or characteristic.
bool withHistory
default: false		 Determines whether the version history should be fetched or not. This only effects the query if versioning is activated on the server side.
All, None, ID list requestedCharacteristicAttributes
default: All		 Restricts the query to the attributes that should be returned for characteristics, for example requestedCharacteristicAttributes={2001, 2101}

InfoYou can only request direct characteristics of the part, characteristics of child parts will be ignored.

Example Example: Fetch all characteristics beneath the part ‘/metal part’ until depth=2
Request
GET /dataServiceRest/characteristics?partPath=/metal%20part&depth=2 HTTP/1.1
Response
[
   {
        "path": "PC:/metal part/deviation_3/",
        "attributes": { ... },
        "uuid": "27e23a7c-dbe7-4863-8461-6abf7b03ddd7",
        "version": 0,
        "timestamp": "2012-11-19T10:48:32.887Z"
    },
   {
        "path": "PCC:/metal part/deviation_3/.X/",
        "attributes": { ... },
        "uuid": "51c8568a-9410-465a-a8ed-33063db41dac",
        "version": 0,
        "timestamp": "2015-03-24T08:17:28.03Z"
    },
    {
        "path": "PCC:/metal part/deviation_3/.Y/",
        "attributes": { ... },
        "uuid": "b7a30736-6e89-4dd5-9bc0-e6cb9eb5e2da",
        "version": 0,
        "timestamp": "2015-03-24T08:17:34.61Z"
    },
    {
        "path": "PCC:/metal part/deviation_3/.Z/",
        "attributes": { ... },
        "uuid": "1175919c-5c59-487e-a0fb-deac04510046",
        "version": 0,
        "timestamp": "2015-03-24T08:17:38.423Z"
    }
]

The result of fetching a certain characteristic by its :charUuid can be restricted by the following uri parameters:

Parameter name Description
bool withHistory
default: false		 Determines whether the version history should be fetched or not. This only effects the query if versioning is activated on the server side.
All, None, ID list requestedCharacteristicAttributes
default: All		 Restricts the query to the attributes that should be returned for characteristics, for example requestedCharacteristicAttributes={2001, 2101}
Example Example: Fetch the characteristic ‘/metal part/deviation_3’ by its guid
Request
GET /dataServiceRest/characteristics/27e23a7c-dbe7-4863-8461-6abf7b03ddd7 HTTP/1.1
Response
[
   {
        "path": "PC:/metal part/deviation_3/",
        "attributes": { ... },
        "uuid": "27e23a7c-dbe7-4863-8461-6abf7b03ddd7",
        "version": 0,
        "timestamp": "2012-11-19T10:48:32.887Z"
    }
]

To create characteristics, you must send a JSON representation of the characteristics in the request body. Values for uuid and path are required, attributes and comment are optional. The attribute keys must be valid characteristic attributes as specified in the Configuration.

Info The comment is only added if versioning is enabled in the server settings.

Example Example: Adding the characteristic ‘metal part/deviation_3’
Request
POST /dataServiceRest/characteristics HTTP/1.1
[
  {
     "path": "PC:/metal part/deviation_3/",
     "attributes":
      {
         "2004": "3",
         "2101": "0",
         "2110": "-0.5",
         "2111": "0.5"
      },
     "uuid": "27e23a7c-dbe7-4863-8461-6abf7b03ddd7"
  }
]
Response
HTTP/1.1 201 Created

If you update characteristics you want to:

  • Rename/move characteristics or
  • change attributes of characteristics.

Info If versioning is activated on server side, every update of one or more characteristics creates a new version entry. If versioning is set to ‘Controlled by the client’ on server side it can be contolled by the following parameter:

Parameter name Description
bool versioningEnabled
default: false		 Determines whether a version entry should be created or not. This only effects the query if versioning is set to ‘Controlled by the client’ on server side.
Example Example: Change the metal part/deviation_3’s attributes
Request
PUT /dataServiceRest/characteristics HTTP/1.1
[
  {
     "path": "/metal part/deviation_3",
     "attributes": { "2110": "-1.0", "2111": "1.0"  }       
     "uuid": "05040c4c-f0af-46b8-810e-30c0c00a379e",
  }
]
Response
HTTP/1.1 200 Ok

You have two options to delete characteristics, either by their paths or by their uuids. This means that either the filter parameter charPath or charUuids has to be set:

Parameter name Description
Guid listcharUuids
 Restricts the query to characteristics with these uuids.
Path charPath Restricts the query to the part with this characteristics.

In both cases the request deletes the characteristic itself as well as all its children. If both parameters are set only the charUuids parameter will be considered.

Example Example: Delete the characteristic ‘metal part/deviation_3’ and all entities beneath it
Request
DELETE /dataServiceRest/parts?charPath=/metal%20part/deviation_3 HTTP/1.1
Response
HTTP/1.1 200 Ok

Deleting a characteristic also deletes all its children.

Example Example: Delete the characteristic ‘metal part/deviation_3’ and all entities beneath it by its guid
Request
DELETE /dataServiceRest/characteristics/27e23a7c-dbe7-4863-8461-6abf7b03ddd7 HTTP/1.1
Response
HTTP/1.1 200 Ok


Object Structure

Both parts and characteristics are PiWeb inspection plan entities. They have the following properties:

Property Description
Guid uuid Identifies this inspection plan entity uniquely.
string path The path of this entity. It consists of the path’s hierarchical structure followed by the path itself, e.g. PCC:/metal part/deviation_3/.X/. P stands for part and C for characteristic.
Attribute attributes A set of attributes which describe the entity.
string comment A comment which describes the last inspection plan change. The comment is only returned in case versioning is enabled in the server settings.
int version Contains the entity´s revision number. The revision number starts with 0 and is incremented by 1 each time changes are applied to the inspection plan.
dateTime timeStamp Contains the date and time of when the entity was last updated.
dateTime charChangeDate (Parts only) The timestamp for the most recent characteristic change on any characteristic that belongs to this part

Measurements and Values

Endpoints

You can fetch, create, update and delete measurements and values using the following endpoints:

Measurements

You can fetch all measurements or certain measurements only. Possible filter uri parameters are:

Type Parameter Description
Example
Guid list measurementUuids Restricts the query to these measurements
measurementUuids={5b59cac7-9ecd-403c-aa26-56dd25892421}
Guid list partUuids Restricts the query to these parts
partUuids={e42c5327-6258-4c4c-b3e9-6d22c30938b2}
Path partPath Restricts the query to this part
partPath=/metal%20part
bool deep
default: false		 Determines whether the query should affect all levels of the inspection plan.
deep=true
OrderCriteria order
default: 4 desc		 Determines which attribute keys and which direction the keys should be ordered by
order:4 asc, 10 desc
Condition searchCondition The query will only return items matching all conditions. Possible operators are: >, <, >=, <=, =, <>, In, NotIn, Like.
You can combine multiple conditions with ‘+’. The format for date/time has to be “yyyy-mm-ddThh:mm:ssZ”. All values need to be surrounded by [ and ].
searchCondition=4>[2012-11-13T00:00:00Z]
DateTime fromModificationDate Specifies a date to select all measurements that where modified after that date. Please note that the system modification date (lastModified property) is used and not the time attribute (creation date).
DateTime toModificationDate Specifies a date to select all measurements that where modified before that date. Please note that the system modification date (lastModified property) is used and not the time attribute (creation date).
int limitResult Restricts the number of result items.
limitResult=100
All, None, Id list requestedMeasurementAttributes
default: All		 Restricts the query to the attributes that should be returned for measurements.
requestedMeasurementAttributes={4,8}
None, Simple, Detailed statistics
default: None		 Indicates how statistical informtaion should be returned:
None = Return no information
Simple = Return statistical information including numvber of characteristics out of warning limit, number of characteristics out of tolerance and number of characteristics in warning limit and tolerance
Detailed = Return statistical information the same way as Simple plus the guid for each characteristic
statistics=Simple
Measurements, AggregationMeasurements, All aggregation
default: Measurements		 Specifies which types of measurements will be fetched.
aggregation=All
Example Example: Fetch measurements newer than 01.01.2015 for the part with the guid e42c5327-6258-4c4c-b3e9-6d22c30938b2
Request
GET /dataServiceRest/measurements?partUuids={e42c5327-6258-4c4c-b3e9-6d22c30938b2}&searchCondition=4>[2015-01-01T00:00:00Z] HTTP/1.1
Response
 [
   {
     "uuid": "5b59cac7-9ecd-403c-aa26-56dd25892421",
     "partUuid": "e42c5327-6258-4c4c-b3e9-6d22c30938b2",
     "lastModified": "2015-03-09T09:19:38.653Z",
     "attributes":
     {
         "4": "2015-03-09T19:12:00Z",
         "6": "3",
         "7": "0"
     }
    },
    ...
  ]

The request can be restricted by the following filter uri parameters:

Type Parameter Description
Example
All, None, Id list requestedMeasurementAttributes
default: All		 Restricts the query to the attributes that should be returned for measurements.
requestedMeasurementAttributes={4,8}
None, Simple, Detailed statistics
default: None		 Indicates how statistical informtaion should be returned:
None = Return no information
Simple = Return statistical information including numvber of characteristics out of warning limit, number of characteristics out of tolerance and number of characteristics in warning limit and tolerance
Detailed = Return statistical information the same way as Simple plus the guid for each characteristic
statistics=Simple
Measurements, AggregationMeasurements, All aggregation
default: Measurements		 Specifies which types of measurements will be fetched.
aggregation=All
Example Example: Fetch a measurement by its guid
Request
GET /dataServiceRest/measurements/5b59cac7-9ecd-403c-aa26-56dd25892421 HTTP/1.1
Response
 [
   {
     "uuid": "5b59cac7-9ecd-403c-aa26-56dd25892421",
     "partUuid": "e42c5327-6258-4c4c-b3e9-6d22c30938b2",
     "lastModified": "2015-03-09T09:19:38.653Z",
     "attributes":
     {
         "4": "2015-03-09T19:12:00Z",
         "6": "3",
         "7": "0"
     }
    }
  ]

To create a new measurement, you must send its JSON representation in the request body. Values for uuid and path are required, attributes and comment are optional. The attribute keys must be valid measurement attributes as specified in the Configuration.

Info The comment is only added if versioning is enabled in server settings.

Example Example: Create a measurement
Request
POST /dataServiceRest/measurements HTTP/1.1
[
  {
    "uuid": "4b59cac7-9ecd-403c-aa26-56dd25892421",
      "partUuid": "e42c5327-6258-4c4c-b3e9-6d22c30938b2",
      "attributes": {
        "4": "2015-03-09T19:12:00Z",
        "6": "3",
        "7": "0"
      }     
  }
]
Response
HTTP/1.1 201 Created

Updating a measurement is about changing measurement attributes. Pass the whole measurement including all attributes in the request body. The server then deletes all attributes and creates the new one in a single transaction.

Example Example: Update a measurement - add and change an attribute
Request
PUT /dataServiceRest/measurements HTTP/1.1
[
  {
    "uuid": "4b59cac7-9ecd-403c-aa26-56dd25892421",
      "partUuid": "e42c5327-6258-4c4c-b3e9-6d22c30938b2",
      "attributes": {
        "4": "2015-03-09T19:12:00Z",
        "6": "2",
        "7": "0",
        "8": "1"
      }
  }
]
Response
HTTP/1.1 200 OK

You have multiple options for deleting measurements measurements:

  • Delete all measurements
  • Delete measurements by their uuids
  • Delete measurements from a single part by its path
  • Delete measurements from parts by its uuids

Delete condition for deleting measurements from a single or multiple parts may be further restricted by the filter uri parameter searchCondition.

Type Parameter Description
Example
Guid list measurementUuids Restricts the query to these measurements
measurementUuids={5b59cac7-9ecd-403c-aa26-56dd25892421}
Guid list partUuids Restricts the query to these parts
partUuids={e42c5327-6258-4c4c-b3e9-6d22c30938b2}
Path partPath Restricts the query to this part
partPath=/metal%20part
Condition searchCondition The query will only return items matching all conditions. Possible operators are: >, <, >=, <=, =, <>, In, NotIn, Like.
You can combine multiple conditions with ‘+’. The format for date/time has to be “yyyy-mm-ddThh:mm:ssZ”. All values need to be surrounded by [ and ].
searchCondition=4>[2012-11-13T00:00:00Z]
Measurements, AggregationMeasurements, All aggregation
default: Measurements		 Specifies which types of measurements will be deleted.
aggregation=All
bool deep
default: false		 Determines whether the query should delete only measurements for the given part(s) specified by either partPath or partUuids.
deep=true
Example Example: Delete measurements newer than 01.01.2015 and older than 31.03.2015 from the part with the uuid e42c5327-6258-4c4c-b3e9-6d22c30938b2
Request
DELETE /dataServiceRest/measurements?partUuids={4b59cac7-9ecd-403c-aa26-56dd25892421}&searchCondition=4>[2015-01-01T00:00:00Z]+4<[2015-03-31T23:59:59Z] HTTP/1.1
Response
HTTP/1.1 200 OK
Example Example: Delete a measurement by its guid
Request
DELETE /dataServiceRest/measurements/5b59cac7-9ecd-403c-aa26-56dd25892421 HTTP/1.1
Response
HTTP/1.1 200 OK

You can fetch all given attribute values for a measurement attribute. Measurements to be considered are definded by the following parameters:

Type Parameter Description
Example
int key The attribute key distincted values should be fetched for
Guid list measurementUuids Restricts the query to these measurements
measurementUuids={5b59cac7-9ecd-403c-aa26-56dd25892421}
Guid list partUuids Restricts the query to these parts
partUuids={e42c5327-6258-4c4c-b3e9-6d22c30938b2}
Path partPath Restricts the query to this part

partPath=/metal%20part
bool deep
default: false		 Determines whether the query should affect all levels of the inspection plan.
deep=true
OrderCriteria order
default: 4 desc		 Determines which attribute keys and which direction the keys should be ordered by
order:4 asc, 10 desc
Condition searchCondition The query will only return items matching all conditions. Possible operators are: >, <, >=, <=, =, <>, In, NotIn, Like.
You can combine multiple conditions with ‘+’. The format for date/time has to be “yyyy-mm-ddThh:mm:ssZ”. All values need to be surrounded by [ and ].
searchCondition=4>[2012-11-13T00:00:00Z]
DateTime fromModificationDate Specifies a date to select all measurements that where modified after that date. Please note that the system modification date (lastModified property) is used and not the time attribute (creation date).
DateTime toModificationDate Specifies a date to select all measurements that where modified before that date. Please note that the system modification date (lastModified property) is used and not the time attribute (creation date).
int limitResult Restricts the number of result items.
limitResult=100
Measurements, AggregationMeasurements, All aggregation
default: Measurements		 Specifies which types of measurements will be fetched.
aggregation=All
Example Example: Fetch distinced attribute values for attribute key 6 of the last 100 measurements
Request
GET /dataservicerest/distinctMeasurementAttributeValues?key=6&limitResult=100 HTTP/1.1
Response
 ["5","6","7","8","4","9","","10"]

Values

You can fetch all measurements with values or only certain measurements with values. Possible filter uri parameters are:

Type Parameter Description
Example
Guid list measurementUuids Restricts the query to these measurements
measurementUuids={5b59cac7-9ecd-403c-aa26-56dd25892421}
Guid list partUuids Restricts the query to these parts
partUuids={e42c5327-6258-4c4c-b3e9-6d22c30938b2}
Path partPath Restricts the query to this part

partPath=/metal%20part
bool deep
default: false		 Determines whether the query should affect all levels of the inspection plan.
deep=true
OrderCriteria order
default: 4 desc		 Determines which attribute keys and which direction the keys should be ordered by
order:4 asc, 10 desc
Condition searchCondition The query will only return items matching all conditions. Possible operators are: >, <, >=, <=, =, <>, In, NotIn, Like.
You can combine multiple conditions with ‘+’. The format for date/time has to be “yyyy-mm-ddThh:mm:ssZ”. All values need to be surrounded by [ and ].
searchCondition=4>[2012-11-13T00:00:00Z]
DateTime fromModificationDate Specifies a date to select all measurements that where modified after that date. Please note that the system modification date (lastModified property) is used and not the time attribute (creation date).
DateTime toModificationDate Specifies a date to select all measurements that where modified before that date. Please note that the system modification date (lastModified property) is used and not the time attribute (creation date).
int limitResult Restricts the number of result items.
limitResult=100
All, None, Id list requestedMeasurementAttributes
default: All		 Restricts the query to the attributes that should be returned for measurements.
requestedMeasurementAttributes={4,8}
All, None, Id list requestedValueAttributes
default: All		 List of attributes that should be returned for values.

requestedValueAttributes={1,8}
Guid list characteristicUuids Restricts the query to the characteristics for which values should be returned.
characteristicsUuids={525d15c6-dc70-4ab4-bd3c-8ab2b5780e6b, 8faae7a0-d1e1-4ee2-b3a5-d4526f6ba822}
Measurements, AggregationMeasurements, All aggregation
default: Measurements		 Specifies which types of measurements will be fetched.
aggregation=All
Example Example: Fetch measurements and values newer than 01.01.2015 restricted to a certain characteristic for a part restricted by its guid
Request
GET /dataservicerest/values?partUuids={05040c4c-f0af-46b8-810e-30c0c00a379e}&searchCondition=4>[2010-11-04T00:00:00Z]&characteristicUuids={b587d548-8aa6-42b7-b292-0f3e13452c3f} HTTP/1.1
Response
 [
   {
    "characteristics":
         {
             "b587d548-8aa6-42b7-b292-0f3e13452c3f":
             {
                 "1": "-0.073420455529934786"
             }
         },
         "uuid": "88974561-a449-4a94-8b3e-970822b84406",
         "partUuid": "05040c4c-f0af-46b8-810e-30c0c00a379e",
         "lastModified": "2015-01-19T10:48:34.157Z",
         "attributes":
         {
             "4": "2010-11-05T20:30:57.6Z",
             "6": "5",
             "7": "4",
             "8": "7",
             "12": "4"
         }
    },
    ...
  ]

The request can be restricted by the following uri filter parameters: Possible filters are:

Type Parameter Description
Example
All, None, Id list requestedMeasurementAttributes
default: All		 Restricts the query to the attributes that should be returned for measurements.
requestedMeasurementAttributes={4,8}
All, None, Id list requestedValueAttributes
default: All		 List of attributes that should be returned for values.

requestedValueAttributes={1,8}
Guid list characteristicUuids Restricts the query to the characteristics for which values should be returned.
characteristicsUuidList={525d15c6-dc70-4ab4-bd3c-8ab2b5780e6b, 8faae7a0-d1e1-4ee2-b3a5-d4526f6ba822}
Measurements, AggregationMeasurements, All aggregation
default: Measurements		 Specifies which types of measurements will be fetched.
aggregation=All
Example Example: Fetch a measurement including all values by its guid
Request
GET /dataServiceRest/values/5b59cac7-9ecd-403c-aa26-56dd25892421 HTTP/1.1
Response
 [
   {
    "characteristics":
     {
         "b587d548-8aa6-42b7-b292-0f3e13452c3f":
         {
             "1": "-0.073420455529934786"
         },
         ...
     },
     "uuid": "5b59cac7-9ecd-403c-aa26-56dd25892421",
     "partUuid": "e42c5327-6258-4c4c-b3e9-6d22c30938b2",
     "lastModified": "2015-03-09T09:19:38.653Z",
     "attributes":
     {
         "4": "2015-03-09T19:12:00Z",
         "6": "3",
         "7": "0"
     }
    },
    ...
  ]

To create a measurement with values, you must send its JSON representation in the request body. Values for uuid and path are required, attributes and comment are optional. The attribute keys must be valid measurement attributes as specified in the Configuration.

Info The comment is only added if versioning is enabled in server settings.

Example Example: Create a measurement with measured values
Request
POST /dataServiceRest/values HTTP/1.1
[
  {
    "uuid": "4b59cac7-9ecd-403c-aa26-56dd25892421",
      "partUuid": "e42c5327-6258-4c4c-b3e9-6d22c30938b2",
      "attributes": {
        "4": "2015-03-09T19:12:00Z",
        "6": "3",
        "7": "0"
      },
      "characteristics":
      {
         "360f55e5-77c3-49f9-9a5e-80d0a9040e2d":
         {
             "1": "0.24966522"
         },
         "b5c98235-c75c-41a4-aced-2a38c70a3866":
         {
             "1": "0.4457339"
         },
         "85bbb406-810e-4062-8a9f-c7b636cb61bd":
         {
             "1": "0.24981162"
         }
      }
  }
]
Response
HTTP/1.1 201 Created

Updating a measurement does always affect the whole measurement. This means that you must send the whole measurement, including attributes and values, in the request body. The server then deletes the old measurement and creates the new one in a single transaction.

Example Example: Update a measurement - change a measured value
Request
PUT /dataServiceRest/measurements HTTP/1.1
[
  {
    "uuid": "4b59cac7-9ecd-403c-aa26-56dd25892421",
      "partUuid": "e42c5327-6258-4c4c-b3e9-6d22c30938b2",
      "attributes": {
        "4": "2015-03-09T19:12:00Z",
        "6": "2",
        "7": "0",
        "8": "1"
      }
      "characteristics":
      {
         "360f55e5-77c3-49f9-9a5e-80d0a9040e2d":
         {
             "1": "0.24966522"
         },
         "b5c98235-c75c-41a4-aced-2a38c70a3866":
         {
             "1": "0.4467339"
         },
         "85bbb406-810e-4062-8a9f-c7b636cb61bd":
         {
             "1": "0.25981162"
         }
      }
  }
]
Response
HTTP/1.1 200 OK

Object Structure

Measurements do always belong to a single inspection plan part. Depending on the purpose, the measured values are included within a measurement or not. Each measurement has the following properties:

Property Description
Guid uuid Identifies the measurement uniquely.
Guid partUuid The uuid of the part the measurement belongs to.
Attribute[] attributes A set of attributes which specifies this measurement.
DateTime lastModified Contains the date and time of the last update applied to this measurement.
DataCharacteristic[] characteristics An array of the characteristics which has been measured within the measurement. Each characteristic within this array consits of the uuid it is identified by and an array of attributes which include at least the measured value attribute.
This project is maintained by Carl Zeiss Industrielle Messtechnik GmbH