meshcloud meshMetering API Docs

Introduction

All public REST endpoints of the meshMetering API are described in this documentation. These endpoints allow integration with company processes and existing tools. We also provide a Postman collection and openAPI documentation.

Postman Collection

OpenAPI documentation

The first step for being able to use the new Postman Collection is to import it in Postman. To proceed, configure the credentials in the "Authorization" tab of this collection. These credentials can be retrieved from the panel by creating a new API User or by using the credentials of an already created API User. Finally, set the hostname variable to ensure that the requests are ready to be executed.

Authentication

Before you start interacting with any of the endpoints we offer, make sure that you acquired valid HTTP Basic Auth credentials. API users, which can be used for basic auth, can be created via meshPanel. These API users are only available for users with Partner Admin rights.

Each endpoint listed in the documentation is secured via HTTP Basic Auth. To authenticate requests, please set the Authorization header as such:

Authorization: Basic <base64 encoded username:password>

All endpoints are encrypted via SSL and can only be called via HTTPS.

Technical Specification

This section describes technical details of the meshStack API, such as the exact data types it provides or HTTP specifics.

HTTP verbs

meshStack tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.

Verb Usage

Verb	Usage
`GET`	Used to retrieve a resource
`POST`	Used to create a new resource
`PATCH`	Used to update an existing resource, including partial updates
`PUT`	Used to update an existing resource, full updates only
`DELETE`	Used to delete an existing resource

GET

Used to retrieve a resource

POST

Used to create a new resource

PATCH

Used to update an existing resource, including partial updates

PUT

Used to update an existing resource, full updates only

DELETE

Used to delete an existing resource

HTTP status codes

meshStack tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes.

Status code Usage

Status code	Usage
`200 OK`	Standard response for successful HTTP requests. The actual response will depend on the request method used. In a GET request, the response will contain an entity corresponding to the requested resource. In a POST request, the response will contain an entity describing or containing the result of the action.
`201 Created`	The request has been fulfilled and resulted in a new resource being created.
`204 No Content`	The server successfully processed the request, but is not returning any content.
`400 Bad Request`	The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
`401 Unauthorized`	The server cannot authorize the request. Check the Basic Auth credentials used for the request.
`403 Forbidden`	The request is not allowed for the authorized user.
`404 Not Found`	The requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissible.
`409 Conflict`	The request leads to a conflict. A resource or a unique identifier used in the request already exists.

200 OK

Standard response for successful HTTP requests.
The actual response will depend on the request method used.
In a GET request, the response will contain an entity corresponding to the requested resource.
In a POST request, the response will contain an entity describing or containing the result of the action.

201 Created

The request has been fulfilled and resulted in a new resource being created.

204 No Content

The server successfully processed the request, but is not returning any content.

400 Bad Request

The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).

401 Unauthorized

The server cannot authorize the request. Check the Basic Auth credentials used for the request.

403 Forbidden

The request is not allowed for the authorized user.

404 Not Found

The requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissible.

409 Conflict

The request leads to a conflict. A resource or a unique identifier used in the request already exists.

Data Types

Dates are always handled as UTC dates and formatted to ISO 8601 standard (e.g. 2020-12-22T09:37:43Z).
String fields are usually limited to 255 characters

Hypermedia

meshStack uses hypermedia. Resources include links to other resources in their responses. Responses are in Hypertext Application Language (HAL) format. Links can be found beneath the _links key. Users of the API should not create URIs themselves, instead they should use the above-described links to navigate from resource to resource.

Notice that HAL hrefs can be templated: For example, if an endpoint requires a path variable, the _links array may include an entry like the following:

{
  "_links" : {
    "users" : {
      "href" : "https://example-url.org/api/users/{username}",
      "templated" : true
    }
  }
}

Please refer to the HAL specification for more details about template URIs.

Versioning

meshStack applies versioning via custom Media Types. This allows custom versioning per resource. As meshStack is developed and deployed continuously, this custom versioning per resource is the best way for applying versioning. If e.g. the meshWorkspace response is modified in an incompatible way, a new version will be provided for meshWorkspaces and all other resources are untouched.

If using a request body, such as when inserting a new meshProject via a POST endpoint, the custom media type must be provided in the Content-Type header. In case of a response body, such as when requesting a list of all meshWorkspaces via a GET endpoint, the client should send the custom media type in the Accept header.

Examples for these headers are:

Accept: application/vnd.meshcloud.api.meshworkspace.v1.hal+json

Content-Type: application/vnd.meshcloud.api.meshobjectcollection.v1+json;charset=UTF-8

Which Media Type is required for which resource is described in the according Resource section. If a request body is required and a different Content-Type like simple application/json is requested, the endpoint will return an error.

If the Accept header is not provided, you may get the response of any version. Therefore please always provide the Accept header so you are guaranteed to get the resource in the expected format.

Common Data Formats

This section describes common data formats that are used across different endpoints.

Paging

Paged list endpoints support two request parameters for pagination, page and size.

Parameter Description

Parameter	Description
`page`	The number of the page you want to retrieve (default=0).
`size`	The amount of elements in a single page (default={default-page-size}). Note: You can size up to {max-page-size}. Greater values will be automatically lowered to this value.

page

The number of the page you want to retrieve (default=0).

size

The amount of elements in a single page (default={default-page-size}). Note: You can size up to {max-page-size}. Greater values will be automatically lowered to this value.

Responses are structured like the following snippet:

{
    "_embedded": { }
    "_links": {
        "self" : {
          "href" : "https://mesh-billing-url/api/meshobjects/meshchargebacks"
        },
        "first" : {
          "href" : "https://mesh-billing-url/api/meshobjects/meshchargebacks?page=0&size=20"
        },
        "prev" : {
          "href" : "https://mesh-billing-url/api/meshobjects/meshchargebacks?page=0&size=20"
        },
        "next" : {
          "href" : "https://mesh-billing-url/api/meshobjects/meshchargebacks?page=2&size=20"
        },
        "last" : {
          "href" : "https://mesh-billing-url/api/meshobjects/meshchargebacks?page=3&size=20"
        }
    }
    "page": {
        "size": 20,
        "totalElements": 64,
        "totalPages": 4,
        "number": 0
    }
}

The above example is taken from the meshWorkspace list endpoint. All relevant paging information is provided in the 'page' element. In addition to that the links to the first page, the next page (if exists), the previous page (if exists) and the last page are provided as well. Pagination links are only provided, if there is more than one page available for the given pagination parameters.

Scalability

This API is designed to handle a large volume of requests while maintaining optimal performance. However, it’s important to note that scaling requests may become a problem if the API is not used in a conform way. In this document, we will discuss how to use the API in a way that will allow for seamless scaling of requests.

Scaling requests is not a problem as long as the API is used in a conform way. Conformity means adhering to the following best practices:

Use pagination to limit the number of results returned in each response. This will reduce the amount of data that needs to be transferred and processed.
Use caching to store frequently requested data. This will reduce the load on the API and improve response times.
When possible, use filters to limit the number of requests to your dedicated use case

By following the best practices outlined in this document, you can ensure that the API can handle your requests without any issues. If you have any questions or concerns about scaling requests, please contact the support team for assistance.

Resources

Index

This is the entry point to navigate through the API of meshStack Metering. Starting from here you will be able to find all endpoints your authenticated user has access to.

Request Headers
Name	Description
`Accept`	meshApi is versioned and you should use `application/vnd.meshcloud.api.v1.hal+json` as an `Accept` header to be guaranteed the V1 response format of this endpoint. New versions will be added in future.

Example Request

GET /api HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.v1.hal+json
Host: mesh-billing-url

Example Curl Request

$ curl 'https://mesh-billing-url/api' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.v1.hal+json'

Response Fields
Path	Type	Description
`_links`	`Object`	All available Top-Level Links for the authenticated user.

Links

List of all top-level endpoints the authenticated user has access to. Depending on your rights, you will only get a subset of the links mentioned here.

Relation Description

Relation	Description
`cloudresources`	The Cloud Resources API to retrieve cloud resources from meshStack.
`meshobjects`	The MeshObjects API to get meshObjects.

cloudresources

The Cloud Resources API to retrieve cloud resources from meshStack.

meshobjects

The MeshObjects API to get meshObjects.

Example Response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/vnd.meshcloud.api.v1.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 366

{
  "_links" : {
    "cloudresources" : {
      "href" : "https://mesh-billing-url/external/resources/v2{?customer,project,platform,displayName,resourceType,resourceStatus}",
      "templated" : true
    },
    "meshobjects" : {
      "href" : "https://mesh-billing-url/api/meshobjects"
    },
    "self" : {
      "href" : "https://mesh-billing-url/api"
    }
  }
}

meshObjects

Via this API you can get meshObjects from meshMetering.

Request Headers
Name	Description
`Accept`	meshApi is versioned and you should use `application/vnd.meshcloud.api.meshobjects.v1.hal+json` as an `Accept` header to be guaranteed the V1 response format of this endpoint. New versions will be added in future.

Example Request

GET /api/meshobjects HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshobjects.v1.hal+json
Host: mesh-billing-url

Example Curl Request

$ curl 'https://mesh-billing-url/api/meshobjects' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshobjects.v1.hal+json'

Response Fields
Path	Type	Description
`_links`	`Object`	All available meshObject Links for the authenticated user.

Links

List of all meshObject endpoints the authenticated user has access to. Depending on your rights, you will only get a subset of the links mentioned here.

Relation Description

Relation	Description
`meshtenantusagereports`	Get meshTenantUsageReports.
`meshchargebacks`	Get meshChargebacks.

meshtenantusagereports

Get meshTenantUsageReports.

meshchargebacks

Get meshChargebacks.

Example Response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/vnd.meshcloud.api.meshobjects.v1.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 578

{
  "_links" : {
    "meshtenantusagereports" : {
      "href" : "https://mesh-billing-url/api/meshobjects/meshtenantusagereports{?workspaceIdentifier,projectIdentifier,platformFullIdentifier,period,reportCategory,paymentIdentifier}",
      "templated" : true
    },
    "meshchargebacks" : {
      "href" : "https://mesh-billing-url/api/meshobjects/meshchargebacks{?workspaceIdentifier,projectIdentifier,period,finalized,legacy,finalizedSince,cancelledSince}",
      "templated" : true
    },
    "self" : {
      "href" : "https://mesh-billing-url/api/meshobjects"
    }
  }
}

meshTenantUsageReports

All endpoints on meshTenantUsageReports.

List meshTenantUsageReports

Provides a paged list of meshTenantUsageReports.

Note: If no request parameters for filtering are specified, all meshTenantUsageReports are returned independently of these parameters. By default, meshTenantUsageReports are sorted descending by period.

Request Headers
Name	Description
`Accept`	meshApi is versioned and you should use `application/vnd.meshcloud.api.meshtenantusagereport.v2.hal+json` as an `Accept` header to be guaranteed the V2 response format of this endpoint. New versions might be added in future.

Request Parameters
Parameter	Description
`partnerIdentifier`	Filter for meshTenantUsageReports that belong to the partner with given identifier. (optional)
`workspaceIdentifier`	Filter for meshTenantUsageReports that belong to the meshWorkspace with given identifier. (optional)
`projectIdentifier`	Filter for meshTenantUsageReports that belong to the meshProject with given identifier. (optional)
`platformFullIdentifier`	Filter for meshTenantUsageReports that belong to the provided platform in the format '<platform>.<location>' (optional)
`paymentIdentifier`	Filter for meshTenantUsageReports that have the meshPaymentMethod with given identifier assigned. Use an empty or blank value to filter for meshTenantUsageReports without an assigned meshPaymentMethod. (optional)
`period`	Filter for meshTenantUsageReports that belong to the provided period, e.g. '2022-01-06Z' (optional)
`reportCategory`	Filter for meshTenantUsageReports that belong to the provided reportCategory, 'BILLING' or 'ENVIRONMENTAL'. (optional)
`page`	The page number (default=0). See Paging information.
`size`	The amount of elements in a single page (default={default-page-size}). See Paging information.
`sort`	A custom order for sorting the results (optional). For meshTenantUsageReports it is possible to filter by the following fields: workspaceIdentifier, customerIdentifier, projectIdentifier, platformFullIdentifier, period, reportCategory. Possible directions are 'asc' or 'desc'. (e.g. sort=workspaceIdentifier,desc)

Example Request

GET /api/meshobjects/meshtenantusagereports?workspaceIdentifier=testWorkspace&page=0&size=10&sort=period,desc HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshtenantusagereport.v2.hal+json
Host: mesh-billing-url

Example Curl Request

$ curl 'https://mesh-billing-url/api/meshobjects/meshtenantusagereports?workspaceIdentifier=testWorkspace&page=0&size=10&sort=period,desc' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshtenantusagereport.v2.hal+json'

Response Fields
Path	Type	Description
`_embedded`	`Object`	Contains the actual content of the paged response.
`_embedded.meshTenantUsageReports[]`	`Array`	List of meshTenantUsageReport.
`page`	`Object`	See Paging information.
`_links`	`Object`	Currently only contains the self link and pagination links.

Example Response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/vnd.meshcloud.api.meshtenantusagereport.v2.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 1383

{
  "_embedded" : {
    "meshTenantUsageReports" : [ {
      "kind" : "meshTenantUsageReport",
      "apiVersion" : "v2",
      "metadata" : {
        "name" : "gcp1.gcp-ffm:project:2018-01-01Z",
        "lastModified" : "2024-11-20T16:04:18.032156600Z",
        "finalized" : true
      },
      "spec" : {
        "period" : "2018-01-01Z",
        "reportCategory" : "BILLING",
        "platformType" : "Gcp",
        "platformFullIdentifier" : "gcp1.gcp-ffm",
        "platformTenantId" : "project"
      },
      "status" : {
        "projectIdentifier" : "testProject",
        "timeframe" : {
          "from" : "2024-11-01T00:00:00Z",
          "to" : "2024-12-01T00:00:00Z"
        },
        "netAmounts" : [ {
          "currency" : "EUR",
          "amount" : 128,
          "baseCurrency" : "EUR",
          "baseAmount" : 0
        } ],
        "workspaceIdentifier" : "testWorkspace"
      },
      "_links" : {
        "self" : {
          "href" : "https://mesh-billing-url/api/meshobjects/meshtenantusagereports/gcp1.gcp-ffm%3Aproject/2018-01-01Z"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://mesh-billing-url/api/meshobjects/meshtenantusagereports?workspaceIdentifier=testWorkspace&page=0&size=10&sort=period,desc"
    }
  },
  "page" : {
    "size" : 10,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

Get meshTenantUsageReport

Get a single meshTenantUsageReport.

Request Headers
Name	Description
`Accept`	meshApi is versioned and you should use `application/vnd.meshcloud.api.meshtenantusagereport.v2.hal+json` as an `Accept` header to be guaranteed the V1 response format of this endpoint. New versions might be added in future.

Example Request

GET /api/meshobjects/meshtenantusagereports/gcp1.gcp-ffm%253Aproject/2018-01-01Z HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshtenantusagereport.v2.hal+json
Host: mesh-billing-url

Example Curl Request

$ curl 'https://mesh-billing-url/api/meshobjects/meshtenantusagereports/gcp1.gcp-ffm%253Aproject/2018-01-01Z' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshtenantusagereport.v2.hal+json'

Response Fields
Path	Type	Description
`apiVersion`	`String`	Version of meshTenantUsageReport datatype. Matches the version provided in the `Accept` request header.
`kind`	`String`	As a common meshObject structure exists, every meshObject has a 'kind'. This is always 'meshTenantUsageReport' for this endpoint.
`metadata`	`Object`	Contains attributes to identify a meshTenantUsageReport.
`metadata.name`	`String`	A name a meshTenantUsageReport can be uniquely identified with.
`metadata.lastModified`	`String`	Date of last update to the meshTenantUsageReport.
`metadata.finalized`	`Boolean`	Indicator whether the meshTenantUsageReport was finalized already or not.
`spec`	`Object`	All fields in this section describe the meshTenantUsageReport.
`spec.platformType`	`String`	The platformType of the platform the meshTenantUsageReport belongs to.
`spec.platformFullIdentifier`	`String`	The platformFullIdentifier of the platform the meshTenantUsageReport belongs to.
`spec.period`	`String`	The period of the meshTenantUsageReport, e.g. '2022-01-06Z'.
`spec.reportCategory`	`String`	The reportCategory of the meshTenantUsageReport, possible options are 'BILLING' or 'ENVIRONMENTAL'.
`spec.platformTenantId`	`String`	The platformTenantId that the meshTenantUsageReport belongs to.
`status`	`Object`	All fields in this section provide detailed content of the meshTenantUsageReport.
`status.workspaceIdentifier`	`String`	The identifier of the meshWorkspace the meshTenantUsageReport belongs to. (optional)
`status.projectIdentifier`	`String`	The identifier of the meshProject the meshTenantUsageReport belongs to. (optional)
`status.timeframe`	`Object`	This provides actual details about the period the meshTenantUsageReport was generated for.
`status.timeframe.from`	`String`	At which point in time the period started (usually beginning of month).
`status.timeframe.to`	`String`	Before which point in time the period ended (usually beginning of next month).
`status.netAmounts[]`	`Array`	A list of total reported amounts separated by currency.
`status.netAmounts[].currency`	`String`	The currency used for the corresponding amount.
`status.netAmounts[].baseCurrency`	`String`	Currency for the baseAmount. This value is either null or EUR.
`status.netAmounts[].amount`	`Number`	The concrete amount of reported costs in the corresponding currency.
`status.netAmounts[].baseAmount`	`Number`	The converted amount. For example, if currency is USD and baseCurrency is EUR, this will be the amount resulting from conversion from USD to EUR.
`_links`	`Object`	Available links [links] on a meshTenantUsageReport.

Example Response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/vnd.meshcloud.api.meshtenantusagereport.v2.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 899

{
  "kind" : "meshTenantUsageReport",
  "apiVersion" : "v2",
  "metadata" : {
    "name" : "gcp1.gcp-ffm:project:2018-01-01Z",
    "lastModified" : "2024-11-20T16:04:18.032156600Z",
    "finalized" : true
  },
  "spec" : {
    "period" : "2018-01-01Z",
    "reportCategory" : "BILLING",
    "platformType" : "Gcp",
    "platformFullIdentifier" : "gcp1.gcp-ffm",
    "platformTenantId" : "project"
  },
  "status" : {
    "projectIdentifier" : "testProject",
    "timeframe" : {
      "from" : "2024-11-01T00:00:00Z",
      "to" : "2024-12-01T00:00:00Z"
    },
    "netAmounts" : [ {
      "currency" : "EUR",
      "amount" : 128,
      "baseCurrency" : "EUR",
      "baseAmount" : 0
    } ],
    "workspaceIdentifier" : "testWorkspace"
  },
  "_links" : {
    "self" : {
      "href" : "https://mesh-billing-url/api/meshobjects/meshtenantusagereports/gcp1.gcp-ffm%3Aproject/2018-01-01Z"
    }
  }
}

meshChargebacks

All endpoints on meshChargebacks.

List meshChargebacks

Provides a paged list of meshChargebacks.

Note: If no request parameters for filtering are specified, all meshChargebacks are returned independently of these parameters. By default, meshChargebacks are sorted descending by period.

Request Headers
Name	Description
`Accept`	meshApi is versioned and you should use `application/vnd.meshcloud.api.meshchargeback.v3.hal+json` as an `Accept` header to be guaranteed the V3 response format of this endpoint. New versions might be added in future.

Request Parameters
Parameter	Description
`workspaceIdentifier`	Filter for meshChargebacks that belong to the meshWorkspace with given identifier. (optional)
`projectIdentifier`	Filter for meshChargebacks that belong to the meshProject with given identifier. (optional)
`period`	Filter for meshChargebacks that belong to the provided period, e.g. '2022-01-06Z' (optional)
`finalized`	Filter for finalized or preview meshChargebacks. Provide 'true' to get finalized meshChargebacks or provide 'false' to get preview meshChargebacks.
`page`	The page number (default=0). See Paging information.
`size`	The amount of elements in a single page (default={default-page-size}). See Paging information.
`sort`	A custom order for sorting the results (optional). For meshChargebacks it is possible to filter by the following fields: name, customerIdentifier, projectIdentifier, period, partnerIdentifier. Possible directions are 'asc' or 'desc'. (e.g. sort=name,desc)

Example Request

GET /api/meshobjects/meshchargebacks?workspaceIdentifier=testWorkspace&page=0&size=10&sort=name,desc HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshchargeback.v3.hal+json
Host: mesh-billing-url

Example Curl Request

$ curl 'https://mesh-billing-url/api/meshobjects/meshchargebacks?workspaceIdentifier=testWorkspace&page=0&size=10&sort=name,desc' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshchargeback.v3.hal+json'

Response Fields
Path	Type	Description
`_embedded`	`Object`	Contains the actual content of the paged response.
`_embedded.meshChargebacks[]`	`Array`	List of meshChargeback.
`page`	`Object`	See Paging information.
`_links`	`Object`	Currently only contains the self link and pagination links.

Example Response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/vnd.meshcloud.api.meshchargeback.v3.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 3377

{
  "_embedded" : {
    "meshChargebacks" : [ {
      "kind" : "meshChargeback",
      "apiVersion" : "v3",
      "metadata" : {
        "name" : "2024-11-01Z/testPartner:testWorkspace:testProject",
        "createdOn" : "2024-11-20T16:04:15.549958700Z",
        "finalized" : true
      },
      "spec" : {
        "projectIdentifier" : "testProject",
        "period" : "2024-11-01Z",
        "tags" : {
          "paymentIdentifier" : [ "123" ]
        },
        "workspaceIdentifier" : "testWorkspace"
      },
      "status" : {
        "timeframe" : {
          "from" : "2024-11-01T00:00:00Z",
          "to" : "2024-12-01T00:00:00Z"
        },
        "lineItems" : [ {
          "reportCategory" : "BILLING",
          "platformTenantId" : "test1-localProjectId",
          "platformFullIdentifier" : "test1-instance.test1-location",
          "reportId" : "test1-reportId",
          "entryDate" : "2019-08-03T00:07:01.289Z",
          "period" : "2019-07-01Z",
          "netAmount" : 1.65,
          "baseNetAmount" : 1.65,
          "baseCurrency" : "EUR",
          "exchangeRate" : 1,
          "currency" : "EUR",
          "sellerId" : "Operations",
          "sellerProductGroup" : "Platform Team"
        }, {
          "reportCategory" : "BILLING",
          "platformTenantId" : "test2-localProjectId",
          "platformFullIdentifier" : "test2-instance.test2-location",
          "reportId" : "test2-reportId",
          "entryDate" : "2019-08-03T00:07:01.289Z",
          "period" : "2019-07-01Z",
          "netAmount" : 3.12,
          "baseNetAmount" : 3.12,
          "baseCurrency" : "EUR",
          "exchangeRate" : 1,
          "currency" : "EUR",
          "sellerId" : "Operations",
          "sellerProductGroup" : "Platform Team"
        } ],
        "netAmounts" : [ {
          "currency" : "EUR",
          "amount" : 4.77,
          "baseCurrency" : "EUR",
          "baseNetAmount" : 4.77
        } ]
      },
      "_links" : {
        "self" : {
          "href" : "https://mesh-billing-url/api/meshobjects/meshchargebacks/2024-11-01Z/testPartner%3AtestWorkspace%3AtestProject"
        }
      }
    }, {
      "kind" : "meshChargeback",
      "apiVersion" : "v3",
      "metadata" : {
        "name" : "2024-10-01Z/testPartner:testWorkspace:testProject",
        "createdOn" : "2024-11-20T16:04:15.551805700Z",
        "finalized" : true
      },
      "spec" : {
        "projectIdentifier" : "testProject",
        "period" : "2024-10-01Z",
        "tags" : { },
        "workspaceIdentifier" : "testWorkspace"
      },
      "status" : {
        "timeframe" : {
          "from" : "2024-10-01T00:00:00Z",
          "to" : "2024-11-01T00:00:00Z"
        },
        "lineItems" : [ ],
        "netAmounts" : [ {
          "currency" : "EUR",
          "amount" : 0,
          "baseCurrency" : "EUR",
          "baseNetAmount" : 0
        } ]
      },
      "_links" : {
        "self" : {
          "href" : "https://mesh-billing-url/api/meshobjects/meshchargebacks/2024-10-01Z/testPartner%3AtestWorkspace%3AtestProject"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://mesh-billing-url/api/meshobjects/meshchargebacks?workspaceIdentifier=testWorkspace&page=0&size=10&sort=name,desc"
    }
  },
  "page" : {
    "size" : 10,
    "totalElements" : 2,
    "totalPages" : 1,
    "number" : 0
  }
}

Get meshChargeback

Get a single meshChargeback.

Request Headers
Name	Description
`Accept`	meshApi is versioned and you should use `application/vnd.meshcloud.api.meshchargeback.v3.hal+json` as an `Accept` header to be guaranteed the V3 response format of this endpoint. New versions might be added in future.

Example Request

GET /api/meshobjects/meshchargebacks/2024-11-01Z/testPartner%253AtestWorkspace%253AtestProject HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshchargeback.v3.hal+json
Host: mesh-billing-url

Example Curl Request

$ curl 'https://mesh-billing-url/api/meshobjects/meshchargebacks/2024-11-01Z/testPartner%253AtestWorkspace%253AtestProject' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshchargeback.v3.hal+json'

Response Fields
Path	Type	Description
`apiVersion`	`String`	Version of meshChargeback datatype. Matches the version provided in the `Accept` request header.
`kind`	`String`	As a common meshObject structure exists, every meshObject has a 'kind'. This is always 'meshChargeback' for this endpoint.
`metadata`	`Object`	Contains attributes to identify a meshChargeback.
`metadata.name`	`String`	A name a meshChargeback can be uniquely identified with.
`metadata.createdOn`	`String`	Creation Date of the meshChargeback.
`metadata.finalized`	`Boolean`	Finalization state of the meshChargeback. Value is 'true' for finalized and 'false' for preview meshChargebacks.
`spec`	`Object`	All fields in this section describe the meshChargeback.
`spec.workspaceIdentifier`	`String`	The meshWorkspace identifier this meshChargeback belongs to.
`spec.projectIdentifier`	`String`	The meshProject identifier this meshChargeback belongs to.
`spec.period`	`String`	The period of the meshChargeback, e.g. '2022-01-06Z'.
`spec.tags`	`Object`	Key/Value pairs associated with this meshChargeback. This includes meshWorkspace, meshProject & meshPaymentMethod tags. Additionally metadata like paymentMethod attributes are provided. Keep in mind, that values are represented as an array to be consistent with other meshObjects. But at themoment, if multiple values are set for a certain tag, only the first value is available on a meshChargeback.
`status`	`Object`	All fields in this section provide detailed content of the meshChargeback.
`status.timeframe`	`Object`	This provides actual details about the period the meshCHargeback was generated for.
`status.timeframe.from`	`String`	At which point in time the period started (usually beginning of month).
`status.timeframe.to`	`String`	Before which point in time the period ended (usually beginning of next month).
`status.lineItems[]`	`Array`	List of all tenant usage reports that have been booked on a meshChargeback. One lineItem is created per Tenant Usage Report and currency.
`status.lineItems[].reportCategory`	`String`	Tenant Usage Reports can either belong to category BILLING or ENVIRONMENTAL. This separation is needed as this kind of different data is provided in quite different time intervals.
`status.lineItems[].platformTenantId`	`String`	Id of the actual platform tenant in the cloud platform (e.g. AWS Account Id or OpenShift Project Id).
`status.lineItems[].platformFullIdentifier`	`String`	meshStack identifier of the platform the tenant belongs to.
`status.lineItems[].reportId`	`String`	Id of the Tenant Usage Report this lineItem relates to.
`status.lineItems[].entryDate`	`String`	Date when the usage report was actually finalized and not modified anymore afterwards.
`status.lineItems[].period`	`String`	Report Period in which the usage for this line item actually occurred. If for some reason a usage report was not finalized before the related chargeback period ended, it will beadded to a later meshChargeback. So meshChargebacks can contain line items from differentreporting periods.
`status.lineItems[].netAmount`	`Number`	Total cost associated with the given Tenant Usage Report for one currency.
`status.lineItems[].baseNetAmount`	`Number`	The converted amount. For example, if currency is USD and baseCurrency is EUR, this will be the amount resulting from conversion from USD to EUR.
`status.lineItems[].currency`	`String`	Currency for the netAmount listed in this lineItem. Multiple lineItems are created if a Tenant Usage Report has costs distributed across multiple currencies.
`status.lineItems[].baseCurrency`	`String`	Currency for the baseNetAmount listed in this lineItem. This value is either null or EUR.
`status.lineItems[].sellerId`	`String`	SellerId configured in meshStack for certain meshPlatforms or even specific products within a platform. This can be used to identify the department or group inside your company the netAmount will be charged to.
`status.lineItems[].sellerProductGroup`	`String`	With the sellerProductGroup the seller information can be further refined. This is for example used to identify the different service brokers used in the meshMarketplace.
`status.netAmounts[]`	`Array`	NetAmounts per currency are provided here.
`status.netAmounts[].currency`	`String`	Currency belonging to the netAmount.
`status.netAmounts[].baseCurrency`	`String`	The currency the amount was converted to. This value is either null or EUR.
`status.netAmounts[].amount`	`Number`	The actual cost associated with the given currency.
`status.netAmounts[].baseNetAmount`	`Number`	The converted amount. For example, if currency is USD and baseCurrency is EUR, this will be the amount resulting from conversion from USD to EUR.
`_links`	`Object`	Available links [links] on a meshChargeback.

Example Response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/vnd.meshcloud.api.meshchargeback.v3.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 1852

{
  "kind" : "meshChargeback",
  "apiVersion" : "v3",
  "metadata" : {
    "name" : "2024-11-01Z/testPartner:testWorkspace:testProject",
    "createdOn" : "2024-11-20T16:04:15.549958700Z",
    "finalized" : true
  },
  "spec" : {
    "projectIdentifier" : "testProject",
    "period" : "2024-11-01Z",
    "tags" : {
      "paymentIdentifier" : [ "123" ]
    },
    "workspaceIdentifier" : "testWorkspace"
  },
  "status" : {
    "timeframe" : {
      "from" : "2024-11-01T00:00:00Z",
      "to" : "2024-12-01T00:00:00Z"
    },
    "lineItems" : [ {
      "reportCategory" : "BILLING",
      "platformTenantId" : "test1-localProjectId",
      "platformFullIdentifier" : "test1-instance.test1-location",
      "reportId" : "test1-reportId",
      "entryDate" : "2019-08-03T00:07:01.289Z",
      "period" : "2019-07-01Z",
      "netAmount" : 1.65,
      "baseNetAmount" : 1.65,
      "baseCurrency" : "EUR",
      "exchangeRate" : 1,
      "currency" : "EUR",
      "sellerId" : "Operations",
      "sellerProductGroup" : "Platform Team"
    }, {
      "reportCategory" : "BILLING",
      "platformTenantId" : "test2-localProjectId",
      "platformFullIdentifier" : "test2-instance.test2-location",
      "reportId" : "test2-reportId",
      "entryDate" : "2019-08-03T00:07:01.289Z",
      "period" : "2019-07-01Z",
      "netAmount" : 3.12,
      "baseNetAmount" : 3.12,
      "baseCurrency" : "EUR",
      "exchangeRate" : 1,
      "currency" : "EUR",
      "sellerId" : "Operations",
      "sellerProductGroup" : "Platform Team"
    } ],
    "netAmounts" : [ {
      "currency" : "EUR",
      "amount" : 4.77,
      "baseCurrency" : "EUR",
      "baseNetAmount" : 4.77
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://mesh-billing-url/api/meshobjects/meshchargebacks/2024-11-01Z/testPartner%3AtestWorkspace%3AtestProject"
    }
  }
}

meshResourceUsageReports

All endpoints on meshResourceUsageReports.

Put meshResourceUsageReports

Use this endpoint to provide cost data from external systems to meshStack. A meshResourceUsageReport will be picked up by the billing system of meshStack and subsequently included into regular meshTenantUsageReports.

/api/meshobjects/meshresourceusagereports/{platformTenantId}/{period}
Parameter	Description
`platformTenantId`	The Platform Tenant ID of the tenant causing the costs.
`period`	The month during which the costs have occurred, e.g. 2023-05-01Z for May 2023.

Request Headers
Name	Description
`Content-Type`	meshObject Import is versioned and `application/vnd.meshcloud.api.meshobjects.v1+yaml` or `application/vnd.meshcloud.api.meshobjects.v1+json` can be used as a `Content-Type`.
`Accept`	meshApi is versioned and you should use `application/vnd.meshcloud.api.meshobjects.v1+json` as an `Accept` header to be guaranteed the V1 response format of this endpoint. New versions will be added in future.

Request Fields
Path	Type	Description
`apiVersion`	`String`	Required for backwards compatibility. v1 is the only supported version at the moment.
`kind`	`String`	Always set this to meshResourceUsageReport.
`fullPlatformIdentifier`	`String`	An identifier in the format $platformInstance.$location, where $platformInstance refers to the identifier of the meshPlatform, and $location refers to the identifier of the meshLocation.
`source`	`String`	Name of the system where this ResourceUsageReport originates from.
`lineItems[].productName`	`String`	Name of the product.
`lineItems[].usageQuantity`	`Number`	The usage quantity, for example, 48 if a product was used for 48 hours.
`lineItems[].usageType`	`String`	To elaborate on the usageUnit, this field is used to describe what exactly is consumed and billed, for example, 'hours of CPU/RAM usage'.
`lineItems[].usageCost`	`Number`	The cost per consumed usageUnit. usageQuantity multiplied by usageCost should always equal totalCost.
`lineItems[].currency`	`String`	The ISO-4217 compliant currency code, e.g. EUR or USD.
`lineItems[].usageUnit`	`String`	The unit of the given usageQuantity, for example, h for hours or d for days.
`lineItems[].totalCost`	`Number`	totalCost equals usageQuantity multiplied by usageCost.

Example Request

PUT /api/meshobjects/meshresourceusagereports/12345/2023-01-01Z HTTP/1.1
Content-Type: application/vnd.meshcloud.api.meshobjects.v1+json;charset=UTF-8
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshobjects.v1+json
Content-Length: 755
Host: mesh-billing-url

{
    "apiVersion": "v1",
    "kind": "meshResourceUsageReport",
    "fullPlatformIdentifier": "my-platform-instance.my-location",
    "source": "Name of Source System",
    "lineItems": [
        {
            "productName": "Virtual Machine",
            "usageQuantity": 48,
            "usageType": "Hours of CPU/RAM usage",
            "usageCost": 1.2,
            "currency": "USD",
            "usageUnit": "h",
            "totalCost": 57.6
        },
        {
            "productName": "SSD storage",
            "usageQuantity": 480,
            "usageType": "Hours of usage multiplied by amounts of GB",
            "usageCost": 0.05,
            "currency": "USD",
            "usageUnit": "h",
            "totalCost": 24
        }
    ]
}

Example Curl Request

$ curl 'https://mesh-billing-url/api/meshobjects/meshresourceusagereports/12345/2023-01-01Z' -i -u 'valid_username:valid_password' -X PUT \
    -H 'Content-Type: application/vnd.meshcloud.api.meshobjects.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.meshcloud.api.meshobjects.v1+json' \
    -d '{
    "apiVersion": "v1",
    "kind": "meshResourceUsageReport",
    "fullPlatformIdentifier": "my-platform-instance.my-location",
    "source": "Name of Source System",
    "lineItems": [
        {
            "productName": "Virtual Machine",
            "usageQuantity": 48,
            "usageType": "Hours of CPU/RAM usage",
            "usageCost": 1.2,
            "currency": "USD",
            "usageUnit": "h",
            "totalCost": 57.6
        },
        {
            "productName": "SSD storage",
            "usageQuantity": 480,
            "usageType": "Hours of usage multiplied by amounts of GB",
            "usageCost": 0.05,
            "currency": "USD",
            "usageUnit": "h",
            "totalCost": 24
        }
    ]
}'

Example Response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/vnd.meshcloud.api.meshobjects.v1+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 133

{
  "meshObject" : "meshResourceUsageReport",
  "status" : "SUCCESS",
  "resultCode" : null,
  "message" : null,
  "remarks" : null
}

Response Fields
Path	Type	Description
`meshObject`	`String`	The name of the meshObject (this is always set to meshResourceUsageReport)
`status`	`String`	The import result status for this meshResourceUsageReport. (SUCCESS or FAILED)
`resultCode`	`String?`	Specific result code for this import result. If no error has occurred, it’s set to null. Otherwise, it’s set to, SERVER_ERROR, as this is is the only possible error code at the moment.
`message`	`String?`	A user readable message with more details. (might be null)
`remarks`	`List<String>?`	User readable remarks on this import result. (might be null)

Cloud resources

In order to retrieve cloud resources and integrate them into existing company processes, the cloud resources API can be used.

getExternalCloudResources

This endpoint will retrieve all your cloud resources based on a paging structure. The result list is sorted ascending by createdAt date of the resource.

Example Request

GET /external/resources/v2?customer=example-customer&platform=os.eu-de-central&project=example-project&resourceStatus=terminated&resourceType=VirtualMachine&displayName=My%20virtual%20machine&page=0&size=20 HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Host: mesh-billing-url

Parameter Description

Parameter	Description
`customer`	The customer identifier
`project`	The project identifier
`platform`	The platform identifier
`resourceStatus`	The status of the resource. This is one of 'Active', 'Terminated', 'Offline' or 'Unknown'
`displayName`	The name of the resource
`resourceType`	The type of the resource. This is currently only 'VirtualMachine'
`page`	The page number (default=0)
`size`	The amount of elements in one page (default=20)

customer

The customer identifier

project

The project identifier

platform

The platform identifier

resourceStatus

The status of the resource. This is one of 'Active', 'Terminated', 'Offline' or 'Unknown'

displayName

The name of the resource

resourceType

The type of the resource. This is currently only 'VirtualMachine'

page

The page number (default=0)

size

The amount of elements in one page (default=20)

Example Curl Request

$ curl 'https://mesh-billing-url/external/resources/v2?customer=example-customer&platform=os.eu-de-central&project=example-project&resourceStatus=terminated&resourceType=VirtualMachine&displayName=My%20virtual%20machine&page=0&size=20' -i -u 'valid_username:valid_password' -X GET

Response Fields
Path	Type	Description
`pageable`	`Object`	Object containing sorting information and additional paging information
`sort`	`Object`	Object containing sorting information
`last`	`Boolean`	Whether the current page is the last one or not
`totalPages`	`Number`	The number of total pages
`totalElements`	`Number`	The number of total elements available
`first`	`Boolean`	Whether the current page is the first one or not
`numberOfElements`	`Number`	The number of elements in the current page
`number`	`Number`	The page number (starts at 0)
`size`	`Number`	The page size
`empty`	`Boolean`	Whether the current page is empty or not
`content[]`	`Array`	The content of the response
`content[].metadata.customer`	`String`	The customer the resource belongs to
`content[].metadata.project`	`String`	The project the resource belongs to
`content[].metadata.platform`	`String`	The platform the resource belongs to
`content[].metadata.tenantId`	`String`	The ID of the tenant in the target platform
`content[].metadata.projectOwner`	`String`	The username of the owner of the project
`content[].metadata.tags`	`Object`	The tags belonging to the tenant
`content[].resource.resourceId`	`String`	The ID of the resource in the target platform
`content[].resource.resourceType`	`String`	The type of the resource (e.g. VirtualMachine)
`content[].resource.createdAt`	`String`	The date and time when this resource was created in the target platform
`content[].resource.displayName`	`String`	The name of the resource in the target platform
`content[].resource.lastObservedAt`	`String`	The last time the resource was observed by meshMetering
`content[].resource.terminatedAt`	`String`	The date and time when this resource was terminated in the target platform (if terminated)
`content[].resource.status`	`String`	Status of the resource. Can be 'Active' or 'Terminated'.
`content[].resource.resourceMeta`	`Object`	Any meta information about the resource, e.g. for VM’s this is the 'ipAddress'

Example Response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 1196

{
  "content" : [ {
    "metadata" : {
      "customer" : "example-customer",
      "project" : "example-project",
      "platform" : "os.eu-de-central",
      "tenantId" : "f7ac731cc11f40efbc03a9f9e1d1d21f",
      "projectOwner" : "project-owner@example.com",
      "tags" : {
        "costCenter" : [ "1234" ]
      }
    },
    "resource" : {
      "resourceId" : "a9debfe41a6d4d09a677da737b907d5e",
      "resourceType" : "VirtualMachine",
      "createdAt" : "2020-03-20T15:00:00Z",
      "displayName" : "My virtual machine",
      "lastObservedAt" : "2020-04-01T12:00:00Z",
      "terminatedAt" : "2020-04-25T09:00:00Z",
      "resourceMeta" : {
        "ipAddress" : "12.34.56.78"
      },
      "status" : "Terminated"
    }
  } ],
  "pageable" : {
    "pageNumber" : 0,
    "pageSize" : 20,
    "sort" : {
      "empty" : false,
      "unsorted" : false,
      "sorted" : true
    },
    "offset" : 0,
    "unpaged" : false,
    "paged" : true
  },
  "last" : true,
  "totalPages" : 1,
  "totalElements" : 1,
  "size" : 20,
  "number" : 0,
  "sort" : {
    "empty" : false,
    "unsorted" : false,
    "sorted" : true
  },
  "first" : true,
  "numberOfElements" : 1,
  "empty" : false
}