Introduction

Hey there, and welcome to the official meshcloud API documentation! This documentation page will guide you through the process of integrating with our meshStack software. meshStack is our self-hosted software that you use to build your own meshcloud.

This API documentation will help you accomplish specific use cases that require you to read data from meshStack or insert data into meshStack.

meshStack offers various public REST endpoints to enable your use cases. If you’re interested in reading data from meshStack via a REST API, have a look at all API compatible meshObjects. 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 existing API User. Finally, set the hostname variable to ensure that the requests are ready to be executed.

Providing or updating data into meshStack can be done via the meshObject Declarative Import API. As a leading cloud solution, we built this API with inspiration from the Kubernetes API, which is a declarative API that uses YML to represent its data. This API will feel familiar to those who have interacted with a Kubernetes cluster before. We also offer the ability to use JSON for those unfamiliar with YAML.

If you are not familiar with meshObjects, or the meshModel in general, we highly recommend reading about them in our public documentation. This should give you an idea of what the objects are, what their relationships are and when you need them.

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

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

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.

422 Unprocessable Entity

The request contained one or more entities with an error like a non existing referenced entity.

500 Internal Server Error

An internal error occurred while processing the request. Most likely these are temporary communication errors with external services.

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

page

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

size

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

Responses are structured like the following snippet:

{
    "_embedded": { }
    "_links": {
        "self" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshworkspaces"
        },
        "first" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshworkspaces?page=0&size=20"
        },
        "prev" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshworkspaces?page=0&size=20"
        },
        "next" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshworkspaces?page=2&size=20"
        },
        "last" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshworkspaces?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.

Tags

meshObjects can be tagged. The tags are provided as key/value pairs where a key can have multiple values. A tag value is always in form of a list regardless of the amount of values present.

An example could look like that:

"tags": {
    "environment": [
        "Dev",
        "QA"
    ],
    "confidentiality": [
        "Internal"
    ]
}

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. 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-backend-url
Example Curl Request
$ curl 'https://mesh-backend-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.
Relation Description

metadata

The Metadata API to retrieve metadata from meshStack.

meshobjects

The MeshObjects API to get, create, update and delete 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: 1; mode=block
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: 257

{
  "_links" : {
    "metadata" : {
      "href" : "https://mesh-backend-url/api/metadata"
    },
    "meshobjects" : {
      "href" : "https://mesh-backend-url/api/meshobjects"
    },
    "self" : {
      "href" : "https://mesh-backend-url/api"
    }
  }
}

meshObjects

Via this API you can get, create, update and delete meshObjects. For creating, updating and deleting meshObjects we currently only support a declarative way to do so. This is described in meshObject Declarative Import.

Request Headers
Name Description

Accept

meshApi is versioned and you should use application/vnd.meshcloud.api.meshobjects.v2.hal+json as an Accept header to be guaranteed the V2 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.v2.hal+json
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshobjects.v2.hal+json'
Response Fields
Path Type Description

_links

Object

All available meshObject Links for the authenticated user.
Relation Description

meshworkspaces

Get meshWorkspaces.

meshworkspaceusergroups

Get meshWorkspaceUserGroups.

meshprojects

Get meshProjects.

meshtenants

Get meshTenants.

meshpaymentmethods

Get meshPaymentMethods.

meshusers

Get meshUsers.

meshserviceinstances

Get meshServiceInstances.

meshbuildingblocks

Get meshBuildingBlocks.
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.v2.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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: 1463

{
  "_links" : {
    "meshusers" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshusers/{username}",
      "templated" : true
    },
    "meshpaymentmethods" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods{?workspaceIdentifier}",
      "templated" : true
    },
    "meshbuildingblocks" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshbuildingblocks{?customerIdentifier,projectIdentifier,platformIdentifier,name,definitionName,versionNumber,status}",
      "templated" : true
    },
    "meshworkspaces" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshworkspaces"
    },
    "meshworkspaceusergroups" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshworkspaceusergroups"
    },
    "meshserviceinstances" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshserviceinstances{?workspaceIdentifier,projectIdentifier,marketplaceIdentifier,serviceIdentifier,planIdentifier}",
      "templated" : true
    },
    "meshprojects" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojects{?workspaceIdentifier,paymentIdentifier}",
      "templated" : true
    },
    "meshtenants" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshtenants{?workspaceIdentifier,projectIdentifier,platformIdentifier,deletionState}",
      "templated" : true
    },
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects"
    }
  }
}

meshWorkspace

All endpoints on meshWorkspaces.

List meshWorkspaces

Provides a paged list of meshWorkspaces. Deleted meshWorkspaces are not provided via this endpoint.

Request Headers
Name Description

Accept

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

page

The page number (default=0). See Paging information.

size

The amount of elements in a single page (default=50). See Paging information.
Example Request
GET /api/meshobjects/meshworkspaces?page=0&size=3 HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshworkspace.v1.hal+json
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshworkspaces?page=0&size=3' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshworkspace.v1.hal+json'
Response Fields
Path Type Description

_embedded

Object

Contains the actual content of the paged response.

_embedded.meshWorkspaces[]

Array

List of meshWorkspace.

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.meshworkspace.v1.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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: 4022

{
  "_embedded" : {
    "meshWorkspaces" : [ {
      "apiVersion" : "v1",
      "kind" : "meshWorkspace",
      "metadata" : {
        "name" : "admin-customer",
        "createdOn" : "2024-04-24T16:46:53Z"
      },
      "spec" : {
        "displayName" : "admin-customer",
        "tags" : { }
      },
      "_links" : {
        "self" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshworkspaces/admin-customer"
        },
        "meshtenants" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshtenants?workspaceIdentifier=admin-customer"
        },
        "meshprojects" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshprojects?workspaceIdentifier=admin-customer"
        },
        "meshusers" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshusers"
        },
        "meshpaymentmethods" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods?workspaceIdentifier=admin-customer"
        },
        "meshworkspaceusergroups" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshworkspaceusergroups?workspaceIdentifier=admin-customer"
        }
      }
    }, {
      "apiVersion" : "v1",
      "kind" : "meshWorkspace",
      "metadata" : {
        "name" : "demo-customer",
        "createdOn" : "2024-04-24T16:46:53Z"
      },
      "spec" : {
        "displayName" : "demo-customer",
        "tags" : { }
      },
      "_links" : {
        "self" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshworkspaces/demo-customer"
        },
        "meshtenants" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshtenants?workspaceIdentifier=demo-customer"
        },
        "meshprojects" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshprojects?workspaceIdentifier=demo-customer"
        },
        "meshusers" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshusers"
        },
        "meshpaymentmethods" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods?workspaceIdentifier=demo-customer"
        },
        "meshworkspaceusergroups" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshworkspaceusergroups?workspaceIdentifier=demo-customer"
        }
      }
    }, {
      "apiVersion" : "v1",
      "kind" : "meshWorkspace",
      "metadata" : {
        "name" : "demo-partner",
        "createdOn" : "2024-04-24T16:46:53Z"
      },
      "spec" : {
        "displayName" : "demo-partner",
        "tags" : { }
      },
      "_links" : {
        "self" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshworkspaces/demo-partner"
        },
        "meshtenants" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshtenants?workspaceIdentifier=demo-partner"
        },
        "meshprojects" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshprojects?workspaceIdentifier=demo-partner"
        },
        "meshusers" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshusers"
        },
        "meshpaymentmethods" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods?workspaceIdentifier=demo-partner"
        },
        "meshworkspaceusergroups" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshworkspaceusergroups?workspaceIdentifier=demo-partner"
        }
      }
    } ]
  },
  "_links" : {
    "first" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshworkspaces?page=0&size=3"
    },
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshworkspaces?page=0&size=3"
    },
    "next" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshworkspaces?page=1&size=3"
    },
    "last" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshworkspaces?page=1&size=3"
    }
  },
  "page" : {
    "size" : 3,
    "totalElements" : 5,
    "totalPages" : 2,
    "number" : 0
  }
}
Get meshWorkspace

Get a single meshWorkspace. Deleted meshWorkspaces can also be requested via this endpoint.

Request Headers
Name Description

Accept

meshApi is versioned and you should use application/vnd.meshcloud.api.meshworkspace.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/meshworkspaces/admin-customer HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshworkspace.v1.hal+json
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshworkspaces/admin-customer' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshworkspace.v1.hal+json'
Response Fields
Path Type Description

apiVersion

String

Version of meshWorkspace datatype. Matches the version part provided within the Accept request header.

kind

String

As a common meshObject structure exists, every meshObject has a 'kind'. This is always 'meshWorkspace' for this endpoint.

metadata

Object

Always contains the 'name' to uniquely identify the meshWorkspace. Can additionally contain meta information like the meshWorkspace creation date.

metadata.name

String

The workspaceIdentifier as 'name' to uniquely identify the meshWorkspace.

metadata.createdOn

String

The meshWorkspace has been created at this date (e.g. 2020-12-22T09:37:43Z).

metadata.deletedOn

String

If the meshWorkspace has already been deleted, the date when deletion happened is provided via this field. e.g. 2020-12-22T09:37:43Z

spec

Object

All fields in this section describe the meshWorkspace.

spec.displayName

String

The display name of the meshWorkspace as it is shown in meshPanel.

spec.tags

Object

Key/Value pairs of tags set on the meshWorkspace. Keep in mind, that values are an array. Also see our general section about Tags

_links

Object

Available links on a meshWorkspace.
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.meshworkspace.v1.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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: 1020

{
  "apiVersion" : "v1",
  "kind" : "meshWorkspace",
  "metadata" : {
    "name" : "admin-customer",
    "createdOn" : "2024-04-24T16:46:53Z"
  },
  "spec" : {
    "displayName" : "admin-customer",
    "tags" : { }
  },
  "_links" : {
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshworkspaces/admin-customer"
    },
    "meshtenants" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshtenants?workspaceIdentifier=admin-customer"
    },
    "meshprojects" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojects?workspaceIdentifier=admin-customer"
    },
    "meshusers" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshusers"
    },
    "meshpaymentmethods" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods?workspaceIdentifier=admin-customer"
    },
    "meshworkspaceusergroups" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshworkspaceusergroups?workspaceIdentifier=admin-customer"
    }
  }
}

meshProject

All endpoints on meshProjects.

List meshProjects

Provides a paged list of meshProjects. Deleted meshProjects are not provided via this endpoint.

Request Headers
Name Description

Accept

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

workspaceIdentifier

Filter for meshProjects that belong to the meshWorkspace with given identifier. (optional)

paymentIdentifier

Filter for meshProjects that have the meshPaymentMethod with given identifier assigned. Substitute Payment Methods on meshProjects are not considered! Use an empty or blank value to filter for meshProjects without an assigned meshPaymentMethod. (optional)

page

The page number (default=0). See Paging information.

size

The amount of elements in a single page (default=50). See Paging information.
Example Request
GET /api/meshobjects/meshprojects?workspaceIdentifier=ejz76mpdsv2&paymentIdentifier=test-payment&page=0&size=1 HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshproject.v2.hal+json
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshprojects?workspaceIdentifier=ejz76mpdsv2&paymentIdentifier=test-payment&page=0&size=1' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshproject.v2.hal+json'
Response Fields
Path Type Description

_embedded

Object

Contains the actual content of the paged response.

_embedded.meshProjects[]

Array

List of meshProject.

_links

Object

Currently only contains the self link and pagination links.

page

Object

See Paging information.
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.meshproject.v2.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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: 1795

{
  "_embedded" : {
    "meshProjects" : [ {
      "apiVersion" : "v2",
      "spec" : {
        "displayName" : "Test Project 1",
        "tags" : { },
        "paymentMethodIdentifier" : "test-payment"
      },
      "metadata" : {
        "name" : "test-project-1",
        "ownedByWorkspace" : "ejz76mpdsv2",
        "createdOn" : "2024-04-24T16:47:50.067514Z"
      },
      "kind" : "meshProject",
      "_links" : {
        "self" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshprojects/ejz76mpdsv2.test-project-1"
        },
        "meshtenants" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshtenants?workspaceIdentifier=ejz76mpdsv2&projectIdentifier=test-project-1"
        },
        "meshusers" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshusers"
        },
        "activePaymentMethod" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods/test-payment"
        }
      }
    } ]
  },
  "_links" : {
    "first" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojects?workspaceIdentifier=ejz76mpdsv2&paymentIdentifier=test-payment&page=0&size=1"
    },
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojects?workspaceIdentifier=ejz76mpdsv2&paymentIdentifier=test-payment&page=0&size=1"
    },
    "next" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojects?workspaceIdentifier=ejz76mpdsv2&paymentIdentifier=test-payment&page=1&size=1"
    },
    "last" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojects?workspaceIdentifier=ejz76mpdsv2&paymentIdentifier=test-payment&page=1&size=1"
    }
  },
  "page" : {
    "size" : 1,
    "totalElements" : 2,
    "totalPages" : 2,
    "number" : 0
  }
}
Get meshProject

Get a single meshProject. Deleted meshProjects can also be requested via this endpoint.

Request Headers
Name Description

Accept

meshApi is versioned and you should use application/vnd.meshcloud.api.meshproject.v2.hal+json as an Accept header to be guaranteed the V2 response format of this endpoint. New versions will be added in future.
Example Request
GET /api/meshobjects/meshprojects/ejz76mpdsv2.test-project-1 HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshproject.v2.hal+json
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshprojects/ejz76mpdsv2.test-project-1' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshproject.v2.hal+json'
Response Fields
Path Type Description

apiVersion

String

Version of meshProject datatype. Matches the version part provided within the Accept request header.

kind

String

As a common meshObject structure exists, every meshObject has a 'kind'. This is always 'meshProject' for this endpoint.

metadata

Object

Always contains the 'name' and 'ownedByWorkspace' to uniquely identify the meshProject.

metadata.name

String

The projectIdentifier as 'name'.

metadata.ownedByWorkspace

String

The workspaceIdentifier as 'ownedByWorkspace'.

metadata.createdOn

String

The meshProject has been created at this date (e.g. 2020-12-22T09:37:43Z).

metadata.deletedOn

String

If the meshProject has been submitted for deletion by a Workspace Manager, the date, the date is represented here (e.g. 2020-12-22T09:37:43Z). Otherwise this field is missing.

spec

Object

All fields in this section describe the meshProject.

spec.displayName

String

The display name of the meshProject as it is shown in meshPanel.

spec.tags

Object

Key/Value pairs of tags set on the meshProject. Keep in mind, that values are an array. Also see our general section about Tags

spec.paymentMethodIdentifier

String

The meshPaymentMethod of the meshProject.

spec.substitutePaymentMethodIdentifier

String

The substitutePaymentMethod of the meshProject

_links

Object

Available links on a meshProject.
Example Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Disposition: inline;filename=f.txt
Content-Type: application/vnd.meshcloud.api.meshproject.v2.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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: 838

{
  "apiVersion" : "v2",
  "spec" : {
    "displayName" : "Test Project 1",
    "tags" : { },
    "paymentMethodIdentifier" : "test-payment"
  },
  "metadata" : {
    "name" : "test-project-1",
    "ownedByWorkspace" : "ejz76mpdsv2",
    "createdOn" : "2024-04-24T16:47:50.067514Z"
  },
  "kind" : "meshProject",
  "_links" : {
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojects/ejz76mpdsv2.test-project-1"
    },
    "meshtenants" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshtenants?workspaceIdentifier=ejz76mpdsv2&projectIdentifier=test-project-1"
    },
    "meshusers" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshusers"
    },
    "activePaymentMethod" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods/test-payment"
    }
  }
}

meshTenant

All endpoints on meshTenants.

List meshTenants

Provides a paged list of meshTenants. By default, list all active meshTenants (neither deleted nor submitted for deletion).

Note: If the deletion state is not specified, only active meshTenants are returned.

Request Headers
Name Description

Accept

meshApi is versioned and you should use application/vnd.meshcloud.api.meshtenant.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 meshTenants that belong to the meshWorkspace with given identifier. (optional)

projectIdentifier

Filter for meshTenants that belong to the meshProject with given identifier. (optional)

platformIdentifier

Filter for meshTenants that belong to the meshPlatform with given identifier. (optional)

deletionState

Filter for meshTenants with a certain deletion state. Possible values are: [ACTIVE](default option) All meshTenants that are not deleted or submitted for deletion,[MARKED_FOR_DELETION] All meshTenants that are awaiting manual deletion approval, or [DELETED] All meshTenants that are deleted or submitted for deletion

page

The page number (default=0). See Paging information.

size

The amount of elements in a single page (default=50). See Paging information.
Example Request
GET /api/meshobjects/meshtenants?workspaceIdentifier=test-workspace&projectIdentifier=test-project&deletionState=MARKED_FOR_DELETION&page=0&size=1 HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshtenant.v3.hal+json
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshtenants?workspaceIdentifier=test-workspace&projectIdentifier=test-project&deletionState=MARKED_FOR_DELETION&page=0&size=1' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshtenant.v3.hal+json'
Response Fields
Path Type Description

_embedded

Object

Contains the actual content of the paged response.

_embedded.meshTenants[]

Array

List of meshTenant.

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.meshtenant.v3.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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: 1907

{
  "_embedded" : {
    "meshTenants" : [ {
      "apiVersion" : "v3",
      "kind" : "meshTenant",
      "metadata" : {
        "ownedByProject" : "test-project",
        "ownedByWorkspace" : "test-workspace",
        "platformIdentifier" : "azure.meshcloud-azure-dev",
        "deletedOn" : "2024-04-25T16:47:52.818135Z",
        "assignedTags" : { }
      },
      "spec" : {
        "localId" : "05aea2ea-2d05-4212-951f-4097e688244d",
        "landingZoneIdentifier" : "stage-dev",
        "quotas" : [ {
          "key" : "limits.cpu",
          "value" : 2000
        }, {
          "key" : "limits.memory",
          "value" : 10000
        } ]
      },
      "_links" : {
        "self" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshtenants/test-workspace.test-project.azure.meshcloud-azure-dev"
        },
        "meshusers" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshusers"
        }
      }
    } ]
  },
  "_links" : {
    "first" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshtenants?workspaceIdentifier=test-workspace&projectIdentifier=test-project&deletionState=MARKED_FOR_DELETION&page=0&size=1"
    },
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshtenants?workspaceIdentifier=test-workspace&projectIdentifier=test-project&deletionState=MARKED_FOR_DELETION&page=0&size=1"
    },
    "next" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshtenants?workspaceIdentifier=test-workspace&projectIdentifier=test-project&deletionState=MARKED_FOR_DELETION&page=1&size=1"
    },
    "last" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshtenants?workspaceIdentifier=test-workspace&projectIdentifier=test-project&deletionState=MARKED_FOR_DELETION&page=1&size=1"
    }
  },
  "page" : {
    "size" : 1,
    "totalElements" : 2,
    "totalPages" : 2,
    "number" : 0
  }
}
Get meshTenant

Get a single meshTenant. A meshTenant submitted for deletion by a Workspace Manager can also be requested via this endpoint.

Request Headers
Name Description

Accept

meshApi is versioned and you should use application/vnd.meshcloud.api.meshtenant.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/meshtenants/test-workspace.test-project.azure.meshcloud-azure-dev HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshtenant.v3.hal+json
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshtenants/test-workspace.test-project.azure.meshcloud-azure-dev' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshtenant.v3.hal+json'
Response Fields
Path Type Description

apiVersion

String

Version of meshTenant 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 'meshTenant' for this endpoint.

metadata

Object

Always contains the 'ownedByProject', 'ownedByWorkspace' and 'platformIdentifier' to identify the meshTenant.

metadata.ownedByProject

String

The identifier of the meshProject the meshTenant belongs to.

metadata.ownedByWorkspace

String

The identifier of the meshWorkspace the meshTenant belongs to.

metadata.deletedOn

String

If the meshTenant has been submitted for deletion by a Workspace Manager, the date, the date is represented here (e.g. 2020-12-22T09:37:43Z). Otherwise this field is missing.

metadata.platformIdentifier

String

The identifier of the related platform instance

metadata.assignedTags

Object

The tags assigned to this meshTenant originating from meshWorkspace, Payment Method and meshProject. Keep in mind, that values are an array. Also see our general section about Tags

spec

Object

All fields in this section describe the meshTenant.

spec.localId

String

The localId (platform tenant id) assigned with this meshTenant. It will only be set if the tenant was either imported via meshObject API with a localId or if at least one replication run finished successfully for this tenant.

spec.landingZoneIdentifier

String

The identifier of the Landing Zone of this meshTenant. This field will be empty if the meshTenant has no Landing Zone.

spec.quotas[]

Array

The set of applied Tenant Quotas. They can be set individually per tenant. By default the Landing Zone quotas are applied to new meshTenants.

_links

Object

Currently only contains the self link.
Example Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Disposition: inline;filename=f.txt
Content-Type: application/vnd.meshcloud.api.meshtenant.v3.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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: 799

{
  "apiVersion" : "v3",
  "kind" : "meshTenant",
  "metadata" : {
    "ownedByProject" : "test-project",
    "ownedByWorkspace" : "test-workspace",
    "platformIdentifier" : "azure.meshcloud-azure-dev",
    "deletedOn" : "2024-04-25T16:47:52.818135Z",
    "assignedTags" : { }
  },
  "spec" : {
    "localId" : "05aea2ea-2d05-4212-951f-4097e688244d",
    "landingZoneIdentifier" : "stage-dev",
    "quotas" : [ {
      "key" : "limits.cpu",
      "value" : 2000
    }, {
      "key" : "limits.memory",
      "value" : 10000
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshtenants/test-workspace.test-project.azure.meshcloud-azure-dev"
    },
    "meshusers" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshusers"
    }
  }
}

meshBuildingBlock

All endpoints on meshBuildingBlocks.

List meshBuildingBlocks

Provides a paged list of meshBuildingBlocks.

Request Headers
Name Description

Accept

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

workspaceIdentifier

Filter for Building Blocks that belong to the meshWorkspace with given identifier. (optional)

projectIdentifier

Filter for Building Blocks that belong to the meshProject with given identifier. (optional)

platformIdentifier

Filter for Building Blocks that belong to the meshPlatform with given identifier. (optional)

name

Filter for Building Blocks with the given display name. (optional)

definitionName

Filter for Building Blocks that belong to the definition with the given name. (optional)

versionNumber

Filter for Building Blocks that use a certain version number. Can be the number or only 'v1', etc. (optional)

status

Filter for Building Blocks that have a certain status. One of WAITING_FOR_DEPENDENT_INPUT, WAITING_FOR_OPERATOR_INPUT, PENDING, IN_PROGRESS, SUCCEEDED, FAILED. (optional)

page

The page number (default=0). See Paging information.

size

The amount of elements in a single page (default=50). See Paging information.
Example Request
GET /api/meshobjects/meshbuildingblocks?projectIdentifier=my-project&page=0&size=10 HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshbuildingblock.v1.hal+json
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshbuildingblocks?projectIdentifier=my-project&page=0&size=10' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshbuildingblock.v1.hal+json'
Response Fields
Path Type Description

_embedded

Object

Contains the actual content of the paged response.

_embedded.meshBuildingBlocks[]

Array

List of meshBuildingBlocks.

page

Object

See Paging information.

_links

Object

Contains the self link, a link to the related tenant 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.meshbuildingblock.v1.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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: 2621

{
  "_embedded" : {
    "meshBuildingBlocks" : [ {
      "apiVersion" : "v1",
      "kind" : "meshBuildingBlock",
      "metadata" : {
        "uuid" : "067485e8-7fac-47b9-a90d-8d0c5a39ecd5",
        "definitionUuid" : "014e733f-5c54-4ecf-93fd-3ec1dc868f40",
        "definitionVersion" : 1,
        "tenantIdentifier" : "my-workspace.my-project.my-platform.my-location",
        "forcePurge" : false,
        "createdOn" : "2024-04-24T16:47:44.951344Z"
      },
      "spec" : {
        "displayName" : "parent block",
        "inputs" : [ ],
        "parentBuildingBlocks" : [ ]
      },
      "status" : {
        "status" : "SUCCEEDED",
        "outputs" : [ ]
      },
      "_links" : {
        "self" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshbuildingblocks/067485e8-7fac-47b9-a90d-8d0c5a39ecd5"
        },
        "meshtenant" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshtenants/my-workspace.my-project.my-platform.my-location"
        }
      }
    }, {
      "apiVersion" : "v1",
      "kind" : "meshBuildingBlock",
      "metadata" : {
        "uuid" : "8d77dd19-d011-4710-b64c-f50ddf232ce6",
        "definitionUuid" : "e2134e0a-5806-4101-a431-5be1982ae35d",
        "definitionVersion" : 1,
        "tenantIdentifier" : "my-workspace.my-project.my-platform.my-location",
        "forcePurge" : false,
        "createdOn" : "2024-04-24T16:47:44.963944Z"
      },
      "spec" : {
        "displayName" : "child block",
        "inputs" : [ {
          "key" : "resourceName",
          "value" : "My Test Resource",
          "valueType" : "STRING"
        } ],
        "parentBuildingBlocks" : [ {
          "buildingBlockUuid" : "067485e8-7fac-47b9-a90d-8d0c5a39ecd5",
          "definitionUuid" : "014e733f-5c54-4ecf-93fd-3ec1dc868f40"
        } ]
      },
      "status" : {
        "status" : "SUCCEEDED",
        "outputs" : [ {
          "key" : "resourceId",
          "value" : "id-123",
          "valueType" : "STRING"
        } ]
      },
      "_links" : {
        "self" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshbuildingblocks/8d77dd19-d011-4710-b64c-f50ddf232ce6"
        },
        "meshtenant" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshtenants/my-workspace.my-project.my-platform.my-location"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshbuildingblocks?projectIdentifier=my-project&page=0&size=10"
    }
  },
  "page" : {
    "size" : 10,
    "totalElements" : 2,
    "totalPages" : 1,
    "number" : 0
  }
}
Get meshBuildingBlock

Get a single meshBuildingBlock.

Request Headers
Name Description

Accept

meshApi is versioned and you should use application/vnd.meshcloud.api.meshbuildingblock.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/meshbuildingblocks/8d77dd19-d011-4710-b64c-f50ddf232ce6 HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshbuildingblock.v1.hal+json
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshbuildingblocks/8d77dd19-d011-4710-b64c-f50ddf232ce6' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshbuildingblock.v1.hal+json'
Response Fields
Path Type Description

apiVersion

String

Version of Building Block datatype. Matches the version part provided within the Accept request header.

kind

String

As a common meshObject structure exists, every meshObject has a 'kind'. This is always 'meshBuildingBlock' for this endpoint.

metadata

Object

Always contains the 'uuid' to uniquely identify the Building Block. It also contains additional meta information like the Building Block creation date.

metadata.uuid

String

The UUID to uniquely identify the Building Block.

metadata.definitionUuid

String

The UUID of the Building Block Definition this Building Block is based on.

metadata.definitionVersion

Number

The version number of the Building Block Definition this Building Block is based on.

metadata.tenantIdentifier

String

The full identifier of the tenant, this Building Block is created in.

metadata.forcePurge

Boolean

Set to true, if an operator explicitly requested this Building Block to be purged.

metadata.createdOn

String

The Building Block has been created at this date (e.g. 2020-12-22T09:37:43Z).

metadata.markedForDeletionOn

String

If the Building Block has been marked for deletion, the date when a user requested the deletion is provided via this field. e.g. 2020-12-22T09:37:43Z

metadata.markedForDeletionBy

String

If the Building Block has already been deleted, the username of the user who triggered the deletion is provided here.

spec

Object

All fields in this section describe the Building Block.

spec.displayName

String

The display name of the Building Block as it is shown in meshPanel.

spec.inputs[]

Array

List of inputs, which are set on the Building Block.

spec.inputs[].key

String

The key of the input as set on the related Building Block Definition.

spec.inputs[].value

String

The value, which is set on this input.

spec.inputs[].valueType

String

The data type of the value. One of STRING, INTEGER, BOOLEAN, FILE, LIST, SINGLE_SELECT.

spec.parentBuildingBlocks[]

Array

List of inputs, which are set on the Building Block.

spec.parentBuildingBlocks[].buildingBlockUuid

String

The UUID of the parent Building Block.

spec.parentBuildingBlocks[].definitionUuid

String

The UUID of the Building Block Definition of the parent Building Block.

status

Object

All fields in this section describe the current status of the Building Block.

status.status

String

The status of the Building Block. One of WAITING_FOR_DEPENDENT_INPUT, WAITING_FOR_OPERATOR_INPUT, PENDING, IN_PROGRESS, SUCCEEDED, FAILED.

status.outputs[]

Array

List of outputs, which are set on the Building Block.

status.outputs[].key

String

The key of the output as set on the related Building Block Definition.

status.outputs[].value

String

The value, which is set on this output.

status.outputs[].valueType

String

The data type of the value. One of STRING, INTEGER, BOOLEAN, FILE, LIST, SINGLE_SELECT.

_links

Object

Available links on a Building Block.
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.meshbuildingblock.v1.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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: 1183

{
  "apiVersion" : "v1",
  "kind" : "meshBuildingBlock",
  "metadata" : {
    "uuid" : "8d77dd19-d011-4710-b64c-f50ddf232ce6",
    "definitionUuid" : "e2134e0a-5806-4101-a431-5be1982ae35d",
    "definitionVersion" : 1,
    "tenantIdentifier" : "my-workspace.my-project.my-platform.my-location",
    "forcePurge" : false,
    "createdOn" : "2024-04-24T16:47:44.963944Z"
  },
  "spec" : {
    "displayName" : "child block",
    "inputs" : [ {
      "key" : "resourceName",
      "value" : "My Test Resource",
      "valueType" : "STRING"
    } ],
    "parentBuildingBlocks" : [ {
      "buildingBlockUuid" : "067485e8-7fac-47b9-a90d-8d0c5a39ecd5",
      "definitionUuid" : "014e733f-5c54-4ecf-93fd-3ec1dc868f40"
    } ]
  },
  "status" : {
    "status" : "SUCCEEDED",
    "outputs" : [ {
      "key" : "resourceId",
      "value" : "id-123",
      "valueType" : "STRING"
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshbuildingblocks/8d77dd19-d011-4710-b64c-f50ddf232ce6"
    },
    "meshtenant" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshtenants/my-workspace.my-project.my-platform.my-location"
    }
  }
}

meshPaymentMethod

All endpoints on meshPaymentMethods.

List meshPaymentMethods

Provides a paged list of meshPaymentMethods. Deleted meshPaymentMethods are not provided via this endpoint.

Request Headers
Name Description

Accept

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

workspaceIdentifier

Filter for meshPaymentMethods that belong to the meshWorkspace with given identifier. (optional)

page

The page number (default=0). See Paging information.

size

The amount of elements in a single page (default=50). See Paging information.
Example Request
GET /api/meshobjects/meshpaymentmethods?workspaceIdentifier=ejz76mpmdsv2&page=0&size=2 HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshpaymentmethod.v2.hal+json
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshpaymentmethods?workspaceIdentifier=ejz76mpmdsv2&page=0&size=2' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshpaymentmethod.v2.hal+json'
Response Fields
Path Type Description

_embedded

Object

Contains the actual content of the paged response.

_embedded.meshPaymentMethods[]

Array

List of meshPaymentMethod.

_links

Object

Currently only contains the self link and pagination links.

page

Object

See Paging information.
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.meshpaymentmethod.v2.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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: 1949

{
  "_embedded" : {
    "meshPaymentMethods" : [ {
      "apiVersion" : "v2",
      "kind" : "meshPaymentMethod",
      "metadata" : {
        "name" : "test-payment-method-1",
        "ownedByWorkspace" : "ejz76mpmdsv2"
      },
      "spec" : {
        "displayName" : "Test Payment Method 1",
        "tags" : { }
      },
      "_links" : {
        "self" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods/test-payment-method-1"
        },
        "meshprojects" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshprojects?paymentIdentifier=test-payment-method-1"
        }
      }
    }, {
      "apiVersion" : "v2",
      "kind" : "meshPaymentMethod",
      "metadata" : {
        "name" : "test-payment-method-2",
        "ownedByWorkspace" : "ejz76mpmdsv2"
      },
      "spec" : {
        "displayName" : "Test Payment Method 2",
        "tags" : { }
      },
      "_links" : {
        "self" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods/test-payment-method-2"
        },
        "meshprojects" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshprojects?paymentIdentifier=test-payment-method-2"
        }
      }
    } ]
  },
  "_links" : {
    "first" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods?workspaceIdentifier=ejz76mpmdsv2&page=0&size=2"
    },
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods?workspaceIdentifier=ejz76mpmdsv2&page=0&size=2"
    },
    "next" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods?workspaceIdentifier=ejz76mpmdsv2&page=1&size=2"
    },
    "last" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods?workspaceIdentifier=ejz76mpmdsv2&page=1&size=2"
    }
  },
  "page" : {
    "size" : 2,
    "totalElements" : 3,
    "totalPages" : 2,
    "number" : 0
  }
}
Get meshPaymentMethod

Get a single meshPaymentMethod. Deleted meshPaymentMethods can also be requested via this endpoint.

Request Headers
Name Description

Accept

meshApi is versioned and you should use application/vnd.meshcloud.api.meshpaymentmethod.v2.hal+json as an Accept header to be guaranteed the V2 response format of this endpoint. New versions will be added in future.
Example Request
GET /api/meshobjects/meshpaymentmethods/test-payment-method-1 HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshpaymentmethod.v2.hal+json
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshpaymentmethods/test-payment-method-1' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshpaymentmethod.v2.hal+json'
Response Fields
Path Type Description

apiVersion

String

Version of meshPaymentMethod datatype. Matches the version part provided within the Accept request header.

kind

String

As a common meshObject structure exists, every meshObject has a 'kind'. This is always 'meshPaymentMethod' for this endpoint.

metadata

Object

Always contains the 'name' and (optional) 'ownedByWorkspace' to uniquely identify the meshPaymentMethod.

metadata.name

String

The paymentMethodIdentifier as 'name'.

metadata.ownedByWorkspace

String

The workspaceIdentifier as 'ownedByWorkspace'.

spec

Object

All fields in this section describe the meshPaymentMethod.

spec.displayName

String

The display name of the meshPaymentMethod as it is shown in meshPanel.

spec.tags

Object

Key/Value pairs of tags set on the meshPaymentMethod. Keep in mind, that values are an array. Also see our general section about Tags

spec.amount

String

The amount of the meshPaymentMethod.

spec.expirationDate

String

The expiration date date of the meshPaymentMethod.

_links

Object

Available links on a meshPaymentMethod.
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.meshpaymentmethod.v2.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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: 518

{
  "apiVersion" : "v2",
  "kind" : "meshPaymentMethod",
  "metadata" : {
    "name" : "test-payment-method-1",
    "ownedByWorkspace" : "ejz76mpmdsv2"
  },
  "spec" : {
    "displayName" : "Test Payment Method 1",
    "tags" : { }
  },
  "_links" : {
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods/test-payment-method-1"
    },
    "meshprojects" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojects?paymentIdentifier=test-payment-method-1"
    }
  }
}

meshUser

All endpoints on meshUsers.

List meshUsers

Provides a paged list of meshUsers. Deleted meshUsers are not provided via this endpoint.

Note: In order to filter on WorkspaceUserGroups you must only specify the workspaceUserGroup Identifier and none of the other request parameters.

In case you filter on roles the response contains all meshUsers with that role regardless if they have been assigned directly or via a group. This offers for example a great opportunity to find the (contact) information of all Workspace Managers within one request, whereas the upcoming endpoints for the bindings (i.e. meshWorkspaceUserBinding, meshWorkspaceGroupBinding etc.) are not sufficient for this use-case. For that purpose several requests are required to cover direct user bindings and bindings via groups.

Note: Filtering on projects with the projectIdentifier requires a workspaceIdentifier, as a projectIdentifier is only unique within a meshWorkspace.

Request Headers
Name Description

Accept

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

workspaceIdentifier

Filter for meshUsers assigned to the meshWorkspace with given identifier. (optional)

projectIdentifier

Requires workspaceIdentifier. Filter for meshUsers having access to the meshProject of a certain workspace with given identifier. (optional)

platformIdentifier

Filter for meshUsers having access to a meshTenant which exist on the platform with given identifier. (optional)

workspaceRole

Filter for meshUsers with given workspace role name, e.g Workspace Manager. (optional)

projectRole

Filter for meshUsers with an active role by the given project role name. By default the following roles are used: Project Admin, Project User and Project Reader. (optional)

firstName

Filter for meshUsers based on their first name. (optional)

lastName

Filter for meshUsers based on their last name. (optional)

username

Filter for meshUsers based on their username. (optional)

email

Filter for meshUsers based on their E-mail. (optional)

euid

Filter for meshUsers based on their EUID. (optional)

page

The page number (default=0). See Paging information.

size

The amount of elements in a single page (default=50). See Paging information.
Example Request
GET /api/meshobjects/meshusers/?workspaceIdentifier=%20my-mobile-app-team&workspaceRole=Workspace%20Manager&page=0&size=1 HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshuser.v2.hal+json
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshusers/?workspaceIdentifier=%20my-mobile-app-team&workspaceRole=Workspace%20Manager&page=0&size=1' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshuser.v2.hal+json'
Response Fields
Path Type Description

_embedded

Object

Contains the actual content of the paged response.

_embedded.meshUsers[]

Array

List of meshUser.

_links

Object

Currently only contains the self link and pagination links.

page

Object

See Paging information.
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.meshuser.v2.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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: 1561

{
  "_embedded" : {
    "meshUsers" : [ {
      "apiVersion" : "v2",
      "kind" : "meshUser",
      "metadata" : {
        "name" : "john-doe"
      },
      "spec" : {
        "email" : "john-doe@example.com",
        "firstName" : "John",
        "lastName" : "Doe",
        "euid" : "fbc2760d-33e7-49b6-8ba2-221db41b897d",
        "tags" : {
          "environment" : [ "dev", "test", "qa" ]
        }
      },
      "_links" : {
        "self" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshusers/john-doe"
        },
        "meshworkspaceusergroups" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshworkspaceusergroups?username=john-doe"
        }
      }
    } ]
  },
  "_links" : {
    "first" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshusers/?workspaceIdentifier=%20my-mobile-app-team&workspaceRole=Workspace%20Manager&page=0&size=1"
    },
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshusers/?workspaceIdentifier=%20my-mobile-app-team&workspaceRole=Workspace%20Manager&page=0&size=1"
    },
    "next" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshusers/?workspaceIdentifier=%20my-mobile-app-team&workspaceRole=Workspace%20Manager&page=1&size=1"
    },
    "last" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshusers/?workspaceIdentifier=%20my-mobile-app-team&workspaceRole=Workspace%20Manager&page=1&size=1"
    }
  },
  "page" : {
    "size" : 1,
    "totalElements" : 2,
    "totalPages" : 2,
    "number" : 0
  }
}
Get meshUser

Get a single meshUser. Deleted meshUsers are not provided via this endpoint.

Request Headers
Name Description

Accept

meshApi is versioned and you should use application/vnd.meshcloud.api.meshuser.v2.hal+json as an Accept header to be guaranteed the V2 response format of this endpoint. New versions will be added in future.
Example Request
GET /api/meshobjects/meshusers/john-doe HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshuser.v2.hal+json
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshusers/john-doe' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshuser.v2.hal+json'
Response Fields
Path Type Description

apiVersion

String

Version of meshUser datatype. Matches the version part provided within the Accept request header.

kind

String

As a common meshObject structure exists, every meshObject has a 'kind'. This is always 'meshUser' for this endpoint.

metadata

Object

Always contains the 'name' to uniquely identify the meshUser.

metadata.name

String

The userIdentifier as 'name' to uniquely identify the meshUser.

spec

Object

All fields in this section describe the meshUser.

spec.email

String

The email of the meshUser.

spec.firstName

String

The firstname of the meshUser.

spec.lastName

String

The lastname of the meshUser.

spec.euid

String

External User ID which is used to lookup the user in the cloud platforms.

spec.tags

Object

Key/Value pairs of tags set on the meshUser. Keep in mind, that values are an array. Also see our general section about Tags

_links

Object

Available links on a meshUser.
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.meshuser.v2.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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: 579

{
  "apiVersion" : "v2",
  "kind" : "meshUser",
  "metadata" : {
    "name" : "john-doe"
  },
  "spec" : {
    "email" : "john-doe@example.com",
    "firstName" : "John",
    "lastName" : "Doe",
    "euid" : "fbc2760d-33e7-49b6-8ba2-221db41b897d",
    "tags" : {
      "environment" : [ "dev", "test", "qa" ]
    }
  },
  "_links" : {
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshusers/john-doe"
    },
    "meshworkspaceusergroups" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshworkspaceusergroups?username=john-doe"
    }
  }
}

meshWorkspaceUserGroup

All endpoints on meshWorkspaceUserGroups.

List meshWorkspaceUserGroups

Provides a paged list of meshWorkspaceUserGroups.

Request Headers
Name Description

Accept

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

page

The page number (default=0). See Paging information.

size

The amount of elements in a single page (default=50). See Paging information.

workspaceIdentifier

Filter for meshWorkspaceUserGroups that belong to the meshWorkspace with given identifier. (optional)

username

Filter for meshWorkspaceUserGroups that belong to the meshUser with given username. (optional)
Example Request
GET /api/meshobjects/meshworkspaceusergroups?username=sample-user&page=0&size=3 HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshworkspaceusergroup.v1.hal+json
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshworkspaceusergroups?username=sample-user&page=0&size=3' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshworkspaceusergroup.v1.hal+json'
Response Fields
Path Type Description

_embedded

Object

Contains the actual content of the paged response.

_embedded.meshWorkspaceUserGroups[]

Array

List of meshWorkspaceUserGroup.

_links

Object

Currently only contains the self link and pagination links.

page

Object

See Paging information.
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.meshworkspaceusergroup.v1.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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: 1088

{
  "_embedded" : {
    "meshWorkspaceUserGroups" : [ {
      "apiVersion" : "v1",
      "kind" : "meshWorkspaceUserGroup",
      "metadata" : {
        "name" : "my-user-group",
        "ownedByWorkspace" : "sample-workspace"
      },
      "spec" : {
        "displayName" : "My User Group",
        "members" : [ "sample-user" ],
        "tags" : { }
      },
      "_links" : {
        "self" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshworkspaceusergroups/sample-workspace.my-user-group"
        },
        "meshworkspace" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshworkspaces/sample-workspace"
        },
        "meshusers" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshusers?workspaceUserGroupIdentifier=my-user-group"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshworkspaceusergroups?username=sample-user&page=0&size=3"
    }
  },
  "page" : {
    "size" : 3,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}
Get meshWorkspaceUserGroup

Get a single meshWorkspaceUserGroup by a composed identifier containing workspace-identifier and group-identifier connected with a dot (e.g. "workspace-identifier.group-identifier"). For global groups, the workspace identifier is always "meshcloud-global-partner".

Request Headers
Name Description

Accept

meshApi is versioned and you should use application/vnd.meshcloud.api.meshworkspaceusergroup.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/meshworkspaceusergroups/sample-workspace.my-user-group HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshworkspaceusergroup.v1.hal+json
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshworkspaceusergroups/sample-workspace.my-user-group' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshworkspaceusergroup.v1.hal+json'
Response Fields
Path Type Description

apiVersion

String

Version of meshWorkspaceUserGroup datatype. Matches the version part provided within the Accept request header.

kind

String

As a common meshObject structure exists, every meshObject has a 'kind'. This is always 'meshWorkspaceUserGroup' for this endpoint.

metadata

Object

Always contains the 'name' to uniquely identify the meshWorkspaceUserGroup. It also contains the workspace name that owns this WorkspaceUserGroup.

metadata.name

String

The workspaceUserGroupIdentifier as 'name' to uniquely identify the meshWorkspaceUserGroup.

metadata.ownedByWorkspace

String

The identifier of the workspace that owns this WorkspaceUserGroup.

spec

Object

All fields in this section describe the meshWorkspaceUserGroup.

spec.displayName

String

The display name of the meshWorkspaceUserGroup as it is shown in meshPanel.

spec.egid

String

External Group Identifier, this is an optional field.

spec.members

Array

List of usernames

spec.tags

Object

Key/Value pairs of tags set on the meshWorkspaceUserGroup. Keep in mind, that values are an array. Also see our general section about Tags

_links

Object

Available links on a meshWorkspaceUserGroup.
Example Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Disposition: inline;filename=f.txt
Content-Type: application/vnd.meshcloud.api.meshworkspaceusergroup.v1.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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: 678

{
  "apiVersion" : "v1",
  "kind" : "meshWorkspaceUserGroup",
  "metadata" : {
    "name" : "my-user-group",
    "ownedByWorkspace" : "sample-workspace"
  },
  "spec" : {
    "displayName" : "My User Group",
    "members" : [ "sample-user" ],
    "tags" : { }
  },
  "_links" : {
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshworkspaceusergroups/sample-workspace.my-user-group"
    },
    "meshworkspace" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshworkspaces/sample-workspace"
    },
    "meshusers" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshusers?workspaceUserGroupIdentifier=my-user-group"
    }
  }
}

meshServiceInstance

All endpoints on meshServiceInstances.

List meshServiceInstances

Provides a paged list of meshServiceInstances. Deleted meshServiceInstances are not provided via this endpoint.

Request Headers
Name Description

Accept

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

workspaceIdentifier

Filter for meshServiceInstances that are part of the meshWorkspace with given identifier. (optional)

projectIdentifier

Requires workspaceIdentifier. Filter for meshServiceInstances that are part of the meshProject of a certain workspace with given identifier. (optional)

marketplaceIdentifier

Filter for meshServiceInstances that are part of a marketplace with given identifier. (optional)

serviceIdentifier

Filter for meshServiceInstances with given service identifier. (optional)

planIdentifier

Requires serviceIdentifier. Filter for meshServiceInstances with given service plan identifier. (optional)

page

The page number (default=0). See Paging information.

size

The amount of elements in a single page (default=50). See Paging information.
Example Request
GET /api/meshobjects/meshserviceinstances?workspaceIdentifier=my-mobile-app-team&page=0&size=1 HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshserviceinstance.v2.hal+json
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshserviceinstances?workspaceIdentifier=my-mobile-app-team&page=0&size=1' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshserviceinstance.v2.hal+json'
Response Fields
Path Type Description

_embedded

Object

Contains the actual content of the paged response.

_embedded.meshServiceInstances[]

Array

List of meshServiceInstance.

_links

Object

Currently only contains the self link and pagination links.

page

Object

See Paging information.
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.meshserviceinstance.v2.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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: 1346

{
  "_embedded" : {
    "meshServiceInstances" : [ {
      "apiVersion" : "v2",
      "kind" : "meshServiceInstance",
      "metadata" : {
        "ownedByProject" : "ejz76mtdg10",
        "ownedByWorkspace" : "my-mobile-app-team",
        "marketplaceIdentifier" : "ejz76mtdg1",
        "instanceId" : "ejz76mtdg11"
      },
      "spec" : {
        "displayName" : "ejz76mtdg12",
        "serviceId" : "ejz76mtdg5",
        "planId" : "ejz76mtdg7",
        "creator" : "Unknown"
      },
      "meaningfulIdentifier" : "meshServiceInstance[ejz76mtdg11, proj: ejz76mtdg10, ws: my-mobile-app-team]"
    } ]
  },
  "_links" : {
    "first" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshserviceinstances?workspaceIdentifier=my-mobile-app-team&page=0&size=1"
    },
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshserviceinstances?workspaceIdentifier=my-mobile-app-team&page=0&size=1"
    },
    "next" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshserviceinstances?workspaceIdentifier=my-mobile-app-team&page=1&size=1"
    },
    "last" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshserviceinstances?workspaceIdentifier=my-mobile-app-team&page=2&size=1"
    }
  },
  "page" : {
    "size" : 1,
    "totalElements" : 3,
    "totalPages" : 3,
    "number" : 0
  }
}

meshObject Declarative Import

To import existing cloud tenants to meshStack into existing company processes, meshStack provides an API to import meshObjects like meshWorkspace, meshProject, etc.

The Declarative Import allows external systems to use a PUT request method for importing meshObject definitions within a YAML or JSON definition. All supported meshObjects can be found under Supported meshObjects.

meshObjects can be imported into a meshObjectCollection (Beta) using the following optional request parameters.

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

meshObject Import 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 Parameters
Parameter Description

meshObjectCollection

the name of the meshObjectCollection the meshObjects should be imported into (optional)

owner

If meshObjectCollection parameter is provided, this is the owner of the meshObjectCollection (optional)
Example Request in YAML
PUT /api/meshobjects?meshObjectCollection=collectionName&owner=ownerName HTTP/1.1
Content-Type: application/vnd.meshcloud.api.meshobjects.v1+yaml;charset=UTF-8
Accept: application/vnd.meshcloud.api.meshobjects.v1+json
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Content-Length: 390
Host: mesh-backend-url


apiVersion: v1
kind: meshUser
metadata:
  name: test-user
spec:
  email: test1-user@meshcloud.io
  firstName: test-user-first-name
  lastName: test-user-last-name
  euid: test-euid
---
apiVersion: v1
kind: meshWorkspace
metadata:
  name: test-workspace
spec:
  displayName: test-display-name
  tags:
    environment:
      - dev
      - qa
      - prod
    anotherTag:
      - myValue
Example Curl Request in YAML
$ curl 'https://mesh-backend-url/api/meshobjects?meshObjectCollection=collectionName&owner=ownerName' -i -u 'valid_username:valid_password' -X PUT \
    -H 'Content-Type: application/vnd.meshcloud.api.meshobjects.v1+yaml;charset=UTF-8' \
    -H 'Accept: application/vnd.meshcloud.api.meshobjects.v1+json' \
    -d '
apiVersion: v1
kind: meshUser
metadata:
  name: test-user
spec:
  email: test1-user@meshcloud.io
  firstName: test-user-first-name
  lastName: test-user-last-name
  euid: test-euid
---
apiVersion: v1
kind: meshWorkspace
metadata:
  name: test-workspace
spec:
  displayName: test-display-name
  tags:
    environment:
      - dev
      - qa
      - prod
    anotherTag:
      - myValue
    '
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: 1; mode=block
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: 274

[ {
  "meshObject" : "meshUser[test-user]",
  "status" : "SUCCESS",
  "resultCode" : null,
  "message" : null,
  "remarks" : null
}, {
  "meshObject" : "meshWorkspace[test-workspace]",
  "status" : "SUCCESS",
  "resultCode" : null,
  "message" : null,
  "remarks" : null
} ]
Response Fields
Path Type Description

[]

Array

An JSON array with meshObject import results containing the following fields per import result:

[].meshObject

String

The name of the meshObject.

[].status

String

The import result status for this meshObject. (SUCCESS or FAILED)

[].resultCode

String?

Specific result code for this import result.

Possible values: WORKSPACE_NOT_FOUND , CUSTOMER_NOT_FOUND , PROJECT_NOT_FOUND , SERVER_ERROR

(might be null)

[].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)
Example Request
PUT /api/meshobjects?meshObjectCollection=collectionName&owner=ownerName HTTP/1.1
Content-Type: application/vnd.meshcloud.api.meshobjects.v1+json;charset=UTF-8
Accept: application/vnd.meshcloud.api.meshobjects.v1+json
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Content-Length: 638
Host: mesh-backend-url

[
  {
    "apiVersion": "v1",
    "kind": "meshUser",
    "metadata": {
      "name": "test-user"
    },
    "spec": {
      "email": "test1-user@meshcloud.io",
      "firstName": "test-user-first-name",
      "lastName": "test-user-last-name",
      "euid": "test-euid"
    }
  },
  {
    "apiVersion": "v1",
    "kind": "meshWorkspace",
    "metadata": {
      "name": "test-workspace"
    },
    "spec": {
      "displayName": "test-display-name",
      "tags": {
        "environment": [
          "dev",
          "qa",
          "prod"
        ],
        "anotherTag": [
          "myValue"
        ]
      }
    }
  }
]
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects?meshObjectCollection=collectionName&owner=ownerName' -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": "meshUser",
    "metadata": {
      "name": "test-user"
    },
    "spec": {
      "email": "test1-user@meshcloud.io",
      "firstName": "test-user-first-name",
      "lastName": "test-user-last-name",
      "euid": "test-euid"
    }
  },
  {
    "apiVersion": "v1",
    "kind": "meshWorkspace",
    "metadata": {
      "name": "test-workspace"
    },
    "spec": {
      "displayName": "test-display-name",
      "tags": {
        "environment": [
          "dev",
          "qa",
          "prod"
        ],
        "anotherTag": [
          "myValue"
        ]
      }
    }
  }
]'
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: 1; mode=block
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: 274

[ {
  "meshObject" : "meshUser[test-user]",
  "status" : "SUCCESS",
  "resultCode" : null,
  "message" : null,
  "remarks" : null
}, {
  "meshObject" : "meshWorkspace[test-workspace]",
  "status" : "SUCCESS",
  "resultCode" : null,
  "message" : null,
  "remarks" : null
} ]

The following table lists all supported meshObjects. Declarative deletion means that a previously imported resource will be deleted, if it is not specified in a subsequent import. Declarative deletion only works, if the respective resource is part of a meshObjectCollection (Beta).

Supported meshObjects
Name Description Import Declarative Deletion

meshUser

user accounts

yes

no

meshWorkspace

workspace accounts

yes

no

meshPaymentMethod

payment methods

yes

no

meshProject

projects

yes

no

meshWorkspaceUserGroup

a user group of a meshWorkspace/-Partner

yes

yes

meshWorkspaceUserBinding

assigns users to meshWorkspace/-Partner

yes

yes

meshWorkspaceGroupBinding

assigns groups to meshWorkspace/-Partner

yes

yes

meshProjectUserBinding

assigns users to projects

yes

no

meshProjectGroupBinding

assigns groups to projects

yes

no

meshTenant

connects projects with platforms

yes

no

meshServiceInstance

a service instance

yes

no

meshServiceBinding

a service binding

yes

no
meshUser
YAML
apiVersion: v1
kind: meshUser
metadata:
  name: john-doe
spec:
  email: john.doe@example.com
  firstName: John
  lastName: Doe
  euid: john-doe-123 # External User Identifier, this is an optional field.
  tags: # optional field.
    environment:
      - dev
      - qa
      - prod
    anotherTag:
      - myValue
JSON
{
  "apiVersion": "v1",
  "kind": "meshUser",
  "metadata": {
    "name": "john-doe"
  },
  "spec": {
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "euid": "john-doe-123",
    "tags": {
      "environment": [
        "dev",
        "qa",
        "prod"
      ],
      "anotherTag": [
        "myValue"
      ]
    }
  }
}

If tags are provided on a meshUser, they should be consistent with tags defined on meshWorkspaceUserGroups, as meshUsers and meshWorkspaceUserGroups are handled as if they are the same. This is especially important when making use of meshPolicies on these two types of objects.

meshWorkspace

See attribute definitions in GET endpoint section.

We strongly recommend assigning a single Workspace Owner when importing a meshWorkspace. You can assign a Workspace Owner via the meshWorkspaceUserBinding. Having a Workspace Owner is a best practice advocated by meshcloud. It allows you to have a clear responsibility and ownership of the meshWorkspace. This is useful when you want to get in touch with someone from a particular meshWorkspace and you need a clear contact person.

apiVersion: v1
kind: meshWorkspace
metadata:
  name: my-mobile-app-team # this must be unique, so it can be used as a unique reference to the meshWorkspace.
spec:
  displayName: Mobile App Team # The name of the meshWorkspace can be any length and contain any characters.
  tags:   # optional field
    environment:
      - dev
      - qa
      - prod
    anotherTag:
      - myValue
{
  "apiVersion": "v1",
  "kind": "meshWorkspace",
  "metadata": {
    "name": "my-mobile-app-team"
  },
  "spec": {
    "displayName": "Mobile App Team",
    "tags": {
      "environment": [
        "dev",
        "qa",
        "prod"
      ],
      "anotherTag": [
        "myValue"
      ]
    }
  }
}
meshPaymentMethod

See attribute definitions in GET endpoint section. If you want to assign this payment method to a project, you can do so using the meshProject object.

apiVersion: v2
kind: meshPaymentMethod
metadata:
  name: mobile-app-budget-2021 # must be unique across entire meshstack
  ownedByWorkspace: my-mobile-app-team
spec:
  displayName: Mobile App Budget 2021
  amount: 50000 #optional field, must be a number
  expirationDate: 2021-12-31 #optional field
  tags: #optional field
    costCenter:
      - 1332
    anotherTag:
      - myValue
      - someOtherValue
{
  "apiVersion": "v2",
  "kind": "meshPaymentMethod",
  "metadata": {
    "name": "mobile-app-budget-2021",
    "ownedByWorkspace": "my-mobile-app-team"
  },
  "spec": {
    "displayName": "Mobile App Budget 2021",
    "amount": 50000,
    "expirationDate": "2021-12-31",
    "tags": {
      "costCenter": [
        1332
      ],
      "anotherTag": [
        "myValue",
        "someOtherValue"
      ]
    }
  }
}
meshProject

See attribute definitions in GET endpoint section.

apiVersion: v2
kind: meshProject
metadata:
  name: mobile-app-prod
  ownedByWorkspace: my-mobile-app-team
spec:
  displayName: Mobile App Production
  tags: # optional field
    environment:
      - prod
  paymentMethodIdentifier: payment-id # optional field
  substitutePaymentMethodIdentifier: substitute-payment-id # optional field
{
  "apiVersion": "v2",
  "kind": "meshProject",
  "metadata": {
    "name": "mobile-app-prod",
    "ownedByWorkspace": "my-mobile-app-team"
  },
  "spec": {
    "displayName": "Mobile App Production",
    "tags": {
      "environment": [
        "prod"
      ]
    },
    "paymentMethodIdentifier": "payment-id",
    "substitutePaymentMethodIdentifier": "substitute-payment-id"
  }
}

The optional payment method identifiers can be used to link the meshProject with meshPaymentMethods. If meshPaymentMethods are already assigned to an existing meshProject the assignments will be updated on meshProject re-import. It is not valid to specify only a substitutePaymentMethodIdentifier without defining a paymentMethodIdentifier.

meshWorkspaceUserGroup

A meshWorkspaceUserGroup is a user group which can be owned by a meshWorkspace/meshPartner.

apiVersion: v1
kind: meshWorkspaceUserGroup
metadata:
  name: my-user-group
  ownedByWorkspace: my-mobile-app-team
spec:
  displayName: My User Group
  egid: sample-egid # External Group Identifier, this is an optional field.
  members: # list of usernames
    - john-doe
    - jane-doe
  tags: # optional field
    environment:
      - dev
      - qa
      - prod
    anotherTag:
      - myValue
{
  "apiVersion": "v1",
  "kind": "meshWorkspaceUserGroup",
  "metadata": {
    "name": "my-user-group",
    "ownedByWorkspace": "my-mobile-app-team"
  },
  "spec": {
    "displayName": "My User Group",
    "egid": "sample-egid",
    "members": [
      "john-doe",
      "jane-doe"
    ],
    "tags": {
      "environment": [
        "dev",
        "qa",
        "prod"
      ],
      "anotherTag": [
        "myValue"
      ]
    }
  }
}
meshWorkspaceUserBinding

A meshWorkspaceUserBinding is an assignment of users to a meshWorkspace/meshPartner.

apiVersion: v1
kind: meshWorkspaceUserBinding
roleRef:
  name: Workspace Manager
targetRef:
  name: my-mobile-app-team
subjects:
  - name: john-doe
  - name: jane-doe
{
  "apiVersion": "v1",
  "kind": "meshWorkspaceUserBinding",
  "roleRef": {
    "name": "Workspace Manager"
  },
  "targetRef": {
    "name": "my-mobile-app-team"
  },
  "subjects": [
    {
      "name": "john-doe"
    },
    {
      "name": "jane-doe"
    }
  ]
}
meshWorkspaceGroupBinding

Assigns a meshWorkspaceUserGroup to a meshWorkspace/meshPartner with the specified role. All users in the group will receive the rights from the role. The Workspace Owner role cannot be assigned to groups. It is only possible to assign users directly to that role. 4-eye-principle is not supported when creating a meshWorkspaceGroupBinding via this API.

apiVersion: v1
kind: meshWorkspaceGroupBinding
roleRef:
  name: Workspace Manager
targetRef:
  name: my-mobile-app-team
subjects:
  - name: my-user-group
  - name: and-another-user-group
{
  "apiVersion": "v1",
  "kind": "meshWorkspaceGroupBinding",
  "roleRef": {
    "name": "Workspace Manager"
  },
  "targetRef": {
    "name": "my-mobile-app-team"
  },
  "subjects": [
    {
      "name": "my-user-group"
    },
    {
      "name": "and-another-user-group"
    }
  ]
}
meshProjectUserBinding
apiVersion: v2
kind: meshProjectUserBinding
roleRef:
  name: Project Admin
targetRef:
  name: mobile-app-prod
  ownedByWorkspace: my-mobile-app-team
subjects:
  - name: john-doe
  - name: jane-doe
{
  "apiVersion": "v2",
  "kind": "meshProjectUserBinding",
  "roleRef": {
    "name": "Project Admin"
  },
  "targetRef": {
    "name": "mobile-app-prod",
    "ownedByWorkspace": "my-mobile-app-team"
  },
  "subjects": [
    {
      "name": "john-doe"
    },
    {
      "name": "jane-doe"
    }
  ]
}
meshProjectGroupBinding
apiVersion: v2
kind: meshProjectGroupBinding
roleRef:
  name: Project Employee
targetRef:
  name: mobile-app-prod
  ownedByWorkspace: my-mobile-app-team
subjects:
  - name: my-user-group
  - name: and-another-user-group
{
  "apiVersion": "v2",
  "kind": "meshProjectGroupBinding",
  "roleRef": {
    "name": "Project Employee"
  },
  "targetRef": {
    "name": "mobile-app-prod",
    "ownedByWorkspace": "my-mobile-app-team"
  },
  "subjects": [
    {
      "name": "my-user-group"
    },
    {
      "name": "and-another-user-group"
    }
  ]
}
meshTenant

See attribute definitions in GET endpoint section.

The localId property is optional. This means that a new tenant will be created within the specific platform if no localId was specified. The landingZone property may be skipped, e.g., for platforms that do not support landing zones.

The quotas must only contain keys that exist in the platform quota definitions for the respective platform, otherwise the import for the meshTenant will fail. Values of omitted quota keys defined in the platform quota definitions will be automatically set to the quotas of the specified landing zone.

apiVersion: v3
kind: meshTenant
metadata:
  ownedByProject: mobile-app-prod
  ownedByWorkspace: my-mobile-app-team
  platformIdentifier: platform-identifier.location-identifier
spec:
  localId: test-tenant # (optional) The tenant id, e.g. AWS account id or Azure subscription id.
  landingZoneIdentifier: test-landing-zone-id # (optional) The identifier of the landing zone.
  quotas: # Only for platforms that support quotas
    - key: limits.cpu
      value: 2000
    - key: limits.memory
      value: 100000
{
  "apiVersion": "v3",
  "kind": "meshTenant",
  "metadata": {
    "ownedByProject": "mobile-app-prod",
    "ownedByWorkspace": "my-mobile-app-team",
    "platformIdentifier": "platform-identifier.location-identifier"
  },
  "spec": {
    "localId": "test-tenant",
    "landingZoneIdentifier": "test-landing-zone-id",
    "quotas": [
      {
        "key": "limits.cpu",
        "value": 2000
      },
      {
        "key": "limits.memory",
        "value": 100000
      }
    ]
  }
}
meshServiceInstance
apiVersion: v2
kind: meshServiceInstance
metadata:
  ownedByProject: mobile-app-prod
  ownedByWorkspace: my-mobile-app-team
  marketplaceIdentifier: global # You can find the marketplace identifier in the meshCustomer service brokers list in the meshPanel
  instanceId: f78ab615-75a4-446f-b8fe-a6db672c039a  # will be used when creating bindings (see meshServiceBinding example below)
spec:
  displayName: My Service Instance
  serviceId: 0164a5b6-f909-434b-9015-46939e993797
  planId: c6d93bf8-642c-48a7-a629-91869a5180c3
  creator: john-doe  # username of the user to use for creating the service instance
  parameters: # parameters may also be mitigated by providing an empty object: {}
    myParam: myValue
{
  "apiVersion": "v2",
  "kind": "meshServiceInstance",
  "metadata": {
    "ownedByProject": "mobile-app-prod",
    "ownedByWorkspace": "my-mobile-app-team",
    "marketplaceIdentifier": "global",
    "instanceId": "f78ab615-75a4-446f-b8fe-a6db672c039a"
  },
  "spec": {
    "displayName": "My Service Instance",
    "serviceId": "0164a5b6-f909-434b-9015-46939e993797",
    "planId": "c6d93bf8-642c-48a7-a629-91869a5180c3",
    "creator": "john-doe",
    "parameters": {
      "myParam": "myValue"
    }
  }
}
meshServiceBinding
apiVersion: v1
kind: meshServiceInstanceBinding
metadata:
  ownedByServiceInstance: f78ab615-75a4-446f-b8fe-a6db672c039a
  bindingId: 32a3eb92-a210-48c4-b734-0b6f5874abc0
spec:
  displayName: My Service Instance Binding
  parameters: {}  # empty in this example
{
  "apiVersion": "v1",
  "kind": "meshServiceInstanceBinding",
  "metadata": {
    "ownedByServiceInstance": "f78ab615-75a4-446f-b8fe-a6db672c039a",
    "bindingId": "32a3eb92-a210-48c4-b734-0b6f5874abc0"
  },
  "spec": {
    "displayName": "My Service Instance Binding",
    "parameters": {}
  }
}

When binding to a tenant aware service you must also specify the tenant:

apiVersion: v1
kind: meshServiceInstanceBinding
metadata:
  ownedByServiceInstance: f78ab615-75a4-446f-b8fe-a6db672c039a
  bindingId: 32a3eb92-a210-48c4-b734-0b6f5874abc0
spec:
  displayName: My Binding With Tenant
  parameters:
    param: value
  tenant:
    localId: d4932d8f-2b31-4df7-be87-29a7ccd90a4d  # e.g. AWS account id or Azure subscription id
    platformIdentifier: aws.test-location
{
  "apiVersion": "v1",
  "kind": "meshServiceInstanceBinding",
  "metadata": {
    "ownedByServiceInstance": "f78ab615-75a4-446f-b8fe-a6db672c039a",
    "bindingId": "32a3eb92-a210-48c4-b734-0b6f5874abc0"
  },
  "spec": {
    "displayName": "My Binding With Tenant",
    "parameters": {
      "param": "value"
    },
    "tenant": {
      "localId": "d4932d8f-2b31-4df7-be87-29a7ccd90a4d",
      "platformIdentifier": "aws.test-location"
    }
  }
}
meshExchangeRate
apiVersion: v1
kind: meshExchangeRate
date: 2023-05-31
rates:
  - sourceCurrency: EUR
    targetCurrency: USD
    rate: 1.0647
  - sourceCurrency: USD
    targetCurrency: EUR
    rate: 0.93923
{
  "apiVersion": "v1",
  "kind": "meshExchangeRate",
  "date": "2023-05-31",
  "rates": [
    {
      "sourceCurrency": "EUR",
      "targetCurrency": "USD",
      "rate": 1.0647
    },
    {
      "sourceCurrency": "USD",
      "targetCurrency": "EUR",
      "rate": 0.93923
    }
  ]
}

meshObjectCollection (Beta)

A meshObjectCollection can be used to group together meshObjects that are created via the meshObject Declarative Import. meshObjectCollections belong to one owner that is responsible to keep the meshObjectCollection updated. Modifications to any meshObjects from a meshObjectCollection can only be done by the specified owner via the meshObject API.

The createMeshObjectCollection endpoint must be called once to create a new meshObjectCollection before the meshObject API can assign meshObjects to it.

meshObjectCollections are currently in Beta state. As of now adding meshObjects to meshObjectCollections works using the meshObject API. Deletion will follow at a later stage.

createMeshObjectCollection

This endpoint will create a new empty meshObjectCollection.

Request Headers
Name Description

Content-Type

meshObjectCollections are versioned and currently only support application/vnd.meshcloud.api.meshobjectcollection.v1+json as a Content-Type.
Request Fields
Path Type Description

name

String

Name of the meshObjectCollection (has to be unique)

owner

String

The owner of the meshObjectCollection

description

String

A freetext field to help describing the contents of the meshObjectCollection
Example Request
POST /api/meshobjectcollections HTTP/1.1
Content-Type: application/vnd.meshcloud.api.meshobjectcollection.v1+json;charset=UTF-8
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Content-Length: 150
Host: mesh-backend-url


      {
        "name": "collection-name",
        "owner": "collection-owner",
        "description": "This is a meshObjectCollection."
      }
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjectcollections' -i -u 'valid_username:valid_password' -X POST \
    -H 'Content-Type: application/vnd.meshcloud.api.meshobjectcollection.v1+json;charset=UTF-8' \
    -d '
      {
        "name": "collection-name",
        "owner": "collection-owner",
        "description": "This is a meshObjectCollection."
      }
    '
Example Response
HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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

deleteMeshObjectCollection

This endpoint can be used to delete an existing meshObjectCollection. It will not remove any meshObjects and works only for empty meshObjectCollections. To delete a meshObjectCollection and all assigned meshObjects, those have to be deleted manually before calling this endpoint.

Request Headers
Name Description

Content-Type

meshObjectCollections are versioned and currently only support application/vnd.meshcloud.api.meshobjectcollection.v1+json as a Content-Type.
Request Fields
Path Type Description

name

String

Name of the meshObjectCollection

owner

String

The owner of the meshObjectCollection
Example Request
DELETE /api/meshobjectcollections HTTP/1.1
Content-Type: application/vnd.meshcloud.api.meshobjectcollection.v1+json;charset=UTF-8
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Content-Length: 92
Host: mesh-backend-url


      {
        "name": "collection-name",
        "owner": "collection-owner"
      }
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjectcollections' -i -u 'valid_username:valid_password' -X DELETE \
    -H 'Content-Type: application/vnd.meshcloud.api.meshobjectcollection.v1+json;charset=UTF-8' \
    -d '
      {
        "name": "collection-name",
        "owner": "collection-owner"
      }
    '
Example Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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
Example Error Response
HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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: 171

{
  "error" : "MeshBadRequestException",
  "message" : "MeshObjectCollection not-empty-collection cannot be deleted, because it is not empty",
  "errorId" : "6jCwuymoad"
}

Metadata

Cloud Platforms may want to enrich their tenant metadata with meshMetadata. This could e.g. be billing information. This metadata can be retrieved via the endpoints defined in this section.

Request Headers
Name Description

Accept

meshApi is versioned and you should use application/vnd.meshcloud.api.metadata.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/metadata HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.metadata.v1.hal+json
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/metadata' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.metadata.v1.hal+json'
Response Fields
Path Type Description

_links

Object

All available Metadata Links for the authenticated user.
Relation Description

openstackProjectMetadata

Link to openStackProjectMetadata to retrieve metadata for tagging OpenStack resources.
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.metadata.v1.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
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: 220

{
  "_links" : {
    "openstackProjectMetadata" : {
      "href" : "https://mesh-backend-url/api/metadata/openstackProjectMetadata"
    },
    "self" : {
      "href" : "https://mesh-backend-url/api/metadata"
    }
  }
}

openStackProjectMetadata

This endpoint returns metadata information for the requested project-id. This endpoint is based on OpenStack vendor data (https://docs.openstack.org/nova/rocky/user/vendordata.html).

Request Fields
Path Type Description

project-id

String

The ID of the project metadata information shall be retrieved for.
Example Request
POST /api/metadata/openstackProjectMetadata HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Content-Length: 82
Host: mesh-backend-url


      {
        "project-id": "d3fc4451-f555-44f2-b651-c8062d21d0e3"
      }
Example Curl Request
$ curl 'https://mesh-backend-url/api/metadata/openstackProjectMetadata' -i -u 'valid_username:valid_password' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '
      {
        "project-id": "d3fc4451-f555-44f2-b651-c8062d21d0e3"
      }
    '
Response Fields
Path Type Description

project-identifier

String

Immutable unique identifier of the project.

project-display-name

String

Human readable project name.

customer-identifier

String

Immutable unique identifier of the customer

customer-display-name

String

Human readable customer name.

tags

Object

Custom tags specified on the project.

tags.costCenter

Array

A cost center number could be a custom tag.

tags.customNumber

Array

And any further attribute can be provided as a tag.
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: 1; mode=block
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: 280

{
  "project-identifier" : "test-project-identifier",
  "project-display-name" : "test-project",
  "customer-identifier" : "test-customer-identifier",
  "customer-display-name" : "test-customer",
  "tags" : {
    "costCenter" : [ "1235" ],
    "customNumber" : [ "1645789" ]
  }
}