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