Raw Data Service

Example: Get interface version for Raw Data Service

Request

GET /rawdataServiceRest/ HTTP/1.1

Response

{"supportedVersions":["1.4.0"]}

Example: Get service information for a given connection

Request

GET /rawdataServiceRest/serviceInformation HTTP/1.1

Response

 {
  "version": "7.8.0.0"
 }

Returns a list of raw data file information entries for all entities with type :entity. You further have to and restrict the request to the entities’ uuids by adding the following uri parameter:

Parameter name	Description Example
uuids	Restricts the query to the entities identified by the given uuids. Entites of type ‘Value’ are identified by a compound key, which consists of the uuid of the measurement, ‘|’ and the characteristics uuid uuids={652ae7a0-d1e1-4ee2-b3a5-d4526f6ba822|78bd15c6-dc70-4ab4-bd3c-8ab2b5780b52}
filter	Contains one or multiple attribute conditions to restrict the query. Details can be found below.

Filter syntax

Basic module is expression <attribute> <operator> <value> or <attribute> <list operator> (<value1>, <value2>, ...)

<Value> can be formatted differently and needs to match type of attribute:

• Strings need to be surrounded by a single quote. If value contains a single quote it needs to be masked by another single quote: 'Some Value' or 'This string contains a single '' character.'.
• Decimal seperator for Numbers is a point.
• Date specifications may be absolute or relative to current server time.
  • Absolute date specifications are ISO formatted strings and have to explicitly contain a time zone '2018-01-21T16:12:30+01:00'
  • Relative data specifications are strings in following format: '-<Offset>[mhdwMy]' where m = minutes, h = hours, d = days, w = weeks, M = months, y = years, e.g. ‘-1w’ or ‘-5d’

Value list (<Value1>, <Value2>, …) contains any number of elements which need to meet the conditions described in above section.

Attribute conditions can be combined by logical operators and, or or not: <Condition1> and <Condition2> <Condition1> or <Condition2> not <Condition1>

Examples: Filename like '*.txt' or MimeType eq 'text/plain' Length lt 5000 (MimeType like 'text/* or Filename like '*.txt') and Length lt 5000 not MimeType like 'text/*' Filename in ('some_file.txt', 'some_other_file.html')

Example: Get the information entries for several parts

Request

GET /rawDataServiceRest/rawDataInformation/part?uuids={05040c4c-f0af-46b8-810e-30c0c00a379e,5441c003-b6db-4217-ac6a-45cdbb805bb3}&filter=fileName%20like%20'*meshModel*' HTTP/1.1

Response

[
 {
      "target":
      {
          "entity": "Part",
          "uuid": "05040c4c-f0af-46b8-810e-30c0c00a379e"
      },
      "key": 0,
      "fileName": "section view.meshModel",
      "mimeType": "application/x-zip-compressed",
      "lastModified": "2012-11-19T10:48:34.327Z",
      "created": "2012-11-19T10:48:34.327Z",
      "size": 147376,
      "md5": "02f9c861-43ea-176c-06e2-4524385b5907"
  },
  {
      "target":
      {
          "entity": "Part",
          "uuid": "5441c003-b6db-4217-ac6a-45cdbb805bb3"
      },
      "key": 0,
      "fileName": "cad_22.meshModel",
      "mimeType": "application/x-zeiss-piweb-meshmodel",
      "lastModified": "2015-03-20T14:37:02.943Z",
      "created": "2015-03-20T14:37:02.943Z",
      "size": 837245,
      "md5": "cbde88e2-ed75-4c70-860b-3e6d4313551a"
 }
]

Example: Get the information entries for a certain part

Request

GET /rawDataServiceRest/rawDataInformation/part/05040c4c-f0af-46b8-810e-30c0c00a379e HTTP/1.1

Response

[
 {
      "target":
      {
          "entity": "Part",
          "uuid": "05040c4c-f0af-46b8-810e-30c0c00a379e"
      },
      "key": 0,
      "fileName": "section view.meshModel",
      "mimeType": "application/x-zip-compressed",
      "lastModified": "2012-11-19T10:48:34.327Z",
      "created": "2012-11-19T10:48:34.327Z",
      "size": 147376,
      "md5": "02f9c861-43ea-176c-06e2-4524385b5907"
  }
 ]

Update raw data information when you want to:

• rename the file and/or
• update Mime type.

An update request consists of 2 mandatory parts:

1. The URL specifies the file to be updated identified by :entity, :uuid and :key.
2. The request body contains the raw data information to be updated.

Example: Update the filename and Mime type of the raw data object with key 1 of the part with the uuid f8343266-188e-4d2e-abf9-f0cbba4ac7c7

Request

PUT /rawDataServiceRest/rawDataInformation/part/f8343266-188e-4d2e-abf9-f0cbba4ac7c7/1 HTTP/1.1

{
    "filename": "metal part.jpg",
    "mimeType": "text/plain"
}

Response

HTTP/1.1 200 Ok

The server caches raw data fetch requests. When you request a raw data file for the first time the response will contain the file itself and several HTTP headers. One of these headers is the ETag header. An ETag is a unique hash value to identify the file. It is a combination of the file’s MD5 checksum and the last modification date. If you send the ETag value in the If-None-Match header, the server can respond two different ways, depending on whether the file has been modified since the last request:

1. Not modified: The server will return a 304 - Not modified HTTP status code and the response body will be emtpy.
2. Modified: The server will return the file.

Example: Fetch raw data with key 0 for a part with the uuid b8f5d3fe-5bd5-406b-8053-67f647f09dc7

Request

Without Caching

GET /rawDataServiceRest/rawData/part/b8f5d3fe-5bd5-406b-8053-67f647f09dc7/0 HTTP/1.1

With caching

GET /rawDataServiceRest/rawData/part/b8f5d3fe-5bd5-406b-8053-67f647f09dc7/0 HTTP/1.1
If-None-Match: "6ab0f6bd01b30aa8e55021085b820393635437006830400000"

Response

Modified

HTTP/1.1 200 OK
Etag: "6ab0f6bd01b30aa8e55021085b820393635437006830400000"
Last-Modified: Fri, 15 Aug 2014 11:58:03 GMT
...

The requested raw data file

Not modified

HTTP/1.1 304 Not modified

Example: Fetch the thumbnail for the raw data object with key 1 which is attached to the part with the uuid b8f5d3fe-5bd5-406b-8053-67f647f09dc7

Request

GET /rawDataServiceRest/rawData/part/b8f5d3fe-5bd5-406b-8053-67f647f09dc7/1/thumbnail HTTP/1.1

Response

HTTP/1.1 200 OK

The requested thumbnail

You can attach files to all entity types: parts, characteristics, measurements and measured values.

An add request consists of 3 mandatory parts:

1. The URL specifies which entity the file will be added to.
2. The request body contains the file itself.
3. The HTTP headers must provide meta information about the file, see below for details.

The allowed raw data file names (see Content-Disposition) can be restricted on the server.

When adding a file, you can pass the desired file key as part of the uri. If you pass -1 or no key, the next available key will automatically be assigned by the server (recommended) and can be read from the result.

If you pass a key which is already assigned to another file, this file will be replaced.

Remember, when adding a file for a measured value, you need to specify the target uuid in a compound format of measurementUuid|characteristicUuid, instead of one single uuid.

Example: Add a raw data object to a part with the uuid b8f5d3fe-5bd5-406b-8053-67f647f09dc7

Request

POST /rawDataServiceRest/rawData/part/b8f5d3fe-5bd5-406b-8053-67f647f09dc7 HTTP/1.1
Content-Disposition: "MetalPart.meshModel"
Content-Length: 2090682
Content-MD5: "vfawarMBqArlUCEIW4IDkw=="
Content-Type: "application/x-zeiss-piweb-meshmodel"

Response

HTTP/1.1 201 Created

{
    "target":
    {
        "entity": "Part",
        "uuid": "b8f5d3fe-5bd5-406b-8053-67f647f09dc7"
    },
    "key": 0,
    "fileName": "MetalPart.meshModel",
    "mimeType": "application/x-zip-compressed",
    "lastModified": "2012-11-19T10:48:34.327Z",
    "created": "2012-11-19T10:48:34.327Z",
    "size": 2090682,
    "md5": "6ab0f6bd-01b3-0aa8-e550-21085b820393"
}

An update request consists of 3 mandatory parts:

1. The URL specifies the file to be replaced identified by :entity, :uuid and :key.
2. The request body contains the file itself.
3. The HTTP headers must provide meta information about the file, see below for details.

The allowed raw data file names (see Content-Disposition) can be restricted on the server.

Example: Replace the raw data object with key 1 of the part with the uuid b8f5d3fe-5bd5-406b-8053-67f647f09dc7

Request

PUT /rawDataServiceRest/rawData/part/b8f5d3fe-5bd5-406b-8053-67f647f09dc7/1 HTTP/1.1
Content-Disposition: "MetalPart.meshModel"
Content-Length: 2090682
Content-MD5: "vfawarMBqArlUCEIW4IDkw=="
Content-Type: "application/x-zeiss-piweb-meshmodel"

Response

HTTP/1.1 200 Ok

Example: Delete all raw data objects from the part with the uuid b8f5d3fe-5bd5-406b-8053-67f647f09dc7

Request

DELETE /rawDataServiceRest/rawData/part/b8f5d3fe-5bd5-406b-8053-67f647f09dc7 HTTP/1.1

Response

HTTP/1.1 200 OK

Example: Delete the raw data object with key 1 from the part with the uuid b8f5d3fe-5bd5-406b-8053-67f647f09dc7

Request

DELETE /rawDataServiceRest/rawData/part/b8f5d3fe-5bd5-406b-8053-67f647f09dc7/0 HTTP/1.1

Response

HTTP/1.1 200 OK

You can fetch information about the archive and included files. In this example the ExampleArchive.zip contains three files as listed in “entries”: information.txt, metal_part.meshModel and thumbnail.jpg.

Example: Get information and a list of entries of an archive which is raw data with key 1 of the part with uuid db42f331-1a22-491b-b20f-1dc52a40cec7

Request

GET /rawDataServiceRest/rawData/part/db42f331-1a22-491b-b20f-1dc52a40cec7/1/ArchiveEntries HTTP/1.1

Response

 [
     {
         "archiveInfo": {
             "target": {
                 "entity": "Part",
                 "uuid": "db42f331-1a22-491b-b20f-1dc52a40cec7"
             },
             "key": 1,
             "fileName": "ExampleArchive.zip",
             "mimeType": "application/x-zip-compressed",
             "lastModified": "2020-12-17T10:35:49.017Z",
             "created": "2020-12-17T10:35:49.017Z",
             "size": 2206767,
             "md5": "9c5574b3-88f6-4e39-c4cd-4319db285c9c"
         },
         "entries": [
             "information.txt",
             "metal_part.meshModel",
             "thumbnail.jpg"
         ]
     }
 ]

Object Structure

The returned object contains the following properties:

Subfolders

As archives can contain subfolders, the structure is present in the filename.

 [
     {
         "archiveInfo": { . . . },
         "entries": [
             "metal_part.meshModel",
             "Subfolder/",
             "Subfolder/information.txt",
             "thumbnail.jpg"
         ]
     }
 ]   

Since folders are also entries from the point of view of the archive, they are part of the response like Subfolder/ in above example. Please note that these entries do not contain data, so requesting the entry Subfolder/ will result in HTTP status code 200 - OK, but without data in the response body. You will not receive the folders content. For this you need to explicitly fetch the files located in the subfolder with their full name, including folder structure, as shown in the next endpoint.

Once you know the contents of specified archive you can request single files with a GET request similiar to fetching normal raw data. You specify the raw data archive with :entity, :uuid and :key, and the requested file with its :filename. This endpoint offers the same caching mechanisms as the normal request for raw data.

The filename is case insensitive. Archive lookup will return the first occurence of specified file if two files with the same name exist in the same folder.

Example: Fetch the file ‘information.txt’ of an archive with raw data key 1 of the part with uuid db42f331-1a22-491b-b20f-1dc52a40cec7

Request

GET /rawDataServiceRest/rawData/part/db42f331-1a22-491b-b20f-1dc52a40cec7/1/ArchiveContent/information.txt HTTP/1.1

Response

The requested file

You can request information and file lists for more than one archive at a time using this query endpoint. The property selectors can contain any number of raw data targets and the key of the raw data archive.

Example: Fetch information and file lists of two raw data archives

Request

POST /rawDataServiceRest/rawData/ArchiveEntryQuery HTTP/1.1

{
    "selectors": [
        {
            "target": {
                "entity": "Part",
                "uuid": "db42f331-1a22-491b-b20f-1dc52a40cec7"
            },
            "key": 1
        },
        {
            "target": {
                "entity": "Characteristic",
                "uuid": "b8f5d3fe-5bd5-406b-8053-67f647f09dc7"
            },
            "key": 4
        },
    ]
}

Response

[
    {
        "archiveInfo": {
            "target": {
                "entity": "Part",
                "uuid": "db42f331-1a22-491b-b20f-1dc52a40cec7"
            },
            "key": 1,
            "fileName": "ExampleArchive.zip",
            "mimeType": "application/x-zip-compressed",
            "lastModified": "2020-12-17T10:35:49.017Z",
            "created": "2020-12-17T10:35:49.017Z",
            "size": 2206767,
            "md5": "9c5574b3-88f6-4e39-c4cd-4319db285c9c"
        },
        "entries": [
            "information.txt",
            "metal_part.meshModel",
            "thumbnail.jpg"
        ]
    },
    {
        "archiveInfo": {
            "target": {
                "entity": "Characteristic",
                "uuid": "b8f5d3fe-5bd5-406b-8053-67f647f09dc7"
            },
            "key": 4,
            "fileName": "ExampleArchive_Subfolder.zip",
            "mimeType": "application/x-zip-compressed",
            "lastModified": "2020-12-17T14:17:53.587Z",
            "created": "2020-12-17T14:17:53.587Z",
            "size": 2206919,
            "md5": "8e51ba7a-b63d-5066-e2a0-c03abc73261a"
        },
        "entries": [
            "metal_part.meshModel",
            "Subfolder/",
            "Subfolder/information.txt",
            "thumbnail.jpg"
        ]
    }
]

You can fetch multiple files of the same or different archives using the ArchiveContentQuery endpoint. The property selectors contains the same information as the ArchiveEntryQuery above, with an additional list of requested files per raw data archive.

Example: Fetch the files information.txt and thumbnail.jpg in one request

Request

POST /rawDataServiceRest/rawData/ArchiveContentQuery HTTP/1.1

{
    "selectors": [
        {
            "target": {
                "entity": "Part",
                "uuid": "db42f331-1a22-491b-b20f-1dc52a40cec7"
            },
            "key": 1,
            "entries": [
                "information.txt",
                "thumbnail.jpg"
            ]
        }
    ]
}

Response

The requested files in BSON format.

The BSON contains one entry for each requested file, with no separation between files of different raw data archives. Each entry contains the property archiveInfo, which again has the same structure as Raw Data Information. The entry can be identified by its fileName and is completed by the actual data, the size and an md5 checksum.

You can add more targets to selectors to fetch files from different archives:

{
    "selectors": [
        {
            "target": { . . . },
            "key": 1,               //Archive 1
            "entries": [ . . . ]
        },
        {
            "target": { . . . },
            "key": 4,               //Archive 2
            "entries": [ . . . ]
        },
        {
            "target": { . . . },
            "key": 325,             //Archive 3
            "entries": [ . . . ]
        }
    ]
}