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

Unresolved directive in api_index.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/apiRoot/request-headers.adoc[]

Example Request

Unresolved directive in api_index.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/apiRoot/http-request.adoc[]

Example Curl Request

Unresolved directive in api_index.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/apiRoot/curl-request.adoc[]

Response Fields

Unresolved directive in api_index.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/apiRoot/response-fields.adoc[]

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. Unresolved directive in api_index.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/apiRoot/links.adoc[]

Example Response

Unresolved directive in api_index.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/apiRoot/http-response.adoc[]

meshObjects

Via this API you can get meshObjects from meshMetering.

Request Headers

Unresolved directive in mesh_objects.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/meshObjectsRoot/request-headers.adoc[]

Example Request

Unresolved directive in mesh_objects.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/meshObjectsRoot/http-request.adoc[]

Example Curl Request

Unresolved directive in mesh_objects.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/meshObjectsRoot/curl-request.adoc[]

Response Fields

Unresolved directive in mesh_objects.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/meshObjectsRoot/response-fields.adoc[]

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. Unresolved directive in mesh_objects.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/meshObjectsRoot/links.adoc[]

Example Response

Unresolved directive in mesh_objects.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/meshObjectsRoot/http-response.adoc[]

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

Unresolved directive in mesh_tenant_usage_reports.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/meshTenantUsageReportsList/request-headers.adoc[]

Request Parameters

Unresolved directive in mesh_tenant_usage_reports.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/meshTenantUsageReportsList/query-parameters.adoc[]

Example Request

Unresolved directive in mesh_tenant_usage_reports.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/meshTenantUsageReportsList/http-request.adoc[]

Example Curl Request

Unresolved directive in mesh_tenant_usage_reports.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/meshTenantUsageReportsList/curl-request.adoc[]

Response Fields

Unresolved directive in mesh_tenant_usage_reports.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/meshTenantUsageReportsList/response-fields.adoc[]

Example Response

Unresolved directive in mesh_tenant_usage_reports.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/meshTenantUsageReportsList/http-response.adoc[]

Get meshTenantUsageReport

Get a single meshTenantUsageReport.

Request Headers

Unresolved directive in mesh_tenant_usage_reports.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/meshTenantUsageReport/request-headers.adoc[]

Example Request

Unresolved directive in mesh_tenant_usage_reports.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/meshTenantUsageReport/http-request.adoc[]

Example Curl Request

Unresolved directive in mesh_tenant_usage_reports.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/meshTenantUsageReport/curl-request.adoc[]

Response Fields

Unresolved directive in mesh_tenant_usage_reports.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/meshTenantUsageReport/response-fields.adoc[]

Example Response

Unresolved directive in mesh_tenant_usage_reports.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/meshTenantUsageReport/http-response.adoc[]

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

Unresolved directive in mesh_chargeback.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/meshChargebackList/request-headers.adoc[]

Request Parameters

Unresolved directive in mesh_chargeback.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/meshChargebackList/query-parameters.adoc[]

Example Request

Unresolved directive in mesh_chargeback.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/meshChargebackList/http-request.adoc[]

Example Curl Request

Unresolved directive in mesh_chargeback.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/meshChargebackList/curl-request.adoc[]

Response Fields

Unresolved directive in mesh_chargeback.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/meshChargebackList/response-fields.adoc[]

Example Response

Unresolved directive in mesh_chargeback.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/meshChargebackList/http-response.adoc[]

Get meshChargeback

Get a single meshChargeback.

Request Headers

Unresolved directive in mesh_chargeback.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/meshChargeback/request-headers.adoc[]

Example Request

Unresolved directive in mesh_chargeback.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/meshChargeback/http-request.adoc[]

Example Curl Request

Unresolved directive in mesh_chargeback.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/meshChargeback/curl-request.adoc[]

Response Fields

Unresolved directive in mesh_chargeback.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/meshChargeback/response-fields.adoc[]

Example Response

Unresolved directive in mesh_chargeback.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/meshChargeback/http-response.adoc[]

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.

Unresolved directive in mesh_resource_usage_report.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/meshResourceUsageReportPut/path-parameters.adoc[]

Request Headers

Unresolved directive in mesh_resource_usage_report.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/meshResourceUsageReportPut/request-headers.adoc[]

Request Fields

Unresolved directive in mesh_resource_usage_report.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/meshResourceUsageReportPut/request-fields.adoc[]

Example Request

Unresolved directive in mesh_resource_usage_report.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/meshResourceUsageReportPut/http-request.adoc[]

Example Curl Request

Unresolved directive in mesh_resource_usage_report.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/meshResourceUsageReportPut/curl-request.adoc[]

Example Response

Unresolved directive in mesh_resource_usage_report.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/meshResourceUsageReportPut/http-response.adoc[]

Response Fields

Unresolved directive in mesh_resource_usage_report.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/meshResourceUsageReportPut/response-fields.adoc[]

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

Unresolved directive in cloud-resources.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/getExternalCloudResources/http-request.adoc[]

Unresolved directive in cloud-resources.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/getExternalCloudResources/query-parameters.adoc[]

Example Curl Request

Unresolved directive in cloud-resources.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/getExternalCloudResources/curl-request.adoc[]

Response Fields

Unresolved directive in cloud-resources.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/getExternalCloudResources/response-fields.adoc[]

Example Response

Unresolved directive in cloud-resources.adoc - include::/__w/meshfed-release/meshfed-release/billing/kraken-api/build/generated-snippets/getExternalCloudResources/http-response.adoc[]