swagger: '2.0' info: title: Usage Transparency API description: | This API also allows platform and third party applications to record application usages by users/assets/tenants for billing, reporting, quota checking purposes. While adding the usages - UTS accepts all the data that is sent, provided it is in valid format and payload does not exceed the limit of usages count per request. - In case rules are configured for the usage units, the corresponding usage data is verified against the rule. - If verification fails, the data will be rejected and is not aggregated. - If /usagesJobs endpoint was used for sending the data, caller can query for the status of the data. - A rule is necessary in case the usages are to be billed. ## Limitations - The number of usages that can be added to UTS in a single request is limited to 200, regardless of whether usages are for single or multiple users. - Tenants can query the status of up to 1000 recent jobs that they created to add the usages to UTS. - The amount of operations performed that can be performed are limited per time, and may be throttled. ## Terms - Rule - Rules are created in UTS to define which valid data will be accepted as usage. - KPI - KPI are created in UTS to defined how the accepted usage data will be aggregated and made available for consumer. ### Generic Errors The following generic error codes might occur at any of the specified operations. Generic errors are prefixed with 'mdsp.core.generic.'. - 204: noContent - 400: invalidParameter - 400: invalidRequestBodyProperty - 400: missingParameter - 400: missingRequestBodyProperty - 401: unauthorized - 403: forbidden - 404: noMatch - 413: payloadTooLarge - 415: unsupportedMediaType - 429: tooManyRequests - 500: internalServerError version: 3.2.0 x-visibility: external schemes: - https securityDefinitions: uts: type: oauth2 flow: accessCode authorizationUrl: 'https://oauth.simple.api/authorization' tokenUrl: 'https://oauth.simple.api/token' scopes: uts.su: Grants access to (s)end (u)sage information uts.tu: Grant access to (t)rack the processing of (u)sages uts.r: Grants access to request for usages basePath: /api/usagetransparency/v3 ## ************************************************************************* ## ## ************************** API Methods ********************************** ## ## ************************************************************************* ## paths: ############################################ ## Add usages for single tenant and user. ## ############################################ /usages: post: security: - uts: - uts.su tags: - usage summary: Send application specific usages to UTS backend. description: >- This method can be used by operators and applications to send application specific usages (e.g. number of created report pages, CPU times per user, assets configured, etc.) to the UTS.
Use this endpoint to send USAGES of a SINGLE TENANT and USER to UTS.
Caller can use the GET /usagesJobs API to get the status of the sent data. consumes: - application/json produces: - application/json - text/plain parameters: - in: body name: usageData description: 'send object contains the usages.' required: true schema: $ref: '#/definitions/UserUsage' responses: '200': description: Data is successfully saved to the database '400': description: | Bad request. schema: $ref: '#/definitions/BadRequestErrorSchema' '401': description: Unauthorized schema: $ref: '#/definitions/UnauthorisedErrorSchema' '403': description: Access denied schema: $ref: '#/definitions/ForbiddenErrorSchema' #################################################################################### ## Jobs API to provide traceability and add usages for multiple tenants and user. ## #################################################################################### /usagesJobs: ## Add usages ## post: security: - uts: - uts.su tags: - usage-jobs-with-traceability summary: Add usages for one or more tenants, users and applications to UTS for storage and processing. description: | This method can be used by operators and applications to create a job that adds application specific usages (e.g. number of created report pages, CPU times per user, assets configured, etc.) to the UTS. - Maximum of 200 usages can be added by one job. Larger payloads are immediately and completely rejected. - Use this endpoint to add USAGES of MULTIPLE TENANTS and USERS to UTS. - The returned id can be used later to query the status of the UTS process for the job and added usages. - In case the usages need to be billed, a rule must be created in UTS. In case the userId is not provided in the payload, the tenantId is used as userId, also userType is then tenant. consumes: - application/json produces: - application/json parameters: - in: body name: usages description: list object of customer and user specific usages required: true schema: $ref: '#/definitions/Users' responses: '202': description: 'ACCEPTED' schema: $ref: '#/definitions/UsagesJob' '400': description: 'Provided request body is invalid' schema: $ref: '#/definitions/HTTPErrors' '413': description: 'Request payload is too large' schema: $ref: '#/definitions/HTTPErrors' ## Status of jobs ## get: security: - uts: - uts.su - uts.tu tags: - usage-jobs-with-traceability summary: Query status of processing for the jobs that added the usages. description: | Returns overall summary of the jobs and optionally the usages added using /usages APIs. - Callers are not usually expected to use this API as part of business workflow, but for 'in-frequent auditing'. - The calls to this method may be throttled. - Only 1000 latest jobs per operator tenant can be retrieved. - Description of job statuses. - ACCEPTED: A job is created, and the usages have been accepted. - INPROGRESS: Processing is on-going on at least one of the usages added by the job. - ERRORS: There is at least one error encountered while processing the usages. - COMPLETED: All the processes applicable to the usages have been completed. consumes: - application/json produces: - application/json parameters: - in: query name: date required: false type: string description: 'date on which usages had been added in yyyy-mm-dd format. default value is current date.' - in: query name: tenant required: false type: string description: 'tenant for which usage had been added' - in: query name: application required: false type: string description: 'application for which usage had been added' - in: query name: unit required: false type: string description: 'resource usage unit' - name: page in: query description: >- Page Number required: false type: integer default: 1 maximum: 20 - name: size in: query description: Page Size required: false type: integer default: 10 maximum: 100 responses: '200': description: 'job summaries retrieved' schema: $ref: '#/definitions/UsagesJobQueryResult' /usagesJobs/{id}: ## Status of usages added by a job ## get: security: - uts: - uts.su - uts.tu tags: - usage-jobs-with-traceability summary: Retrieve the status of processing of usages that were added by the job. description: | Returns status summary of the usages added by the data sent using /usages APIs. - Callers are not usually expected to use this API as part of business workflow, but for 'in-frequent auditing'. - The calls to this method may be throttled. - Description of usage statuses. - ACCEPTED: Usages have been accepted. - VERIFIED: Usages have been verified against the rules configured in rule engine, if applicable. - VERIFICATIONFAILED: Verification of at least one of the usages has failed. - NOVERIFICATION: No applicable rule was found and hence no verification was done. - AGGREGATED: Usages have been aggregated into a running daily aggregate value based on the aggregation function defined in UTS rule. In case no rule is applicable, default aggregation function 'SUM' is used. The aggregation is performed every hour and the daily aggregate is updated. Once aggregated, the UTS can be queried to report the usages through UI or data endpoints. - SENTFORBILLING: If billing is enabled for the usages, the data has been sent successfully to the billing system. - FAILEDTOSENDFORBILLING: Errors were encountered while sending the data to billing. These could be network issues or other internal errors. consumes: - application/json produces: - application/json parameters: - in: path name: id required: true type: string description: 'id of the job that was used to send the usages.' - name: page in: query description: 'page number' required: false type: integer default: 1 maximum: 10 - name: size in: query description: 'page size' required: false type: integer default: 200 responses: '200': description: 'usages summary for the job retrieved.' schema: $ref: '#/definitions/UsagesJobSummary' /usagesJobs/{id}/errors: ## Errors encountered in processing usages ## get: security: - uts: - uts.su - uts.tu tags: - usage-jobs-with-traceability summary: Retrieve the processing errors related the usages added by the job. description: | Returns the errors, if any, associated with a set of usages that were received by the identified job. - Callers are not usually expected to use this API as part of business workflow, but for 'in-frequent auditing'. - The calls to this method may be throttled. - In case of 'Verification Errors', the list of usages that failed verification is part of the errors. - In case of 'Billing Errors', billing ids are part of the error data. API users need to contact UTS team with the billing-ids to resolve the issues. consumes: - application/json produces: - application/json parameters: - in: path name: id required: true type: string description: 'id of the job that was used to send the usages.' - in: query name: errorClass required: false type: string description: Error Class - validation|billing|errors - name: page in: query description: >- Page Number required: false type: integer default: 1 - name: size in: query description: Page Size required: false type: integer default: 10 maximum: 100 responses: '200': description: 'usage errors retrieved.' schema: $ref: '#/definitions/UsageErrors' ############################################ ## Get usage as a consumer tenant. ## ############################################ /aggregatedMonthlyConsumerUsage: get: security: - uts: - uts.r tags: - aggregated-monthly-usage summary: Get monthly aggregated usages of rule enabled for consumer tenant. description: | Operator registers a KPI with UTS. Operator send the resource usage data of consumer to UTS. KPI contains the aggregation and unit conversion details which should be applied on received usages. Aggregation is executed and calculated values are shown in response. This API endpoint can be used by consumer tenant to see the aggregated usage calculated for month on prorate basis. consumes: - application/json produces: - application/json parameters: - name: month in: query description: month for which usage requested required: true type: string enum: [January, February, March, April, May, June, July, August, September, October, November, December] - name: year in: query description: year required: true type: string - name: provider in: query description: provider tenant Id required: true type: string - name: application in: query description: application name registered on gateway required: true type: string - name: KPIName description: name of the KPI registered with UTS for application in: query required: true type: string responses: '200': description: 'OK' schema: $ref: '#/definitions/aggregatedTenantUsageData' '400': description: 'BAD REQUEST' schema: $ref: '#/definitions/HTTPErrorsV3' '404': description: Unauthorized schema: $ref: '#/definitions/HTTPErrorsV3' /aggregatedMonthlyProviderUsage: get: security: - uts: - uts.r tags: - aggregated-monthly-usage summary: Get monthly aggregated usages for rule enabled to consumer tenants. description: | Operator registers a KPI with UTS. Operator send the resource usage data of consumer to UTS. KPI contains the aggregation and unit conversion details which should be applied on received usages. Aggregation is executed and calculated values are shown in response. This API endpoint can be used by provider tenant to see the aggregated usage calculated for month on prorate basis for various consumers. consumes: - application/json produces: - application/json parameters: - name: month in: query description: month for which usage requested required: true type: string enum: [January, February, March, April, May, June, July, August, September, October, November, December] - name: year in: query description: year required: true type: string - name: consumer in: query description: consumer tenant id type: string - name: application in: query description: application name registered on gateway required: true type: string - name: KPIName description: name of the KPI registered with UTS for application in: query required: true type: string - $ref: '#/parameters/page' - $ref: '#/parameters/size' responses: '200': description: 'OK' schema: $ref: '#/definitions/aggregatedMonthyOperatorUsages' '400': description: 'BAD REQUEST' schema: $ref: '#/definitions/HTTPErrorsV3' '404': description: Unauthorized schema: $ref: '#/definitions/HTTPErrorsV3' parameters: page: name: page in: query type: integer description: specifies the requested page index. default: 0 size: name: size in: query type: integer description: specifies the number of elements in a page default: 20 ## ************************************************************************* ## ## ************************** Model Definitions## ************************** ## ## ************************************************************************* ## definitions: ################################ ## To Be Deprecated UTS Model ## ################################ UserUsage: type: object required: - CustomerTenantID - CustomerUserID - UTSUsageData properties: CustomerTenantID: type: string example: test CustomerUserID: type: string example: test@gmail.com UTSUsageData: type: array items: $ref: '#/definitions/ApplicationUsage' ApplicationUsage: type: object properties: resourceAlias: type: string example: 'assetmonitor' description: 'an application that consumes or manipulates a resource and provides some service. an application is the main actor that generates usages' resourceName: type: string example: 'assetid1' description: | a resource for which the usage is being reported by the application (resourceAlias), e.g asset, user, app, action, url, operation. If user want to send multiple keywords as a value for resourceName then hyphen (-) should be used to separate the keywords. UsageData: type: array items: $ref: '#/definitions/ResourceUsage' ResourceUsage: type: object properties: usage: type: integer example: 20 usageUnit: type: string example: 'asset-count' description: 'represents an action performed by the application, e.g. sending sms, onboarding of asset, etc.' usageDate: type: string example: '2011-07-14T19:43:37+0100' ############################## ## Models tenant usage data ## ############################## aggregatedTenantUsageData: type: object properties: provider: type: string example: provider description: the tenant id which owns the application application: type: string example: assetmonitor description: the application name registered on gateway applicationDisplayName: type: string example: Asset Monitor description: the application display name KPIName: type: string example: asset-count description: rule name registered with UTS KPIDisplayName: type: string example: asset count description: the display name of rule which is known to consumer aggregationUntilDate: type: string example: '2011-07-14' description: 'date until received data is aggregated in UTC timezone.' year: type: string example: '2021' description: year for which the usages are requested month: type: string example: 'january' description: month for which the usages are requested aggragationFunction: $ref: '#/definitions/aggregationFunction' allOf: # Combines the package and the inline model - $ref: '#/definitions/aggregatedUsageData' aggregationFunction: type: object properties: aggregationFunctionDaily: type: string description: these are UTS supported aggregation functions for day. enum: - MIN - MAX - AVERAGE - SUM - COUNT - LAST - FIRST example: SUM aggregationFunctionMonthly: type: string description: these are UTS supported aggregation functions for month. enum: - MIN - MAX - AVERAGE - SUM - COUNT - LAST - FIRST - AVERAGE_DAYS_IN_MONTH example: SUM preFill: type: string description: the aggregate function computes the billing unit for the day. The preFill option provides you a way to configure the behaviour when no data is received for a defined rule then should UTS consider it as empty , zero or it should use the value from previous day. enum: - ZERO - EMPTY - PREVIOUS example: ZERO aggregatedUsageData: type: object required: - consumer - value properties: consumer: type: string example: bmw description: the tenant id which has used provider application value: type: integer example: 20 description: 'represents the amount of units consumed.' ############################ ## Models for usage details# ############################ aggregatedMonthyOperatorUsages: type: object properties: provider: type: string example: provider description: the operator which owns the application application: type: string example: assetmonitor description: the application name registered on gateway applicationDisplayName: type: string example: Asset Monitor description: the application display name KPIName: type: string example: asset-count description: rule name registered with UTS KPIDisplayName: type: string example: asset count description: the display name of rule which is known to consumer aggregationUntilDate: type: string example: '2011-07-14' description: 'date until received data is aggregated in UTC timezone.' year: type: string example: '2021' description: year for which the usages are requested month: type: string example: 'january' description: month for which the usages are requested aggregatedUsages: type: array items: $ref: '#/definitions/aggregatedUsageData' aggragationFunction: $ref: '#/definitions/aggregationFunction' page: $ref: '#/definitions/Page' BadRequestErrorSchema: $ref: '#/definitions/HTTPErrorsWithStatus' ForbiddenErrorSchema: $ref: '#/definitions/HTTPErrorsWithStatus' UnauthorisedErrorSchema: $ref: '#/definitions/HTTPErrorsWithStatus' HTTPErrorsWithStatus: type: object properties: code: type: string description: 'UTS specific error code' example: 'UTS-Exxx|mdsp...' message: type: string description: 'error message in English' example: '' logref: type: string description: 'log correlation-id' example: '0bff7e7a-cd25-4576-9908-4180ef086174' status: type: integer example: 403 ####################### ## UTS Usages Models ## ####################### Users: type: object required: - users properties: users: type: array items: $ref: '#/definitions/User' User: type: object required: - tenantId - resources properties: tenantId: type: string example: test userId: type: string example: test@gmail.com userType: type: string enum: - tenant - user - agent example: user default: tenant description: 'type of user i.e. interactive user, an agent or usage corresponds to entire tenant. if not specified, default is ‘user' resources: type: array items: $ref: '#/definitions/ApplicationResource' ApplicationResource: type: object required: - application - resource - usages properties: application: type: string example: 'assetmonitor' description: 'an application that consumes or manipulates a resource and provides some service. an application is the main actor that generates usages. the name should be same as the registered application name. in case no application is specified, alias name will be considered as the application name.' alias: type: string example: 'analyze-my-performance' description: 'an application may realize multiple business cases, in such a case aliases can be used to distinguish between the business cases realized by same application. alias should be named so that it conveys the underlying business case. in case no alias is provided, application name will be considered as the alias.' resource: type: string example: 'assetid1' description: | a resource for which the usage is being reported by the application (resourceAlias), e.g asset, user, app, action, url, operation. If user want to send multiple keyword as a value for resourceName then hyphen (-) should be used to Separate the keywords. usages: type: array items: $ref: '#/definitions/Usage' Usage: type: object required: - value - unit - datetime properties: value: type: integer example: 20 description: 'represents the amount of units consumed.' unit: type: string example: 'asset-count' description: 'represents a trackable or billable action performed by the application, e.g. sending SMS, onboarding of asset, etc.' datetime: type: string example: '2011-07-14T19:43:37Z' description: 'time at which the usage occurred, in UTC clock time.' ############################################# ## Models for Reporting UTS Process Status ## ############################################# UsagesJob: type: object properties: id: type: string example: '35a4cb01-2497-4191-ad1c-551a1942c409-20190520131' description: 'the id recevied in response to /usagesJobs endpoint' time: type: string example: '2011-07-14T19:43:37Z' status: type: string description: 'the status is based on the status of the usages that satisfy the query.' enum: - ACCEPTED - INPROGRESS - ERRORS - COMPLETED usagesCount: type: integer description: 'number of usages that satisfy the query and identified by the id.' example: 7 UsagesSummary: type: object properties: application: type: string example: 'assetmonitor' unit: type: string example: 'asset-count' usagesCount: type: integer description: 'number of usages that satisfy the query within the application, unit, and job id.' example: 2 processStatus: type: string enum: - ACCEPTED - VERIFIED - VERIFICATIONFAILED - NOVERIFICATION - AGGREGATED - SENTFORBILLING - FAILEDTOSENDFORBILLING - RECEIVEDFORBILLING UsagesJobSummary: allOf: - $ref: '#/definitions/UsagesJob' - type: object properties: usagesSummary: type: array items: $ref: '#/definitions/UsagesSummary' page: $ref: '#/definitions/Page' UsagesJobQueryResult: type: object properties: jobs: type: array items: $ref: '#/definitions/UsagesJob' page: $ref: '#/definitions/Page' ######################## ## Common Error Model ## ######################## Error: type: object properties: code: type: string description: ' mdsp...' example: 'mdsp...' message: type: string description: 'error message in english' example: '' messageParameters: type: array items: type: object properties: name: type: string example: name1 value: type: string example: value1 logref: type: string description: 'log correlation-id' example: '0bff7e7a-cd25-4576-9908-4180ef086174' ############################ ## Models for HTTP Errors ## ############################ HTTPErrors: type: object properties: errors: type: array items: $ref: '#/definitions/Error' ##################################### ## Error models for UTS processing ## ##################################### UsageError: allOf: - $ref: '#/definitions/Error' - properties: errorType: type: string enum: - ValidationError - BillingError - OtherError info: type: string description: 'reference to more information if available' example: 'http://developer.mindsphere.io/uts/documentation/billing' discriminator: errorType ############################ ## MDSP Errors Schema ## ############################ HTTPErrorsV3: type: object properties: errors: type: array description: Array of errors. items: properties: code: type: string description: uts error code as per MDSP standard. example: 'mdsp.core.uts.' message: type: string description: Detailed description of error. example: '' logref: type: string description: Log reference id. example: '737b7f76-50aa-4169-bd74-6c8a0edbe922' UsageErrors: type: object properties: errors: type: array items: $ref: '#/definitions/UsageError' page: $ref: '#/definitions/Page' ################################# ## Common Model for Pagination ## ################################# Page: type: object properties: number: type: integer example : 2 size: type: integer example : 10 totalElements: type: integer example : 40 totalPages: type: integer example : 4 title: PageDetails