# Copyright (c) Siemens AG 2021 ALL RIGHTS RESERVED. openapi: 3.0.0 info: title: Analyze MyMachine /Condition API Documentation description: > API defining resources and operations for AMM /C related data like Measurements. - AMM /C API is hosted behind SINUMERIK Edge MiniWeb application. - Basic Authentication & Client Certificate Authentication are supported which are functionalities of SINUMERIK Edge MiniWeb application. Check SINUMERIK Edge MiniWeb application documentation for further information. - OEMCommissioningEngineer and OEMServiceEngineer are the supported user groups version: 1.0.0 x-visibility: external servers: - url: https://:5443/analyzemymachinecondition/api/v1 description: AMM /C API url via MiniWeb for Basic Authentication - url: https://:5444/analyzemymachinecondition/api/v1 description: AMM /C API url via MiniWeb for Client Certificate Authentication tags: - name: Measurement Operations - name: Measurement Group Operations paths: /measurements: get: tags: - Measurement Operations summary: Get measurements description: | Gets the measurements. parameters: - name: page in: query description: The (0-based) index of page. required: false schema: type : integer format: int32 minimum: 0 default: 0 - name: size in: query description: The maximum number of elements in a page. required: false schema: type : integer format: int32 minimum: 0 maximum: 20 default: 20 responses: '200': description: Array of measurements content: application/json: schema: $ref: "#/components/schemas/PagedMeasurement" '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '500': description: unexpected error 'default': description: Other error with any status code and response body format. /measurements/{id}: get: tags: - Measurement Operations summary: Get measurement description: | Gets the measurement for the given measurement id. parameters: - name: id in: path description: Unique identifier of the measurement. required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Measurement' '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '500': description: unexpected error 'default': description: Other error with any status code and response body format. /measurements/{id}/threshold: get: tags: - Measurement Operations summary: Get the threshold for the given measurement id. description: | Gets the threshold for the given measurement id. parameters: - name: id in: path description: Unique identifier of the measurement. required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Thresholds' '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '500': description: unexpected error 'default': description: Other error with any status code and response body format. /measurements/{id}/results: get: tags: - Measurement Operations summary: Get all results of the measurement description: | Gets all results of the given measurement. parameters: - name: id in: path description: Unique identifier of the measurement. required: true schema: type: string - name: page in: query description: The (0-based) index of page. required: false schema: type : integer format: int32 minimum: 0 default: 0 - name: size in: query description: The maximum number of elements in a page. required: false schema: type : integer format: int32 minimum: 0 maximum: 20 default: 20 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/PagedResult' '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '500': description: unexpected error 'default': description: Other error with any status code and response body format. /measurements/{id}/results/{resultId}: get: tags: - Measurement Operations summary: Get the result for the given measurement id and the result id. description: | Gets the result for the given measurement id and the result id. parameters: - name: id in: path description: Unique identifier of the measurement. required: true schema: type: string - name: resultId in: path description: Unique identifier of the result. required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Result' '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '500': description: unexpected error 'default': description: Other error with any status code and response body format. /measurements/{id}/results/{resultId}/graphData/friction: get: tags: - Measurement Operations summary: Get the graphical data of friction for the given measurement id and the result id. description: | Gets the graphical data of friction for the given measurement id and the result id. parameters: - name: id in: path description: Unique identifier of the measurement. required: true schema: type: string - name: resultId in: path description: Unique identifier of the result. required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/FrictionGraphData' '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '500': description: unexpected error 'default': description: Other error with any status code and response body format. /measurements/{id}/results/{resultId}/graphData/stiffness: get: tags: - Measurement Operations summary: Get the graphical data of stiffness for the given measurement id and the result id. description: | Gets the graphical data of stiffness for the given measurement id and the result id. parameters: - name: id in: path description: Unique identifier of the measurement. required: true schema: type: string - name: resultId in: path description: Unique identifier of the result. required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/StiffnessGraphData' '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '500': description: unexpected error 'default': description: Other error with any status code and response body format. /measurements/{id}/results/{resultId}/graphData/backlash: get: tags: - Measurement Operations summary: Get the graphical data of backlash for the given measurement id and the result id. description: | Gets the graphical data of backlash for the given measurement id and the result id. parameters: - name: id in: path description: Unique identifier of the measurement. required: true schema: type: string - name: resultId in: path description: Unique identifier of the result. required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/BacklashGraphData' '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '500': description: unexpected error 'default': description: Other error with any status code and response body format. /measurements/{id}/results/{resultId}/graphData/signature: get: tags: - Measurement Operations summary: Get the graphical data for the given measurement id and the result id. description: | Gets the graphical data of signature for the given measurement id and the result id. parameters: - name: id in: path description: Unique identifier of the measurement. required: true schema: type: string - name: resultId in: path description: Unique identifier of the result. required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SignatureGraphData' '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '500': description: unexpected error 'default': description: Other error with any status code and response body format. /measurements/{id}/results/{resultId}/graphData/equability: get: tags: - Measurement Operations summary: Get the graphical data of equability for the given measurement id and the result id. description: | Gets the graphical data for the given measurement id and the result id. parameters: - name: id in: path description: Unique identifier of the measurement. required: true schema: type: string - name: resultId in: path description: Unique identifier of the result. required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/EquabilityGraphData' '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '500': description: unexpected error 'default': description: Other error with any status code and response body format. /measurements/{id}/results/{resultId}/graphData/frequencyResponse: get: tags: - Measurement Operations summary: Get the graphical data of frequency response for the given measurement id and the result id. description: | Gets the graphical data of frequency response for the given measurement id and the result id. parameters: - name: id in: path description: Unique identifier of the measurement. required: true schema: type: string - name: resultId in: path description: Unique identifier of the result. required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/FrequencyResponseGraphData' '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '500': description: unexpected error 'default': description: Other error with any status code and response body format. /measurements/{id}/results/{resultId}/rawData: get: tags: - Measurement Operations summary: Get raw data of the the result for the given measurement id and the result id. description: | Gets the raw data of the result for the given measurement id and the result id as zip file. The zip file name formatting is **_.zip** (e.g. 100_1654151362.zip). All characteristics' raw data is exported as csv file. The raw data csv file formatting is **.csv** (e.g. equability.csv). All csv files contain data with following order in DOUBLE data type: TIME | STAGE | Encoder1 data(ENC1_POS) | Encoder2 data(ENC2_POS) | Set_point(DES_POS) | Torque parameters: - name: id in: path description: Unique identifier of the measurement. required: true schema: type: string - name: resultId in: path description: Unique identifier of the measurement. required: true schema: type: string - name: range in: header description: | Part of the raw data to return in Bytes. Supported formats: * bytes=- * bytes=- * bytes=- Maximum range size is 100000000 schema: type: string example: 'bytes=200-600' responses: '200': description: OK content: application/octet-stream: schema: type: string format: binary '206': description: Partial Content content: application/octet-stream: schema: type: string format: binary headers: Content-Range: schema: type: string example: 'bytes 200-600/428808' '400': description: | Bad Request Bad Request that can be arised based on subsequent case: - User makes the request without Range header. - User makes the request with Range header and Range header exists maximum size 100 MB. - User makes the request with Range header or Range header format is not supported. '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '413': description: | Payload Too Large Payload Too Large that can be arised based on subsequent case: - User makes the request without Range header and the file size exists 100 MB. '416': description: Range Not Satisfiable '500': description: unexpected error '503': description: | Service Unavailable Service Unavailable that can be arised based on subsequent case: - User makes the request while a measurement test is executed. 'default': description: Other error with any status code and response body format. /measurementGroups: get: tags: - Measurement Group Operations summary: Get measurement groups description: | Gets the measurement groups. parameters: - name: page in: query description: The (0-based) index of page. required: false schema: type : integer format: int32 minimum: 0 default: 0 - name: size in: query description: The maximum number of elements in a page. required: false schema: type : integer format: int32 minimum: 0 maximum: 5 default: 5 responses: '200': description: Array of measurement groups content: application/json: schema: $ref: "#/components/schemas/PagedMeasurementGroup" '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '500': description: unexpected error 'default': description: Other error with any status code and response body format. /measurementGroups/{id}: get: tags: - Measurement Group Operations summary: Get measurement group description: | Gets the measurement group for the given measurement group id. parameters: - name: id in: path description: Unique identifier of the measurement group. required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/MeasurementGroup' '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '500': description: unexpected error 'default': description: Other error with any status code and response body format. components: schemas: Measurement: type: object required: - name - securityProfile - entityId properties: name: type: string maxLength: 40 example: 'Measurement 1' description: Name of the measurement id: type: string description: Unique identifier of the measurement example: "1" axis: type: string example: 'X' description: Axis of the measurement to be tested status: type: string enum: [CREATED, DEFINED, RELEASED, REFERENCED, REFERENCEABLE] description: Status of the measurement characteristics: type: object description: Selection of the characteristic values that must be calculated for measurement properties: friction: type: boolean stiffness: type: boolean backlash: type: boolean quadrantError: type: boolean signature: type: boolean equability: type: boolean frequencyResponse: type: boolean distance: type: object required: - startPoint - endPoint properties: startPoint: type: number description: The starting point for measurement travel is defined endPoint: type: number description: The end point for measurement travel is defined secure: type: object properties: prologStatus: type: boolean description: Indicates that the usage of prolog NC code is activated positionProlog: type: string description: Given prolog NC code. Maximum 2000 lines and maximum 256 characters per Line. epilogStatus: type: boolean description: Indicates that the usage of epilog NC code is activated positionEpilog: type: string description: Given epilog NC code. Maximum 2000 lines and maximum 256 characters per Line. circleDynamicResponse: type: string enum: [HIGH, MEDIUM, LOW] description: " Measurement with a high dynamic response (r = 10 mm, F = 5000 mm/min) Measurement with a medium dynamic response (r = 15 mm, F = 3000 mm/min) Measurement with a low dynamic response (r = 20 mm, F = 1000 mm/min)" rotationalStiffness: type: number example: 10000 maximum: 1000000000 minimum: 10 description: The rotational stiffness of the coupling [Nm/rad] ballScrewInertia: type: number example: 0 maximum: 100 minimum: 0 description: The moment of inertia of the ball screw [kgm2] referencedResultId: description: Referenced result of the measurement type: string example: 1 PagedMeasurement: type: object required: - content - totalPages - totalElements - last - numberOfElements - first - sort - size - number properties: content: type: array items: $ref: '#/components/schemas/Measurement' last: description: Whether the current item is the last one. type: boolean example: true totalPages: description: The number of total pages. type: integer example: 1 totalElements: description: The total amount of elements. type: integer example: 1 numberOfElements: description: The number of elements currently on this page. type: integer example: 1 first: description: Whether the current item is the first one. type: boolean example: true size: description: The size of the page. type: integer example: 20 number: description: The number of the current item. type: integer example: "1" Threshold: type: object properties: warningThreshold: type: number format: float example: 85.0 serviceThreshold: type: number format: float example: 100.0 unit: type: string description: Unit of the service and warning thresholds maxLength: 1 example: '%' Thresholds: type: object properties: friction: $ref: '#/components/schemas/Threshold' stiffness: $ref: '#/components/schemas/Threshold' backlash: $ref: '#/components/schemas/Threshold' quadrantError: $ref: '#/components/schemas/Threshold' signature: $ref: '#/components/schemas/Threshold' equability: $ref: '#/components/schemas/Threshold' frequencyResponse: $ref: '#/components/schemas/Threshold' Result: type: object properties: id: type: string description: Unique identifier of the result maxLength: 36 example: '100' date: type: number description: Timestamp of the result in epoch time example: 1654151362 status: type: string enum: [OK, Warning, Service, Error] description: > Status of the measurement result * `OK`- Measurement test executed successfully and no threshold specified * `Warning` - Warning threshold is exceeded for at least one characteristic * `Service` - Service threshold is exceeded for at least one characteristic * `Error` - Measurement test execution failed example: 'OK' frictionDistributionGuidance: allOf: - $ref: '#/components/schemas/ResultValueWithoutStatus' - type: object properties: unit: type: string example: "%" frictionDistributionSpindleNut: allOf: - $ref: '#/components/schemas/ResultValueWithoutStatus' - type: object properties: unit: type: string example: "%" frictionDry: allOf: - $ref: '#/components/schemas/ResultValue' - type: object properties: unit: type: string enum: [N, Nm] example: "N" description: "Unit changes according to axis type. Linear Axis - N and Rotary Axis - Nm" frictionViscous: allOf: - $ref: '#/components/schemas/ResultValueWithoutStatus' - type: object properties: unit: type: string example: "Ns/m" stiffness: allOf: - $ref: '#/components/schemas/ResultValue' - type: object properties: unit: type: string enum: [N/μm, Nms/rad] example: "N/μm" description: "Unit changes according to axis type. Linear Axis - N/μm and Rotary Axis - Nms/rad" backlash: allOf: - $ref: '#/components/schemas/ResultValue' - type: object properties: unit: type: string enum: [µm, m°] example: "μm" description: "Unit changes according to axis type. Linear Axis - μm and Rotary Axis - m°" quadrantError: allOf: - $ref: '#/components/schemas/ResultValue' - type: object properties: unit: type: string enum: [µm, m°] example: "μm" description: "Unit changes according to axis type. Linear Axis - μm and Rotary Axis - m°" signature: $ref: '#/components/schemas/Signature' equability: allOf: - $ref: '#/components/schemas/ResultValue' - type: object properties: unit: type: string enum: [N, Nm] example: "N" description: "Unit changes according to axis type. Linear Axis - N and Rotary Axis - Nm" frequencyResponse: allOf: - $ref: '#/components/schemas/ResultValue' - type: object properties: unit: type: string example: "Hz" Signature: type: object properties: order1: $ref: '#/components/schemas/SignatureOrder' order2: $ref: '#/components/schemas/SignatureOrder' order3: $ref: '#/components/schemas/SignatureOrder' order4: $ref: '#/components/schemas/SignatureOrder' order5: $ref: '#/components/schemas/SignatureOrder' valueUnit: type: string enum: [µm, m°] example: "µm" description: "Unit changes according to axis type. Linear Axis - μm and Rotary Axis - m°" status: type: string enum: [OK, Warning, Service] description: > Indicates that given threshold values are exceeded or not. * `OK`- Not Exceeded or no threshold is given * `Warning` - Warning threshold is exceeded * `Service` - Warning threshold is exceeded example: 'OK' SignatureOrder: type: object properties: order: type: number format: float example: 6.0 value: type: number format: float example: 2.43 ResultValue: type: object properties: value: type: number format: float example: 4.3 unit: type: string example: "N" status: type: string enum: [OK, Warning, Service, Error] description: > Indicates that given threshold values are exceeded or not. * `OK`- Not Exceeded or no threshold is given * `Warning` - Warning threshold is exceeded * `Service` - Service threshold is exceeded * `Error` - Measurement test execution failed example: 'OK' ResultValueWithoutStatus: type: object properties: value: type: number format: float example: 4.3 unit: type: string example: "N" PagedResult: type: object required: - content - totalPages - totalElements - last - numberOfElements - first - sort - size - number properties: content: type: array items: $ref: '#/components/schemas/Result' last: description: Whether the current item is the last one. type: boolean example: true totalPages: description: The number of total pages. type: integer example: 1 totalElements: description: The total amount of elements. type: integer example: 1 numberOfElements: description: The number of elements currently on this page. type: integer example: 1 first: description: Whether the current item is the first one. type: boolean example: true size: description: The size of the page. type: integer example: 20 number: description: The number of the current item. type: integer example: 0 FrictionGraphData: type: object description: Data encoded to Base64 format with UTF-8 character set. properties: torqueUnit: type: string example: "N" enum: [N, Nm] description: "Unit changes according to axis type. Linear Axis - N and Rotary Axis - Nm" torqueData: type: string format: byte example: U3dhZ2dlciByb2Nrcw== velocityUnit: type: string example: "m/min" enum: [m/min, rpm] description: "Unit changes according to axis type. Linear Axis - m/min and Rotary Axis - rpm" velocityData: type: string format: byte example: U3dhZ2dlciByb2Nrcw== StiffnessGraphData: type: object description: Data encoded to Base64 format with UTF-8 character set. properties: positionUnit: type: string example: "m" enum: [m, °] description: "Unit changes according to axis type. Linear Axis - m and Rotary Axis - °" stiffnessUnit: type: string example: "N" enum: [N, Nm/rad] description: "Unit changes according to axis type. Linear Axis - m/min and Rotary Axis - Nm/rad" xFitData: type: string format: byte example: U3dhZ2dlciByb2Nrcw== yFitData: type: string format: byte example: U3dhZ2dlciByb2Nrcw== BacklashGraphData: type: object description: Data encoded to Base64 format with UTF-8 character set properties: positionUnit: type: string example: "s" positionData: type: string format: byte example: U3dhZ2dlciByb2Nrcw== positionDifferenceUnit: type: string example: "µm" enum: [µm, m°] description: "Unit changes according to axis type. Linear Axis - µm and Rotary Axis - m°" positionDifferenceData: type: string format: byte example: U3dhZ2dlciByb2Nrcw== EquabilityGraphData: type: object description: Data encoded to Base64 format with UTF-8 character set. properties: filteredTorqueUnit: type: string example: "N" enum: [N, Nm] description: "Unit changes according to axis type. Linear Axis - N and Rotary Axis - Nm" positionUnit: type: string example: "mm" enum: [mm, °] description: "Unit changes according to axis type. Linear Axis - mm and Rotary Axis - °" filteredTorquePlusData: type: string format: byte example: U3dhZ2dlciByb2Nrcw== filteredTorqueMinusData: type: string format: byte example: U3dhZ2dlciByb2Nrcw== SignatureGraphData: type: object description: Data encoded to Base64 format with UTF-8 character set. properties: signatureOrderData: type: string format: byte example: U3dhZ2dlciByb2Nrcw== signatureMagnitudeUnit: type: string example: "m" enum: [m, °] description: "Unit changes according to axis type. Linear Axis - m and Rotary Axis - °" signatureMagnitudeData: type: string format: byte example: U3dhZ2dlciByb2Nrcw== FrequencyResponseGraphData: type: object description: Data encoded to Base64 format with UTF-8 character set. properties: amplitude: type: string format: byte example: U3dhZ2dlciByb2Nrcw== phase: type: string format: byte example: U3dhZ2dlciByb2Nrcw== frequency: type: string format: byte example: U3dhZ2dlciByb2Nrcw== MeasurementGroup: type: object required: - name - id - status - measurements properties: name: type: string maxLength: 40 example: 'MeasurementGroup 1' description: Name of the measurement group. id: type: string description: Unique identifier of the measurement group maxLength: 36 example: '3b27818ea09a46b48c7eb3fbd878349f' status: type: string example: 'DEFINED' measurements: type: array description: List of added measurements' ids. items: type: string example: 1 PagedMeasurementGroup: type: object required: - content - totalPages - totalElements - last - numberOfElements - first - sort - size - number properties: content: type: array items: $ref: '#/components/schemas/MeasurementGroup' last: description: Whether the current item is the last one. type: boolean example: true totalPages: description: The number of total pages. type: integer example: 1 totalElements: description: The total amount of elements. type: integer example: 1 numberOfElements: description: The number of elements currently on this page. type: integer example: 1 first: description: Whether the current item is the first one. type: boolean example: true size: description: The size of the page. type: integer example: 20 number: description: The number of the current item. type: integer example: 0