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.

The first step for being able to use the new Postman Collection is to import it in Postman. To proceed, Authentication information must be provided centrally in the collection. You can 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. In that case you provide Basic Auth credentials. You can also use API Keys, which require a Bearer Token authentication. 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

This section covers the authentication mechanisms available in the API. Users must authenticate themselves to access the API endpoints. The supported methods are Basic Authentication and API Keys.

Basic Authentication

Basic Authentication requires the user to provide a valid username and password to authenticate. For that, you can make use of API users, which can be used for Basic Authentication, 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:

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.

API Keys

API keys authorize requests towards the meshObject API within the scope of the respective workspace. To issue workspace-scoped API Keys, navigate to the admin or workspace area. Follow these steps:

  1. Open the respective workspace.

  2. Go to Workspace Access > API Keys.

  3. Issue a new API key by clicking + Create API Key.

  4. Provide a name and the permissions the API key shall get.

  5. Save the secret and key ID securely to make requests.

The permissions you can set in 4. do not include all endpoints of this API. So via API Keys you can currently only get access to a limited amount of endpoints. You can identify which ones these are via the naming of these permissions inside meshStack.

The login endpoint is described here.

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: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 257

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

API Key Login

To call the API with an API key, first issue an API call to the backend to receive a short-lived bearer token. Send a request to /api/login with the following keys in the body of the request in the x-www-form-urlencoded format.

Please be aware, that this endpoint only provides a redirect to meshStack’s IdP. So you have to either configure your request to follow the redirect or manually implement the redirect to meshStack’s IdP.

Request Headers
Name Description

Content-Type

The content type of the request

Request Parameters
Parameter Description

client_id

The Key ID assigned to your API key upon creation. This ID is used to authenticate your application.

client_secret

The Key Secret associated with your API key. This secret is used in conjunction with the client_id to securely authenticate your application.

grant_type

The grant type, which must be 'client_credentials'.

Example HTTP Request
$ http --form -follow POST 'https://mesh-backend-url/api/login' \
    'client_id=8a616394-98ad-4541-a0e9-e280f5d92249' \
    'client_secret=abcdefghijklmnopqrstuvwxyz0123456789' \
    'grant_type=client_credentials'
Example Curl Request
$ curl 'https://mesh-backend-url/api/login' -i -L -X POST \
    -d 'client_id=8a616394-98ad-4541-a0e9-e280f5d92249&client_secret=abcdefghijklmnopqrstuvwxyz0123456789&grant_type=client_credentials'
Response Fields
Parameter Description

access_token

The access token received upon successful authentication. Use this token in the Authorization header of subsequent requests to access protected resources.

expires_in

Access token are valid for 5 minutes by default. This expires_in property provides the expiration time in seconds and should usually be set to 300.

not-before-policy

This policy is not activated and the value should therefore be 0.

refresh_expires_in

Refresh Tokens are not supported at the moment and the value should therefore be 0.

scope

meshStack does not use scopes for authorization, so only the default scopes profile & email are provided.

access_type

The type of the token is 'Bearer'. This is how the token should be used in the Authorization header.

Example Response
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json
Pragma: no-cache
Referrer-Policy: no-referrer
Set-Cookie: KC_RESTART=; Version=1; Expires=Thu, 01-Jan-2024 00:00:10 GMT; Max-Age=0; Path=/auth/realms/meshfed/; HttpOnly
Set-Cookie: KC_AUTH_STATE=; Version=1; Expires=Thu, 01-Jan-2024 00:00:10 GMT; Max-Age=0; Path=/auth/realms/meshfed/
Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
Content-Length: 1482
{
    "access_token": "ey...",
    "expires_in": 300,
    "not-before-policy": 0,
    "refresh_expires_in": 0,
    "scope": "profile email",
    "token_type": "Bearer"
}

Use the token in further requests by specifying it in the authorization header. This documentation always shows Basic Auth headers in the example requests. To authenticate requests via API keys, please set the Authorization header as such:

Authorization: Bearer <access_token>

Building Block Runner API

The Block Runner API is used by the block runner which execute building block runs. This API is part of the meshObject API. At the moment it is not possible to write fully custom block runner, but it is possible to write a building block which hands over execution to an external system (for example a Github Action). This is called an asynchronous building block run. The external system is then responsible for providing status updates for the building block run via the meshObject 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.

meshprojectgroupbindings

Gets meshProjectGroupBindings for this meshProject.

meshprojectuserbindings

Gets meshProjectUserBindings for this meshProject.

meshworkspaceuserbindings

Get meshWorkspaceUserBinding.

meshtenants

Get meshTenants.

meshpaymentmethods

Get meshPaymentMethods.

meshusers

Get meshUsers.

meshserviceinstances

Get meshServiceInstances.

meshbuildingblocks

Get meshBuildingBlocks.

meshbuildingblockruns

Get meshBuildingBlockRuns.

meshtagdefinitions

Get meshTagDefinitions.

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: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 2664

{
  "_links" : {
    "meshprojects" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojects{?workspaceIdentifier,paymentIdentifier}",
      "templated" : true
    },
    "meshprojectgroupbindings" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojectbindings/groupbindings?workspaceIdentifier={workspaceIdentifier}&projectIdentifier={projectIdentifier}",
      "templated" : true
    },
    "meshprojectuserbindings" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojectbindings/userbindings?workspaceIdentifier={workspaceIdentifier}&projectIdentifier={projectIdentifier}",
      "templated" : true
    },
    "meshtenants" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshtenants{?workspaceIdentifier,projectIdentifier,platformIdentifier,deletionState}",
      "templated" : true
    },
    "meshtagdefinitions" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshtagdefinitions"
    },
    "meshusers" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshusers{?workspaceIdentifier,projectIdentifier,platformIdentifier,workspaceUserGroupIdentifier,projectRole,workspaceRole,email,firstName,lastName,username,euid}",
      "templated" : true
    },
    "meshworkspaceusergroups" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshworkspaceusergroups{?workspaceIdentifier,username}",
      "templated" : true
    },
    "meshworkspaceuserbindings" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshworkspacebindings/userbindings{?username,workspaceRole,workspaceIdentifier}",
      "templated" : true
    },
    "meshworkspaces" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshworkspaces"
    },
    "meshpaymentmethods" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods{?workspaceIdentifier}",
      "templated" : true
    },
    "meshbuildingblocks" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshbuildingblocks{?workspaceIdentifier,customerIdentifier,projectIdentifier,platformIdentifier,name,definitionName,versionNumber,status}",
      "templated" : true
    },
    "meshbuildingblockruns" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshbuildingblockruns?runnerNodeId={runnerNodeId}{&selector}",
      "templated" : true
    },
    "meshserviceinstances" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshserviceinstances{?workspaceIdentifier,projectIdentifier,marketplaceIdentifier,serviceIdentifier,planIdentifier}",
      "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: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 4124

{
  "_embedded" : {
    "meshWorkspaces" : [ {
      "kind" : "meshWorkspace",
      "apiVersion" : "v1",
      "metadata" : {
        "name" : "admin-customer",
        "createdOn" : "2024-10-16T10:33:11Z"
      },
      "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?workspaceIdentifier=admin-customer"
        },
        "meshpaymentmethods" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods?workspaceIdentifier=admin-customer"
        },
        "meshworkspaceusergroups" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshworkspaceusergroups?workspaceIdentifier=admin-customer"
        }
      }
    }, {
      "kind" : "meshWorkspace",
      "apiVersion" : "v1",
      "metadata" : {
        "name" : "demo-customer",
        "createdOn" : "2024-10-16T10:33:11Z"
      },
      "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?workspaceIdentifier=demo-customer"
        },
        "meshpaymentmethods" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods?workspaceIdentifier=demo-customer"
        },
        "meshworkspaceusergroups" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshworkspaceusergroups?workspaceIdentifier=demo-customer"
        }
      }
    }, {
      "kind" : "meshWorkspace",
      "apiVersion" : "v1",
      "metadata" : {
        "name" : "demo-partner",
        "createdOn" : "2024-10-16T10:33:11Z"
      },
      "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?workspaceIdentifier=demo-partner"
        },
        "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" : 6,
    "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: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 1055

{
  "kind" : "meshWorkspace",
  "apiVersion" : "v1",
  "metadata" : {
    "name" : "admin-customer",
    "createdOn" : "2024-10-16T10:33:11Z"
  },
  "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?workspaceIdentifier=admin-customer"
    },
    "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=ezth6mpdsv2&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=ezth6mpdsv2&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: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 2283

{
  "_embedded" : {
    "meshProjects" : [ {
      "kind" : "meshProject",
      "apiVersion" : "v2",
      "metadata" : {
        "name" : "test-project-1",
        "ownedByWorkspace" : "ezth6mpdsv2",
        "createdOn" : "2024-10-16T10:34:10.539050764Z"
      },
      "spec" : {
        "displayName" : "Test Project 1",
        "tags" : { },
        "paymentMethodIdentifier" : "test-payment"
      },
      "_links" : {
        "self" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshprojects/ezth6mpdsv2.test-project-1"
        },
        "meshtenants" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshtenants?workspaceIdentifier=ezth6mpdsv2&projectIdentifier=test-project-1"
        },
        "meshusers" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshusers?workspaceIdentifier=ezth6mpdsv2&projectIdentifier=test-project-1"
        },
        "activePaymentMethod" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods/test-payment"
        },
        "meshprojectuserbindings" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshprojectbindings/userbindings?workspaceIdentifier=ezth6mpdsv2&projectIdentifier=test-project-1"
        },
        "meshprojectgroupbindings" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshprojectbindings/groupbindings?workspaceIdentifier=ezth6mpdsv2&projectIdentifier=test-project-1"
        }
      }
    } ]
  },
  "_links" : {
    "first" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojects?workspaceIdentifier=ezth6mpdsv2&paymentIdentifier=test-payment&page=0&size=1"
    },
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojects?workspaceIdentifier=ezth6mpdsv2&paymentIdentifier=test-payment&page=0&size=1"
    },
    "next" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojects?workspaceIdentifier=ezth6mpdsv2&paymentIdentifier=test-payment&page=1&size=1"
    },
    "last" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojects?workspaceIdentifier=ezth6mpdsv2&paymentIdentifier=test-payment&page=1&size=1"
    }
  },
  "page" : {
    "size" : 1,
    "totalElements" : 2,
    "totalPages" : 2,
    "number" : 0
  }
}
Get meshProject

Get a single meshProject. A specific project is identified by <workspace identifier>.<project identifier>. 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/ezth6mpdsv2.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/ezth6mpdsv2.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: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 1354

{
  "kind" : "meshProject",
  "apiVersion" : "v2",
  "metadata" : {
    "name" : "test-project-1",
    "ownedByWorkspace" : "ezth6mpdsv2",
    "createdOn" : "2024-10-16T10:34:10.539050764Z",
    "deletedOn" : "2024-10-16T10:34:11.847106082Z"
  },
  "spec" : {
    "displayName" : "Test Project 1",
    "tags" : { },
    "paymentMethodIdentifier" : "test-payment"
  },
  "_links" : {
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojects/ezth6mpdsv2.test-project-1"
    },
    "meshtenants" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshtenants?workspaceIdentifier=ezth6mpdsv2&projectIdentifier=test-project-1"
    },
    "meshusers" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshusers?workspaceIdentifier=ezth6mpdsv2&projectIdentifier=test-project-1"
    },
    "activePaymentMethod" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods/test-payment"
    },
    "meshprojectuserbindings" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojectbindings/userbindings?workspaceIdentifier=ezth6mpdsv2&projectIdentifier=test-project-1"
    },
    "meshprojectgroupbindings" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojectbindings/groupbindings?workspaceIdentifier=ezth6mpdsv2&projectIdentifier=test-project-1"
    }
  }
}
Post meshProject

Creating a meshProject.

Request Headers
Name Description

Content-Type

You should use application/vnd.meshcloud.api.meshproject.v2.hal+json as an Content-Type header.

Accept

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

Request Body

The fields have the same meaning as the response fields.

{
  "apiVersion" : "v2",
  "kind": "meshProject",
  "spec" : {
    "displayName" : "Test Project 3",
    "tags" : { },
    "paymentMethodIdentifier" : "test-payment"
  },
  "metadata" : {
    "name" : "test-project-3",
    "ownedByWorkspace" : "ezth6mpdsv2"
  }
}
Example Request
POST /api/meshobjects/meshprojects HTTP/1.1
Content-Type: application/vnd.meshcloud.api.meshproject.v2.hal+json;charset=UTF-8
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshproject.v2.hal+json
Content-Length: 263
Host: mesh-backend-url

{
  "apiVersion" : "v2",
  "kind": "meshProject",
  "spec" : {
    "displayName" : "Test Project 3",
    "tags" : { },
    "paymentMethodIdentifier" : "test-payment"
  },
  "metadata" : {
    "name" : "test-project-3",
    "ownedByWorkspace" : "ezth6mpdsv2"
  }
}
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshprojects' -i -u 'valid_username:valid_password' -X POST \
    -H 'Content-Type: application/vnd.meshcloud.api.meshproject.v2.hal+json;charset=UTF-8' \
    -H 'Accept: application/vnd.meshcloud.api.meshproject.v2.hal+json' \
    -d '{
  "apiVersion" : "v2",
  "kind": "meshProject",
  "spec" : {
    "displayName" : "Test Project 3",
    "tags" : { },
    "paymentMethodIdentifier" : "test-payment"
  },
  "metadata" : {
    "name" : "test-project-3",
    "ownedByWorkspace" : "ezth6mpdsv2"
  }
}'
Request 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

Fixed fields that help to identify the meshProject.

metadata.name

String

The identifier that should be unique within a workspace

metadata.ownedByWorkspace

String

The identifier of the workspace that the project should belong to.

spec

Object

All fields in this section describe the project.

spec.displayName

String

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

spec.tags

Object

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

spec.paymentMethodIdentifier

String

The payment method of the project.

spec.substitutePaymentMethodIdentifier

String

The substitute payment method of the project.

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: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 1302

{
  "kind" : "meshProject",
  "apiVersion" : "v2",
  "metadata" : {
    "name" : "test-project-3",
    "ownedByWorkspace" : "ezth6mpdsv2",
    "createdOn" : "2024-10-16T10:34:10.977849986Z"
  },
  "spec" : {
    "displayName" : "Test Project 3",
    "tags" : { },
    "paymentMethodIdentifier" : "test-payment"
  },
  "_links" : {
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojects/ezth6mpdsv2.test-project-3"
    },
    "meshtenants" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshtenants?workspaceIdentifier=ezth6mpdsv2&projectIdentifier=test-project-3"
    },
    "meshusers" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshusers?workspaceIdentifier=ezth6mpdsv2&projectIdentifier=test-project-3"
    },
    "activePaymentMethod" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods/test-payment"
    },
    "meshprojectuserbindings" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojectbindings/userbindings?workspaceIdentifier=ezth6mpdsv2&projectIdentifier=test-project-3"
    },
    "meshprojectgroupbindings" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojectbindings/groupbindings?workspaceIdentifier=ezth6mpdsv2&projectIdentifier=test-project-3"
    }
  }
}
Delete meshProject

Delete a single meshProject. The project is marked as "Pending Deletion" and the deletion process is started for all tenants. Depending on their Landing Zone setting they are either automatically deleted or require manual confirmation from a platform operator. Tenants first require the full removal of all additional services like Service Instances (OSB) or Building Blocks. If one tenant still has such active services the project deletion will fail.

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.

/api/meshobjects/meshprojects/{fullProjectIdentifier}
Parameter Description

fullProjectIdentifier

The full project identifier is a unique string consisting of the workspace identifier and project identifier separated by '.'.

Example Request
DELETE /api/meshobjects/meshprojects/ezth6mpdsv2.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/ezth6mpdsv2.test-project-1' -i -u 'valid_username:valid_password' -X DELETE \
    -H 'Accept: application/vnd.meshcloud.api.meshproject.v2.hal+json'
Example Response
HTTP/1.1 202 Accepted
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY

meshProjectUserBinding

A meshProjectUserBinding is an assignment of users to a project with a specified project role. These project roles grant users a specific set of permissions within the cloud platforms used by the project. The actual permissions that the role have within the platform tenant are determined by the policies set by your cloud foundation team.

List meshProjectUserBindings

Provides a paged list of meshProjectUserBindings.

Request Headers
Name Description

Accept

meshApi is versioned and you should use application/vnd.meshcloud.api.meshprojectuserbinding.v3.hal+json as an Accept header to be guaranteed the expected response format of this endpoint. New versions will be added in future.

Request Parameters
Parameter Description

workspaceIdentifier

The identifier of the workspace the project with the bindings belongs to.

projectIdentifier

The project identifier of the project that contains the requested bindings.

Example Request
GET /api/meshobjects/meshprojectbindings/userbindings?workspaceIdentifier=test-workspace&projectIdentifier=test-project-1 HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshprojectuserbinding.v3.hal+json
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshprojectbindings/userbindings?workspaceIdentifier=test-workspace&projectIdentifier=test-project-1' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshprojectuserbinding.v3.hal+json'
Response Fields
Path Type Description

_embedded.meshProjectUserBindings[]

Array

List of meshProjectUserBindings.

_embedded.meshProjectUserBindings[].roleRef.name

String

The name of the referenced role for this user.

_embedded.meshProjectUserBindings[].targetRef.name

String

The identifier of the project the user is assigned to.

_embedded.meshProjectUserBindings[].targetRef.displayName

String

The name of the project the user is assigned to.

_embedded.meshProjectUserBindings[].targetRef.ownedByWorkspace

String

The identifier of the workspace which contains the project.

_embedded.meshProjectUserBindings[].subject.name

String

The username of the referenced user.

_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.meshprojectuserbinding.v3.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 982

{
  "_embedded" : {
    "meshProjectUserBindings" : [ {
      "kind" : "meshProjectUserBinding",
      "apiVersion" : "v3",
      "metadata" : {
        "name" : "56120fe7-1ae3-42ba-a91b-b3369004cf17"
      },
      "roleRef" : {
        "name" : "Project User"
      },
      "targetRef" : {
        "name" : "test-project-1",
        "displayName" : "Test Project 1",
        "ownedByWorkspace" : "test-workspace"
      },
      "subject" : {
        "name" : "username1"
      },
      "_links" : {
        "self" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshprojectbindings/userbindings/56120fe7-1ae3-42ba-a91b-b3369004cf17"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojectbindings/userbindings?workspaceIdentifier=test-workspace&projectIdentifier=test-project-1"
    }
  },
  "page" : {
    "size" : 1,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}
Get meshProjectUserBinding

Get a single meshProjectUserBinding.

Request Headers
Name Description

Accept

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

Example Request
GET /api/meshobjects/meshprojectbindings/userbindings/56120fe7-1ae3-42ba-a91b-b3369004cf17 HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshprojectuserbinding.v3.hal+json
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshprojectbindings/userbindings/56120fe7-1ae3-42ba-a91b-b3369004cf17' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshprojectuserbinding.v3.hal+json'
Response Fields
Path Type Description

apiVersion

String

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

metadata

Object

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

metadata.name

String

The meshProjectUserBinding identifier as 'name' to uniquely identify the meshProjectUserBinding.

roleRef.name

String

The name of the referenced role for this user.

targetRef.name

String

The identifier of the project the user is assigned to.

targetRef.displayName

String

The name of the project the user is assigned to.

targetRef.ownedByWorkspace

String

The identifier of the workspace which contains the project.

subject.name

String

The username of the referenced user.

_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-Type: application/vnd.meshcloud.api.meshprojectuserbinding.v3.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 534

{
  "kind" : "meshProjectUserBinding",
  "apiVersion" : "v3",
  "metadata" : {
    "name" : "56120fe7-1ae3-42ba-a91b-b3369004cf17"
  },
  "roleRef" : {
    "name" : "Project User"
  },
  "targetRef" : {
    "name" : "test-project-1",
    "displayName" : "Test Project 1",
    "ownedByWorkspace" : "test-workspace"
  },
  "subject" : {
    "name" : "username1"
  },
  "_links" : {
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojectbindings/userbindings/56120fe7-1ae3-42ba-a91b-b3369004cf17"
    }
  }
}
Post meshProjectUserBinding

Creating a meshProjectUserBinding assigns the users to a project with a specified project role, which grants them the corresponding permissions within the cloud platform. Before users can be assigned to a project, they must first be added to the workspace that owns that project.

Request Headers
Name Description

Content-Type

meshApi is versioned and you should use application/vnd.meshcloud.api.meshprojectuserbinding.v3.hal+json as a Content-Type header.

Accept

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

Request Body

The fields have the same meaning as the response fields.

{
  "apiVersion": "v3",
  "kind": "meshProjectUserBinding",
  "metadata": {
    "name": "user-binding-name"
  },
  "targetRef": {
    "name": "test-project-1",
    "ownedByWorkspace": "test-workspace"
  },
  "roleRef": { "name": "Project Reader" },
  "subject": {
    "name" : "username3"
  }
}
Example Request
POST /api/meshobjects/meshprojectbindings/userbindings HTTP/1.1
Content-Type: application/vnd.meshcloud.api.meshprojectuserbinding.v3.hal+json;charset=UTF-8
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshprojectuserbinding.v3.hal+json
Content-Length: 296
Host: mesh-backend-url

{
  "apiVersion": "v3",
  "kind": "meshProjectUserBinding",
  "metadata": {
    "name": "user-binding-name"
  },
  "targetRef": {
    "name": "test-project-1",
    "ownedByWorkspace": "test-workspace"
  },
  "roleRef": { "name": "Project Reader" },
  "subject": {
    "name" : "username3"
  }
}
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshprojectbindings/userbindings' -i -u 'valid_username:valid_password' -X POST \
    -H 'Content-Type: application/vnd.meshcloud.api.meshprojectuserbinding.v3.hal+json;charset=UTF-8' \
    -H 'Accept: application/vnd.meshcloud.api.meshprojectuserbinding.v3.hal+json' \
    -d '{
  "apiVersion": "v3",
  "kind": "meshProjectUserBinding",
  "metadata": {
    "name": "user-binding-name"
  },
  "targetRef": {
    "name": "test-project-1",
    "ownedByWorkspace": "test-workspace"
  },
  "roleRef": { "name": "Project Reader" },
  "subject": {
    "name" : "username3"
  }
}  '
Response Fields
Path Type Description

apiVersion

String

Version of this object

roleRef.name

String

The name of the referenced role for this user.

targetRef.name

String

The identifier of the project the user was assigned to.

targetRef.displayName

String

The name of the project the user was assigned to.

targetRef.ownedByWorkspace

String

The identifier of the workspace which contains the project.

metadata.name

String

Name of this binding which later can be used to refer to it

subject.name

String

The username of the referenced user.

kind

String

Type of the returned meshObject

_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.meshprojectuserbinding.v3.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 498

{
  "kind" : "meshProjectUserBinding",
  "apiVersion" : "v3",
  "metadata" : {
    "name" : "user-binding-name"
  },
  "roleRef" : {
    "name" : "Project Reader"
  },
  "targetRef" : {
    "name" : "test-project-1",
    "displayName" : "Test Project 1",
    "ownedByWorkspace" : "test-workspace"
  },
  "subject" : {
    "name" : "username3"
  },
  "_links" : {
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojectbindings/userbindings/user-binding-name"
    }
  }
}
Update meshProjectUserBindings

An update is currently not possible. To change a user binding, you must first delete the existing binding and then re-create it, for example, with the updated role.

Delete meshProjectUserBinding

Deleting a meshProjectUserBinding removes the assignment of a user from a project and revokes their associated project role. This action effectively withdraws the permissions granted to the user within the cloud platforms linked to the project.

Request Headers

There are no special headers required.

Example Request
DELETE /api/meshobjects/meshprojectbindings/userbindings/user-binding-name HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshprojectbindings/userbindings/user-binding-name' -i -u 'valid_username:valid_password' -X DELETE
Example Response

The response is just an empty HTTP 204.

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

meshProjectGroupBinding

A meshProjectGroupBinding is an assignment of groups to a project with a specified project role. These project roles grant groups a specific set of permissions within the cloud platforms used by the project. The actual permissions that the role have within the platform tenant are determined by the policies set by your cloud foundation team.

List meshProjectGroupBindings

Provides a paged list of meshProjectGroupBindings.

Request Headers
Name Description

Accept

meshApi is versioned and you should use application/vnd.meshcloud.api.meshprojectgroupbinding.v3.hal+json as an Accept header to be guaranteed the expected response format of this endpoint. New versions will be added in future.

Request Parameters
Parameter Description

workspaceIdentifier

The identifier of the workspace containing the project with the requested bindings.

projectIdentifier

The project identifier of the project that contains the requested bindings

Example Request
GET /api/meshobjects/meshprojectbindings/groupbindings?workspaceIdentifier=test-workspace&projectIdentifier=test-project-1 HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshprojectgroupbinding.v3.hal+json
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshprojectbindings/groupbindings?workspaceIdentifier=test-workspace&projectIdentifier=test-project-1' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshprojectgroupbinding.v3.hal+json'
Response Fields
Path Type Description

_embedded.meshProjectGroupBindings[]

Array

List of meshProjectGroupBindings.

_embedded.meshProjectGroupBindings[].roleRef.name

String

The name of the referenced role for this group.

_embedded.meshProjectGroupBindings[].targetRef.name

String

The identifier of the project the group is assigned to.

_embedded.meshProjectGroupBindings[].targetRef.ownedByWorkspace

String

The identifier of the workspace which contains the project.

_embedded.meshProjectGroupBindings[].subject.name

String

The identifier of this user group.

_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.meshprojectgroupbinding.v3.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 986

{
  "_embedded" : {
    "meshProjectGroupBindings" : [ {
      "kind" : "meshProjectGroupBinding",
      "apiVersion" : "v3",
      "metadata" : {
        "name" : "878e182d-0b5d-4b12-b0e9-130658725906"
      },
      "roleRef" : {
        "name" : "Project User"
      },
      "targetRef" : {
        "name" : "test-project-1",
        "displayName" : "Test Project 1",
        "ownedByWorkspace" : "test-workspace"
      },
      "subject" : {
        "name" : "testgroup"
      },
      "_links" : {
        "self" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshprojectbindings/groupbindings/878e182d-0b5d-4b12-b0e9-130658725906"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojectbindings/groupbindings?workspaceIdentifier=test-workspace&projectIdentifier=test-project-1"
    }
  },
  "page" : {
    "size" : 1,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}
Get meshProjectGroupBinding

Get a single meshProjectGroupBinding.

Request Headers
Name Description

Accept

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

Example Request
GET /api/meshobjects/meshprojectbindings/groupbindings/878e182d-0b5d-4b12-b0e9-130658725906 HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshprojectgroupbinding.v3.hal+json
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshprojectbindings/groupbindings/878e182d-0b5d-4b12-b0e9-130658725906' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshprojectgroupbinding.v3.hal+json'
Response Fields
Path Type Description

apiVersion

String

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

metadata

Object

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

metadata.name

String

The meshProjectGroupBinding identifier as 'name' to uniquely identify the meshProjectGroupBinding.

roleRef.name

String

The name of the referenced role for this group.

targetRef.name

String

The identifier of the project the group is assigned to.

targetRef.displayName

String

The name of the project the group is assigned to.

targetRef.ownedByWorkspace

String

The identifier of the workspace which contains the project.

subject.name

String

The identifier of this user group.

_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-Type: application/vnd.meshcloud.api.meshprojectgroupbinding.v3.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 536

{
  "kind" : "meshProjectGroupBinding",
  "apiVersion" : "v3",
  "metadata" : {
    "name" : "878e182d-0b5d-4b12-b0e9-130658725906"
  },
  "roleRef" : {
    "name" : "Project User"
  },
  "targetRef" : {
    "name" : "test-project-1",
    "displayName" : "Test Project 1",
    "ownedByWorkspace" : "test-workspace"
  },
  "subject" : {
    "name" : "testgroup"
  },
  "_links" : {
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojectbindings/groupbindings/878e182d-0b5d-4b12-b0e9-130658725906"
    }
  }
}
Post meshProjectGroupBindings

This creates a new group binding and associates a user group together with a role to a project.

Request Headers
Name Description

Content-Type

meshApi is versioned and you should use application/vnd.meshcloud.api.meshprojectgroupbinding.v3.hal+json as a Content-Type header.

Accept

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

Request Body

The fields have the same meaning as the response fields.

{
  "apiVersion": "v3",
  "kind": "meshProjectGroupBinding",
  "metadata": {
    "name": "group-binding-name"
  },
  "targetRef": {
    "name": "test-project-1",
    "ownedByWorkspace": "test-workspace"
  },
  "roleRef": { "name": "Project Reader" },
  "subject": {
    "name" : "testgroup"
  }
}
Example Request
POST /api/meshobjects/meshprojectbindings/groupbindings HTTP/1.1
Content-Type: application/vnd.meshcloud.api.meshprojectgroupbinding.v3.hal+json;charset=UTF-8
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshprojectgroupbinding.v3.hal+json
Content-Length: 298
Host: mesh-backend-url

{
  "apiVersion": "v3",
  "kind": "meshProjectGroupBinding",
  "metadata": {
    "name": "group-binding-name"
  },
  "targetRef": {
    "name": "test-project-1",
    "ownedByWorkspace": "test-workspace"
  },
  "roleRef": { "name": "Project Reader" },
  "subject": {
    "name" : "testgroup"
  }
}
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshprojectbindings/groupbindings' -i -u 'valid_username:valid_password' -X POST \
    -H 'Content-Type: application/vnd.meshcloud.api.meshprojectgroupbinding.v3.hal+json;charset=UTF-8' \
    -H 'Accept: application/vnd.meshcloud.api.meshprojectgroupbinding.v3.hal+json' \
    -d '{
  "apiVersion": "v3",
  "kind": "meshProjectGroupBinding",
  "metadata": {
    "name": "group-binding-name"
  },
  "targetRef": {
    "name": "test-project-1",
    "ownedByWorkspace": "test-workspace"
  },
  "roleRef": { "name": "Project Reader" },
  "subject": {
    "name" : "testgroup"
  }
}  '
Response Fields
Path Type Description

apiVersion

String

Version of this object

roleRef.name

String

The name of the referenced role for this group.

targetRef.name

String

The identifier of the project the group should get assigned to.

targetRef.displayName

String

The name of the project the group should get assigned to.

targetRef.ownedByWorkspace

String

The identifier of the workspace which contains the project.

metadata.name

String

Name of this binding which later can be used to refer to it

subject.name

String

The identifier of the referenced group.

kind

String

Type of the returned meshObject

_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.meshprojectgroupbinding.v3.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 502

{
  "kind" : "meshProjectGroupBinding",
  "apiVersion" : "v3",
  "metadata" : {
    "name" : "group-binding-name"
  },
  "roleRef" : {
    "name" : "Project Reader"
  },
  "targetRef" : {
    "name" : "test-project-1",
    "displayName" : "Test Project 1",
    "ownedByWorkspace" : "test-workspace"
  },
  "subject" : {
    "name" : "testgroup"
  },
  "_links" : {
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojectbindings/groupbindings/group-binding-name"
    }
  }
}
Update meshProjectGroupBinding

An update is currently not possible. You must first delete an existing group binding and then re-create it with for example a changed role.

Delete meshProjectGroupBinding

Deleting a meshProjectGroupBinding removes the assignment of a group from a project and revokes their associated project role. This action effectively withdraws the permissions granted to the group within the cloud platforms linked to the project.

Request Headers

There are no special headers required.

Example Request
DELETE /api/meshobjects/meshprojectbindings/groupbindings/878e182d-0b5d-4b12-b0e9-130658725906 HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshprojectbindings/groupbindings/878e182d-0b5d-4b12-b0e9-130658725906' -i -u 'valid_username:valid_password' -X DELETE
Example Response

The response is just an empty HTTP 204.

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

meshWorkspaceUserBinding

A meshWorkspaceUserBinding is an assignment of users to a workspace with a specified workspace role. Please note that this endpoint can only be used with API users for now. Support for API keys will be added in the future.

List meshWorkspaceUserBindings

Provides a paged list of meshWorkspaceUserBindings.

Request Headers
Name Description

Accept

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

Request Parameters
Parameter Description

username

Filter for user bindings associated to the given user (optional)

workspaceRole

Filter for user bindings with the given workspace role (optional)

workspaceIdentifier

Filter for user bindings associated to the given workspace (optional)

Example Request
GET /api/meshobjects/meshworkspacebindings/userbindings?username=username1&workspaceRole=Workspace%20Manager&workspaceIdentifier=test-workspace HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshworkspaceuserbinding.v2.hal+json
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshworkspacebindings/userbindings?username=username1&workspaceRole=Workspace%20Manager&workspaceIdentifier=test-workspace' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshworkspaceuserbinding.v2.hal+json'
Response Fields
Path Type Description

_embedded.meshWorkspaceUserBindings[]

Array

List of meshWorkspaceUserBinding.

_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.meshworkspaceuserbinding.v2.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 941

{
  "_embedded" : {
    "meshWorkspaceUserBindings" : [ {
      "kind" : "meshWorkspaceUserBinding",
      "apiVersion" : "v2",
      "metadata" : {
        "name" : "user-binding-name"
      },
      "roleRef" : {
        "name" : "Workspace Manager"
      },
      "targetRef" : {
        "name" : "test-workspace",
        "displayName" : "test-workspace Workspace"
      },
      "subject" : {
        "name" : "username1"
      },
      "_links" : {
        "self" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshworkspacebindings/userbindings/user-binding-name"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshworkspacebindings/userbindings?username=username1&workspaceRole=Workspace%20Manager&workspaceIdentifier=test-workspace"
    }
  },
  "page" : {
    "size" : 50,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}
Get meshWorkspaceUserBinding

Get a single meshWorkspaceUserBinding.

Request Headers
Name Description

Accept

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

Example Request
GET /api/meshobjects/meshworkspacebindings/userbindings/user-binding-name HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshworkspaceuserbinding.v2.hal+json
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshworkspacebindings/userbindings/user-binding-name' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshworkspaceuserbinding.v2.hal+json'
Response Fields
Path Type Description

apiVersion

String

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

metadata

Object

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

metadata.name

String

The meshWorkspaceUserBinding identifier as 'name' to uniquely identify the meshWorkspaceUserBinding.

roleRef.name

String

The name of the referenced role for this user.

targetRef.name

String

The identifier of the workspace the user is assigned to.

targetRef.displayName

String

The name of the workspace the user is assigned to.

subject.name

String

The username of the referenced user.

_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-Type: application/vnd.meshcloud.api.meshworkspaceuserbinding.v2.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 472

{
  "kind" : "meshWorkspaceUserBinding",
  "apiVersion" : "v2",
  "metadata" : {
    "name" : "user-binding-name"
  },
  "roleRef" : {
    "name" : "Workspace Manager"
  },
  "targetRef" : {
    "name" : "test-workspace",
    "displayName" : "test-workspace Workspace"
  },
  "subject" : {
    "name" : "username1"
  },
  "_links" : {
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshworkspacebindings/userbindings/user-binding-name"
    }
  }
}
Post meshWorkspaceUserBinding

Creating a meshWorkspaceUserBinding assigns the user to a workspace with a specified workspace role.

Request Headers
Name Description

Content-Type

meshApi is versioned and you should use application/vnd.meshcloud.api.meshworkspaceuserbinding.v2.hal+json as a Content-Type header.

Accept

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

Request Body

The fields have the same meaning as the response fields.

{
  "apiVersion": "v2",
  "kind": "meshWorkspaceUserBinding",
  "metadata": {
    "name": "another-user-binding-name"
  },
  "targetRef": {
    "name": "test-workspace"
  },
  "roleRef": { "name": "Workspace Member" },
  "subject": {
    "name" : "username1"
  }
}
Example Request
POST /api/meshobjects/meshworkspacebindings/userbindings HTTP/1.1
Content-Type: application/vnd.meshcloud.api.meshworkspaceuserbinding.v2.hal+json;charset=UTF-8
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshworkspaceuserbinding.v2.hal+json
Content-Length: 266
Host: mesh-backend-url

{
  "apiVersion": "v2",
  "kind": "meshWorkspaceUserBinding",
  "metadata": {
    "name": "another-user-binding-name"
  },
  "targetRef": {
    "name": "test-workspace"
  },
  "roleRef": { "name": "Workspace Member" },
  "subject": {
    "name" : "username1"
  }
}
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshworkspacebindings/userbindings' -i -u 'valid_username:valid_password' -X POST \
    -H 'Content-Type: application/vnd.meshcloud.api.meshworkspaceuserbinding.v2.hal+json;charset=UTF-8' \
    -H 'Accept: application/vnd.meshcloud.api.meshworkspaceuserbinding.v2.hal+json' \
    -d '{
  "apiVersion": "v2",
  "kind": "meshWorkspaceUserBinding",
  "metadata": {
    "name": "another-user-binding-name"
  },
  "targetRef": {
    "name": "test-workspace"
  },
  "roleRef": { "name": "Workspace Member" },
  "subject": {
    "name" : "username1"
  }
}  '
Response Fields
Path Type Description

apiVersion

String

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

metadata

Object

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

metadata.name

String

The meshWorkspaceUserBinding identifier as 'name' to uniquely identify the meshWorkspaceUserBinding.

roleRef.name

String

The name of the referenced role for this user.

targetRef.name

String

The identifier of the workspace the user is assigned to.

targetRef.displayName

String

The name of the workspace the user is assigned to.

subject.name

String

The username of the referenced user.

_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-Type: application/vnd.meshcloud.api.meshworkspaceuserbinding.v2.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 487

{
  "kind" : "meshWorkspaceUserBinding",
  "apiVersion" : "v2",
  "metadata" : {
    "name" : "another-user-binding-name"
  },
  "roleRef" : {
    "name" : "Workspace Member"
  },
  "targetRef" : {
    "name" : "test-workspace",
    "displayName" : "test-workspace Workspace"
  },
  "subject" : {
    "name" : "username1"
  },
  "_links" : {
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshworkspacebindings/userbindings/another-user-binding-name"
    }
  }
}
Update meshWorkspaceUserBindings

An update is currently not possible. To change a user binding, you must first delete the existing binding and then re-create it, for example, with the updated role.

Delete meshWorkspaceUserBinding

Deleting a meshWorkspaceUserBinding removes the assignment of a user from a workspace and revokes their associated workspace role.

Request Headers

There are no special headers required.

Example Request
DELETE /api/meshobjects/meshworkspacebindings/userbindings/another-user-binding-name HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshworkspacebindings/userbindings/another-user-binding-name' -i -u 'valid_username:valid_password' -X DELETE
Example Response

The response is just an empty HTTP 204.

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

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: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 2091

{
  "_embedded" : {
    "meshTenants" : [ {
      "kind" : "meshTenant",
      "apiVersion" : "v3",
      "metadata" : {
        "ownedByProject" : "test-project",
        "ownedByWorkspace" : "test-workspace",
        "platformIdentifier" : "aws.aws-meshstack-dev",
        "deletedOn" : "2024-10-17T10:34:15.120135292Z",
        "assignedTags" : { },
        "tenantIdentifier" : "test-workspace.test-project.aws.aws-meshstack-dev"
      },
      "spec" : {
        "localId" : "413d4916-b484-4291-abf9-b3da4a96c5d9",
        "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.aws.aws-meshstack-dev"
        },
        "meshusers" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshusers?workspaceIdentifier=test-workspace&projectIdentifier=test-project&platformIdentifier=aws.aws-meshstack-dev"
        }
      }
    } ]
  },
  "_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.aws.aws-meshstack-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.aws.aws-meshstack-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.tenantIdentifier

String

The full identifier of this tenant, a concatenation of the workspace identifier, project identifier and platform identifier.

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: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 979

{
  "kind" : "meshTenant",
  "apiVersion" : "v3",
  "metadata" : {
    "ownedByProject" : "test-project",
    "ownedByWorkspace" : "test-workspace",
    "platformIdentifier" : "aws.aws-meshstack-dev",
    "deletedOn" : "2024-10-17T10:34:15.120135292Z",
    "assignedTags" : { },
    "tenantIdentifier" : "test-workspace.test-project.aws.aws-meshstack-dev"
  },
  "spec" : {
    "localId" : "413d4916-b484-4291-abf9-b3da4a96c5d9",
    "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.aws.aws-meshstack-dev"
    },
    "meshusers" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshusers?workspaceIdentifier=test-workspace&projectIdentifier=test-project&platformIdentifier=aws.aws-meshstack-dev"
    }
  }
}
Post meshTenant

Create a new meshTenant.

Request Headers
Name Description

Content-Type

meshApi is versioned and you should use application/vnd.meshcloud.api.meshtenant.v3.hal+json as a Content-Type header.

Accept

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

Example Request
POST /api/meshobjects/meshtenants HTTP/1.1
Content-Type: application/vnd.meshcloud.api.meshtenant.v3.hal+json;charset=UTF-8
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshtenant.v3.hal+json
Content-Length: 292
Host: mesh-backend-url

{
    "apiVersion": "v3",
    "kind": "meshTenant",
    "metadata": {
      "ownedByProject": "test-project",
      "ownedByWorkspace": "test-workspace",
      "platformIdentifier": "azure.meshcloud-azure-dev"
    },
    "spec": {
      "landingZoneIdentifier": "stage-dev"
    }
  }
}
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshtenants' -i -u 'valid_username:valid_password' -X POST \
    -H 'Content-Type: application/vnd.meshcloud.api.meshtenant.v3.hal+json;charset=UTF-8' \
    -H 'Accept: application/vnd.meshcloud.api.meshtenant.v3.hal+json' \
    -d '{
    "apiVersion": "v3",
    "kind": "meshTenant",
    "metadata": {
      "ownedByProject": "test-project",
      "ownedByWorkspace": "test-workspace",
      "platformIdentifier": "azure.meshcloud-azure-dev"
    },
    "spec": {
      "landingZoneIdentifier": "stage-dev"
    }
  }
} '
Request Fields
Path Type Description

apiVersion

String

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

metadata

Object

Fixed fields that help identify the Tenant.

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.platformIdentifier

String

The identifier of the platform the meshTenant belongs to.

spec

Object

All fields in this section describe the Tenant.

spec.landingZoneIdentifier

String

The identifier of the landing zone the meshTenant belongs to.

spec.localId

String

The localId (platform tenant id) assigned with this meshTenant. If it is set, meshStack will attempt to import an existing tenant instead of creating a new one.

Tenant Links
Relation Description

meshusers

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: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 768

{
  "kind" : "meshTenant",
  "apiVersion" : "v3",
  "metadata" : {
    "ownedByProject" : "test-project",
    "ownedByWorkspace" : "test-workspace",
    "platformIdentifier" : "azure.meshcloud-azure-dev",
    "assignedTags" : { },
    "tenantIdentifier" : "test-workspace.test-project.azure.meshcloud-azure-dev"
  },
  "spec" : {
    "landingZoneIdentifier" : "stage-dev",
    "quotas" : [ ]
  },
  "_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?workspaceIdentifier=test-workspace&projectIdentifier=test-project&platformIdentifier=azure.meshcloud-azure-dev"
    }
  }
}
Delete meshTenant

Submits an existing meshTenant for deletion. meshTenant deletion might involve manual action on operator side, so the meshTenant might not be immediately deleted but rather marked for deletion.

Example Request
DELETE /api/meshobjects/meshtenants/test-workspace.test-project.azure.meshcloud-azure-dev HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
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 DELETE
Example Response
HTTP/1.1 202 Accepted
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY

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: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 2947

{
  "_embedded" : {
    "meshBuildingBlocks" : [ {
      "kind" : "meshBuildingBlock",
      "apiVersion" : "v1",
      "metadata" : {
        "uuid" : "68ce5455-2a4a-4a4b-a324-6a6c18cab85a",
        "definitionUuid" : "b23cfb9a-6974-444f-9d33-62134a632373",
        "definitionVersion" : 1,
        "tenantIdentifier" : "my-workspace.my-project.my-platform.my-location",
        "forcePurge" : false,
        "createdOn" : "2024-10-16T10:34:00.604075845Z"
      },
      "spec" : {
        "displayName" : "parent block",
        "inputs" : [ ],
        "parentBuildingBlocks" : [ ]
      },
      "status" : {
        "status" : "SUCCEEDED",
        "outputs" : [ ]
      },
      "_links" : {
        "self" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshbuildingblocks/68ce5455-2a4a-4a4b-a324-6a6c18cab85a"
        },
        "meshtenant" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshtenants/my-workspace.my-project.my-platform.my-location"
        },
        "forcePurge" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshbuildingblocks/68ce5455-2a4a-4a4b-a324-6a6c18cab85a/purge"
        }
      }
    }, {
      "kind" : "meshBuildingBlock",
      "apiVersion" : "v1",
      "metadata" : {
        "uuid" : "5646eafe-5d56-43e5-84fe-329bb050d720",
        "definitionUuid" : "ef6aaf87-3f8c-477c-94f4-f3cf509728ca",
        "definitionVersion" : 1,
        "tenantIdentifier" : "my-workspace.my-project.my-platform.my-location",
        "forcePurge" : false,
        "createdOn" : "2024-10-16T10:34:00.659118831Z"
      },
      "spec" : {
        "displayName" : "child block",
        "inputs" : [ {
          "key" : "resourceName",
          "value" : "My Test Resource",
          "valueType" : "STRING"
        } ],
        "parentBuildingBlocks" : [ {
          "buildingBlockUuid" : "68ce5455-2a4a-4a4b-a324-6a6c18cab85a",
          "definitionUuid" : "b23cfb9a-6974-444f-9d33-62134a632373"
        } ]
      },
      "status" : {
        "status" : "SUCCEEDED",
        "outputs" : [ {
          "key" : "resourceId",
          "value" : "id-123",
          "valueType" : "STRING"
        } ]
      },
      "_links" : {
        "self" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshbuildingblocks/5646eafe-5d56-43e5-84fe-329bb050d720"
        },
        "meshtenant" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshtenants/my-workspace.my-project.my-platform.my-location"
        },
        "forcePurge" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshbuildingblocks/5646eafe-5d56-43e5-84fe-329bb050d720/purge"
        }
      }
    } ]
  },
  "_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/5646eafe-5d56-43e5-84fe-329bb050d720 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/5646eafe-5d56-43e5-84fe-329bb050d720' -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, OBJECT.

spec.parentBuildingBlocks[]

Array

List of parent building blocks, 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, OBJECT.

_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: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 1334

{
  "kind" : "meshBuildingBlock",
  "apiVersion" : "v1",
  "metadata" : {
    "uuid" : "5646eafe-5d56-43e5-84fe-329bb050d720",
    "definitionUuid" : "ef6aaf87-3f8c-477c-94f4-f3cf509728ca",
    "definitionVersion" : 1,
    "tenantIdentifier" : "my-workspace.my-project.my-platform.my-location",
    "forcePurge" : false,
    "createdOn" : "2024-10-16T10:34:00.659118831Z"
  },
  "spec" : {
    "displayName" : "child block",
    "inputs" : [ {
      "key" : "resourceName",
      "value" : "My Test Resource",
      "valueType" : "STRING"
    } ],
    "parentBuildingBlocks" : [ {
      "buildingBlockUuid" : "68ce5455-2a4a-4a4b-a324-6a6c18cab85a",
      "definitionUuid" : "b23cfb9a-6974-444f-9d33-62134a632373"
    } ]
  },
  "status" : {
    "status" : "SUCCEEDED",
    "outputs" : [ {
      "key" : "resourceId",
      "value" : "id-123",
      "valueType" : "STRING"
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshbuildingblocks/5646eafe-5d56-43e5-84fe-329bb050d720"
    },
    "meshtenant" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshtenants/my-workspace.my-project.my-platform.my-location"
    },
    "forcePurge" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshbuildingblocks/5646eafe-5d56-43e5-84fe-329bb050d720/purge"
    }
  }
}
Post meshBuildingBlock

Create a new meshBuildingBlock.

Request Headers
Name Description

Content-Type

meshApi is versioned and you should use application/vnd.meshcloud.api.meshbuildingblock.v1.hal+json as a Content-Type header.

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
POST /api/meshobjects/meshbuildingblocks HTTP/1.1
Content-Type: application/vnd.meshcloud.api.meshbuildingblock.v1.hal+json;charset=UTF-8
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshbuildingblock.v1.hal+json
Content-Length: 599
Host: mesh-backend-url

{
  "apiVersion" : "v1",
  "kind" : "meshBuildingBlock",
  "metadata" : {
    "definitionUuid" : "ef6aaf87-3f8c-477c-94f4-f3cf509728ca",
    "definitionVersion" : 1,
    "tenantIdentifier" : "my-workspace.my-project.my-platform.my-location"
  },
  "spec" : {
    "displayName" : "New BuildingBlock",
    "inputs" : [{
      "key": "resourceName",
      "value": "buildingBlock-for-docs",
      "valueType": "STRING"
    }],
    "parentBuildingBlocks" : [{
      "definitionUuid": "b23cfb9a-6974-444f-9d33-62134a632373",
      "buildingBlockUuid": "bc758d92-5642-4b10-8b28-91d1b8397503"
    }]
  }
}
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshbuildingblocks' -i -u 'valid_username:valid_password' -X POST \
    -H 'Content-Type: application/vnd.meshcloud.api.meshbuildingblock.v1.hal+json;charset=UTF-8' \
    -H 'Accept: application/vnd.meshcloud.api.meshbuildingblock.v1.hal+json' \
    -d '{
  "apiVersion" : "v1",
  "kind" : "meshBuildingBlock",
  "metadata" : {
    "definitionUuid" : "ef6aaf87-3f8c-477c-94f4-f3cf509728ca",
    "definitionVersion" : 1,
    "tenantIdentifier" : "my-workspace.my-project.my-platform.my-location"
  },
  "spec" : {
    "displayName" : "New BuildingBlock",
    "inputs" : [{
      "key": "resourceName",
      "value": "buildingBlock-for-docs",
      "valueType": "STRING"
    }],
    "parentBuildingBlocks" : [{
      "definitionUuid": "b23cfb9a-6974-444f-9d33-62134a632373",
      "buildingBlockUuid": "bc758d92-5642-4b10-8b28-91d1b8397503"
    }]
  }
} '
Request 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

Fixed fields that help 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.

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, OBJECT.

spec.parentBuildingBlocks[]

Array

List of parent building blocks, which are required for the Building Block. If none given, an empty list needs to be provided.

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.

Building Block Links
Relation Description

meshtenant

Link to fetch the related meshTenant.

forcePurge

Link to purge this meshBuildingBlock. This is not available for workspace scoped access.

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: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 1253

{
  "kind" : "meshBuildingBlock",
  "apiVersion" : "v1",
  "metadata" : {
    "uuid" : "b82d3d0f-b69a-4663-8ff7-29aeab639e82",
    "definitionUuid" : "ef6aaf87-3f8c-477c-94f4-f3cf509728ca",
    "definitionVersion" : 1,
    "tenantIdentifier" : "my-workspace.my-project.my-platform.my-location",
    "forcePurge" : false,
    "createdOn" : "2024-10-16T10:34:02.052163811Z"
  },
  "spec" : {
    "displayName" : "New BuildingBlock",
    "inputs" : [ {
      "key" : "resourceName",
      "value" : "buildingBlock-for-docs",
      "valueType" : "STRING"
    } ],
    "parentBuildingBlocks" : [ {
      "buildingBlockUuid" : "bc758d92-5642-4b10-8b28-91d1b8397503",
      "definitionUuid" : "b23cfb9a-6974-444f-9d33-62134a632373"
    } ]
  },
  "status" : {
    "status" : "PENDING",
    "outputs" : [ ]
  },
  "_links" : {
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshbuildingblocks/b82d3d0f-b69a-4663-8ff7-29aeab639e82"
    },
    "meshtenant" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshtenants/my-workspace.my-project.my-platform.my-location"
    },
    "forcePurge" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshbuildingblocks/b82d3d0f-b69a-4663-8ff7-29aeab639e82/purge"
    }
  }
}
Delete meshBuildingBlock

Remove an existing meshBuildingBlock. Depending on the deletion mode of the meshBuildingBlock’s version, the meshBuildingBlock will either be removed (including potential cloud resources) or purged (removed from meshStack only).

Example Request
DELETE /api/meshobjects/meshbuildingblocks/b82d3d0f-b69a-4663-8ff7-29aeab639e82 HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshbuildingblocks/b82d3d0f-b69a-4663-8ff7-29aeab639e82' -i -u 'valid_username:valid_password' -X DELETE
Example Response
HTTP/1.1 202 Accepted
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Purge meshBuildingBlock

With administration rights it is also possible to force the purging of a meshBuildingBlock. That way, the deletion mode of the meshBuildingBlock’s version is ignored and the meshBuildingBlock is deleted from meshStack.

Example Request
DELETE /api/meshobjects/meshbuildingblocks/b82d3d0f-b69a-4663-8ff7-29aeab639e82/purge HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshbuildingblocks/b82d3d0f-b69a-4663-8ff7-29aeab639e82/purge' -i -u 'valid_username:valid_password' -X DELETE
Example Response
HTTP/1.1 202 Accepted
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY

meshBuildingBlockRun (BETA)

Attention: This API is currently in BETA and subject to change.

Services which are called block runner are responsible for executing block runs. Those services use this API to execute and update the run status in meshStack. At the moment it is not possible to create and integrate a fully custom block runner, however you can use this API to send back status updates of individual block runs when you build an asynchronous building block (this is a building block which gets its execution handed over to an external system by the block runner). You need an API key with the permission to update building block runs. Please be aware that you can only update runs whose underlying building block definitions are owned by the workspace the API key is scoped to.

Register Sources and Steps

In order to return updates for a run to meshStack, you first need to register one or multiple steps and their resources of your run execution. It is up to you how many or how you organize your steps. You can however also just send step results back and the registration takes place on the fly, but in order to have a consistent display and ordering of steps, it is highly advised to pre-register steps and sources.

Request Headers
Name Description

Accept

meshApi is versioned and you should use application/vnd.meshcloud.api.meshbuildingblockrun.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 Body
{
  "source": {
    "id": "github",
    "externalRunId": "12345",
    "externalRunUrl": "https://github.com/meshcloud/example/actions/runs/12345678"
  },
  "steps": [{
    "id": "step1",
    "displayName": "Init",
    "status": "IN_PROGRESS"
  },
  {
    "id": "step2",
    "displayName": "Pipeline"
  }]
}
Example Request
POST /api/meshobjects/meshbuildingblockruns/b3116611-e08b-4b00-91c5-10365b25a6ef/status/source HTTP/1.1
Content-Type: application/vnd.meshcloud.api.meshbuildingblockrun.v1.hal+json;charset=UTF-8
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshbuildingblockrun.v1.hal+json
Content-Length: 308
Host: mesh-backend-url

{
  "source": {
    "id": "github",
    "externalRunId": "12345",
    "externalRunUrl": "https://github.com/meshcloud/example/actions/runs/12345678"
  },
  "steps": [{
    "id": "step1",
    "displayName": "Init",
    "status": "IN_PROGRESS"
  },
  {
    "id": "step2",
    "displayName": "Pipeline"
  }]
}
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshbuildingblockruns/b3116611-e08b-4b00-91c5-10365b25a6ef/status/source' -i -u 'valid_username:valid_password' -X POST \
    -H 'Content-Type: application/vnd.meshcloud.api.meshbuildingblockrun.v1.hal+json;charset=UTF-8' \
    -H 'Accept: application/vnd.meshcloud.api.meshbuildingblockrun.v1.hal+json' \
    -d '{
  "source": {
    "id": "github",
    "externalRunId": "12345",
    "externalRunUrl": "https://github.com/meshcloud/example/actions/runs/12345678"
  },
  "steps": [{
    "id": "step1",
    "displayName": "Init",
    "status": "IN_PROGRESS"
  },
  {
    "id": "step2",
    "displayName": "Pipeline"
  }]
}  '
Request Fields
Path Type Description

source.id

String

The ID of this source.

source.externalRunId

String

In case the external run is tracked by a different ID you can include it here

source.externalRunUrl

String

You can provide a clickable URL to a website with additional information about the external run.

steps[]

Array

Contains the steps for this source. It should not exceed more than 50 steps

steps[].id

String

The ID of this step.

steps[].displayName

String

The human readable display name of the step

steps[].status

String

The execution status of this step. Can be PENDING, IN_PROGRESS, SUCCEEDED or FAILED.

Update Sources and Steps

With this API you can update the step execution result. You can also provide the outputs of a building block run step, which will potentially be used as inputs of other dependent building blocks.

Request Headers
Name Description

Accept

meshApi is versioned and you should use application/vnd.meshcloud.api.meshbuildingblockrun.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 Body
{
  "status": "IN_PROGRESS",
  "summary": "A summary of the run.",
  "steps": [{
    "id": "step1",
    "status": "SUCCEEDED",
    "userMessage": "Step was successful.",
    "systemMessage": "Step was successful.",
    "outputs": {
      "outputName": {
        "value": "hello-world",
        "type": "STRING",
        "isSensitive": false
      }
    }
  },
  {
    "id": "step2",
    "status": "IN_PROGRESS"
  }]
}
Example Request
PATCH /api/meshobjects/meshbuildingblockruns/b3116611-e08b-4b00-91c5-10365b25a6ef/status/source/github HTTP/1.1
Content-Type: application/vnd.meshcloud.api.meshbuildingblockrun.v1.hal+json;charset=UTF-8
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshbuildingblockrun.v1.hal+json
Content-Length: 419
Host: mesh-backend-url

{
  "status": "IN_PROGRESS",
  "summary": "A summary of the run.",
  "steps": [{
    "id": "step1",
    "status": "SUCCEEDED",
    "userMessage": "Step was successful.",
    "systemMessage": "Step was successful.",
    "outputs": {
      "outputName": {
        "value": "hello-world",
        "type": "STRING",
        "isSensitive": false
      }
    }
  },
  {
    "id": "step2",
    "status": "IN_PROGRESS"
  }]
}
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshbuildingblockruns/b3116611-e08b-4b00-91c5-10365b25a6ef/status/source/github' -i -u 'valid_username:valid_password' -X PATCH \
    -H 'Content-Type: application/vnd.meshcloud.api.meshbuildingblockrun.v1.hal+json;charset=UTF-8' \
    -H 'Accept: application/vnd.meshcloud.api.meshbuildingblockrun.v1.hal+json' \
    -d '{
  "status": "IN_PROGRESS",
  "summary": "A summary of the run.",
  "steps": [{
    "id": "step1",
    "status": "SUCCEEDED",
    "userMessage": "Step was successful.",
    "systemMessage": "Step was successful.",
    "outputs": {
      "outputName": {
        "value": "hello-world",
        "type": "STRING",
        "isSensitive": false
      }
    }
  },
  {
    "id": "step2",
    "status": "IN_PROGRESS"
  }]
}  '
Request Fields
Path Type Description

status

String

The execution status of the building block as whole. Can be any of PENDING, IN_PROGRESS, SUCCEEDED or FAILED. (Optional)

summary

String

A short summary of the execution and its result. This is shown to the user. It should not exceed more than 300 characters. (Optional)

steps[]

Array

Can contain updates to the steps. (Optional)

steps[].id

String

The ID of the step which should get updates.

steps[].userMessage

String

A message which is displayed to the user. It should not exceed more than 500 characters. (Optional)

steps[].systemMessage

String

A message which is displayed only to the operators. It should not exceed more than 500 characters. (Optional)

steps[].outputs

Object

Contains any output this step has provided. (Optional)

steps[].outputs.outputName.value

Varies

The name of the input variable.

steps[].outputs.outputName.type

Varies

The type of the variable. It can be one of those

steps[].outputs.outputName.isSensitive

Varies

Flag if the variable content is sensitive and encrypted. The runner must decrypt this variable content first before it can be used. Information on how to do this will provided in the future.

steps[].status

String

The execution status of this step. Can be PENDING, IN_PROGRESS, SUCCEEDED or FAILED. (Optional)

Usable Output Types
  • STRING: A simple text output.

  • INTEGER: A numeric output.

  • BOOLEAN: A boolean flag

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=ezth6mpmdsv2&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=ezth6mpmdsv2&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: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 1999

{
  "_embedded" : {
    "meshPaymentMethods" : [ {
      "kind" : "meshPaymentMethod",
      "apiVersion" : "v2",
      "metadata" : {
        "name" : "test-payment-method-1",
        "ownedByWorkspace" : "ezth6mpmdsv2"
      },
      "spec" : {
        "displayName" : "Test Payment Method 1",
        "tags" : { },
        "amount" : 1000
      },
      "_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"
        }
      }
    }, {
      "kind" : "meshPaymentMethod",
      "apiVersion" : "v2",
      "metadata" : {
        "name" : "test-payment-method-2",
        "ownedByWorkspace" : "ezth6mpmdsv2"
      },
      "spec" : {
        "displayName" : "Test Payment Method 2",
        "tags" : { },
        "amount" : 1000
      },
      "_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=ezth6mpmdsv2&page=0&size=2"
    },
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods?workspaceIdentifier=ezth6mpmdsv2&page=0&size=2"
    },
    "next" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods?workspaceIdentifier=ezth6mpmdsv2&page=1&size=2"
    },
    "last" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods?workspaceIdentifier=ezth6mpmdsv2&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

Number

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: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 539

{
  "kind" : "meshPaymentMethod",
  "apiVersion" : "v2",
  "metadata" : {
    "name" : "test-payment-method-1",
    "ownedByWorkspace" : "ezth6mpmdsv2"
  },
  "spec" : {
    "displayName" : "Test Payment Method 1",
    "tags" : { },
    "amount" : 1000
  },
  "_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: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 1557

{
  "_embedded" : {
    "meshUsers" : [ {
      "kind" : "meshUser",
      "apiVersion" : "v2",
      "metadata" : {
        "name" : "john-doe"
      },
      "spec" : {
        "email" : "john-doe@example.com",
        "firstName" : "John",
        "lastName" : "Doe",
        "euid" : "9d27d7b9-1359-4e4e-8519-e8fa6ea0bbab",
        "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: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 579

{
  "kind" : "meshUser",
  "apiVersion" : "v2",
  "metadata" : {
    "name" : "john-doe"
  },
  "spec" : {
    "email" : "john-doe@example.com",
    "firstName" : "John",
    "lastName" : "Doe",
    "euid" : "9d27d7b9-1359-4e4e-8519-e8fa6ea0bbab",
    "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: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 1088

{
  "_embedded" : {
    "meshWorkspaceUserGroups" : [ {
      "kind" : "meshWorkspaceUserGroup",
      "apiVersion" : "v1",
      "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: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 678

{
  "kind" : "meshWorkspaceUserGroup",
  "apiVersion" : "v1",
  "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: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 1388

{
  "_embedded" : {
    "meshServiceInstances" : [ {
      "kind" : "meshServiceInstance",
      "apiVersion" : "v2",
      "metadata" : {
        "ownedByProject" : "ezth6mtdg10",
        "ownedByWorkspace" : "my-mobile-app-team",
        "marketplaceIdentifier" : "ezth6mtdg1",
        "instanceId" : "ezth6mtdg11"
      },
      "spec" : {
        "displayName" : "ezth6mtdg12",
        "serviceId" : "ezth6mtdg5",
        "planId" : "ezth6mtdg7",
        "creator" : "Unknown"
      },
      "_links" : {
        "self" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshserviceinstances/ezth6mtdg11"
        }
      }
    } ]
  },
  "_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
  }
}
Get meshServiceInstance

Get a single meshServiceInstance.

Request Headers
Name Description

Accept

meshApi is versioned and you should use application/vnd.meshcloud.api.meshserviceinstance.v2.hal+json as a Content-Type header.

Example Request
GET /api/meshobjects/meshserviceinstances/serviceInstanceId 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/serviceInstanceId' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshserviceinstance.v2.hal+json'
Response Fields
Path Type Description

apiVersion

String

Version of Service Instance 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

Metadata and more fields to identify the Service Instance.

metadata.ownedByWorkspace

String

The workspace that this Service Instance belongs to.

metadata.ownedByProject

String

The project that this Service Instance belongs to.

metadata.marketplaceIdentifier

String

The identifier of the marketplace that this Service Instance belongs to.

metadata.instanceId

String

The instance id this Service Instance should use.

spec

Object

Specifications for the Service Instance.

spec.displayName

String

The display name of the Service Instance.

spec.serviceId

String

The id of the service for the Service Instance

spec.planId

String

The id of the plan for this Service Instance

spec.creator

String

The creator’s username that creates this Service Instance

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: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 535

{
  "kind" : "meshServiceInstance",
  "apiVersion" : "v2",
  "metadata" : {
    "ownedByProject" : "ezth6smsids-1",
    "ownedByWorkspace" : "my-mobile-app-team",
    "marketplaceIdentifier" : "ezth6mtdg21",
    "instanceId" : "serviceInstanceId"
  },
  "spec" : {
    "displayName" : "New SI updated",
    "serviceId" : "ezth6mtdg25",
    "planId" : "ezth6mtdg27",
    "creator" : "Unknown"
  },
  "_links" : {
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshserviceinstances/serviceInstanceId"
    }
  }
}
Post meshServiceInstance

Create a new meshServiceInstance.

Request Headers
Name Description

Content-Type

meshApi is versioned and you should use application/vnd.meshcloud.api.meshserviceinstance.v2.hal+json as a Content-Type header.

Accept

meshApi is versioned and you should use application/vnd.meshcloud.api.meshserviceinstance.v2.hal+json as an Accept header.

Example Request
POST /api/meshobjects/meshserviceinstances HTTP/1.1
Content-Type: application/vnd.meshcloud.api.meshserviceinstance.v2.hal+json;charset=UTF-8
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshserviceinstance.v2.hal+json
Content-Length: 400
Host: mesh-backend-url

{
  "apiVersion" : "v2",
  "kind" : "meshServiceInstance",
  "metadata" : {
    "ownedByProject" : "ezth6smsids-1",
    "ownedByWorkspace" : "my-mobile-app-team",
    "marketplaceIdentifier" : "ezth6mtdg21",
    "instanceId" : "serviceInstanceId"
  },
  "spec" : {
    "displayName" : "New SI",
    "serviceId" : "ezth6mtdg25",
    "planId" : "ezth6mtdg27",
    "creator" : "admin@meshcloud.io"
  }
}
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshserviceinstances' -i -u 'valid_username:valid_password' -X POST \
    -H 'Content-Type: application/vnd.meshcloud.api.meshserviceinstance.v2.hal+json;charset=UTF-8' \
    -H 'Accept: application/vnd.meshcloud.api.meshserviceinstance.v2.hal+json' \
    -d '{
  "apiVersion" : "v2",
  "kind" : "meshServiceInstance",
  "metadata" : {
    "ownedByProject" : "ezth6smsids-1",
    "ownedByWorkspace" : "my-mobile-app-team",
    "marketplaceIdentifier" : "ezth6mtdg21",
    "instanceId" : "serviceInstanceId"
  },
  "spec" : {
    "displayName" : "New SI",
    "serviceId" : "ezth6mtdg25",
    "planId" : "ezth6mtdg27",
    "creator" : "admin@meshcloud.io"
  }
}'
Request Fields
Path Type Description

apiVersion

String

Version of Service Instance 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

Metadata and more fields to identify the Service Instance.

metadata.ownedByWorkspace

String

The workspace that this Service Instance belongs to.

metadata.ownedByProject

String

The project that this Service Instance belongs to.

metadata.marketplaceIdentifier

String

The identifier of the marketplace that this Service Instance belongs to.

metadata.instanceId

String

The instance id this Service Instance should use.

spec

Object

Specifications for the Service Instance.

spec.displayName

String

The display name of the Service Instance.

spec.serviceId

String

The id of the service for the Service Instance

spec.planId

String

The id of the plan for this Service Instance

spec.creator

String

The creator’s username that creates this Service Instance

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: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 527

{
  "kind" : "meshServiceInstance",
  "apiVersion" : "v2",
  "metadata" : {
    "ownedByProject" : "ezth6smsids-1",
    "ownedByWorkspace" : "my-mobile-app-team",
    "marketplaceIdentifier" : "ezth6mtdg21",
    "instanceId" : "serviceInstanceId"
  },
  "spec" : {
    "displayName" : "New SI",
    "serviceId" : "ezth6mtdg25",
    "planId" : "ezth6mtdg27",
    "creator" : "Unknown"
  },
  "_links" : {
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshserviceinstances/serviceInstanceId"
    }
  }
}
Put meshServiceInstance

Update an existing meshServiceInstance.

Request Headers
Name Description

Content-Type

meshApi is versioned and you should use application/vnd.meshcloud.api.meshserviceinstance.v2.hal+json as a Content-Type header.

Accept

meshApi is versioned and you should use application/vnd.meshcloud.api.meshserviceinstance.v2.hal+json as an Accept header.

Example Request
PUT /api/meshobjects/meshserviceinstances/serviceInstanceId HTTP/1.1
Content-Type: application/vnd.meshcloud.api.meshserviceinstance.v2.hal+json;charset=UTF-8
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshserviceinstance.v2.hal+json
Content-Length: 408
Host: mesh-backend-url

{
  "apiVersion" : "v2",
  "kind" : "meshServiceInstance",
  "metadata" : {
    "ownedByProject" : "ezth6smsids-1",
    "ownedByWorkspace" : "my-mobile-app-team",
    "marketplaceIdentifier" : "ezth6mtdg21",
    "instanceId" : "serviceInstanceId"
  },
  "spec" : {
    "displayName" : "New SI updated",
    "serviceId" : "ezth6mtdg25",
    "planId" : "ezth6mtdg27",
    "creator" : "admin@meshcloud.io"
  }
}
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshserviceinstances/serviceInstanceId' -i -u 'valid_username:valid_password' -X PUT \
    -H 'Content-Type: application/vnd.meshcloud.api.meshserviceinstance.v2.hal+json;charset=UTF-8' \
    -H 'Accept: application/vnd.meshcloud.api.meshserviceinstance.v2.hal+json' \
    -d '{
  "apiVersion" : "v2",
  "kind" : "meshServiceInstance",
  "metadata" : {
    "ownedByProject" : "ezth6smsids-1",
    "ownedByWorkspace" : "my-mobile-app-team",
    "marketplaceIdentifier" : "ezth6mtdg21",
    "instanceId" : "serviceInstanceId"
  },
  "spec" : {
    "displayName" : "New SI updated",
    "serviceId" : "ezth6mtdg25",
    "planId" : "ezth6mtdg27",
    "creator" : "admin@meshcloud.io"
  }
}'
Example Response
HTTP/1.1 202 Accepted
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Delete meshServiceInstance

Delete an existing meshServiceInstance.

Example Request
DELETE /api/meshobjects/meshserviceinstances/serviceInstanceId 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/serviceInstanceId' -i -u 'valid_username:valid_password' -X DELETE \
    -H 'Accept: application/vnd.meshcloud.api.meshserviceinstance.v2.hal+json'
Example Response
HTTP/1.1 202 Accepted
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY

meshTagDefinitions

A meshTagDefinition defines additional metadata (tags) attached to all meshObjects of a specific kind. The meshTagDefinition describes a schema for this metadata.

Note: Reading meshTagDefinitions does not require any special permissions. All API Keys and API Users set up via meshPanel have read access to meshTagDefinitions by default.

List meshTagDefinitions

Provides a paged list of all meshTagDefinitions defined by meshStack administrators.

Request Headers
Name Description

Accept

meshApi is versioned and you should use application/vnd.meshcloud.api.meshtagdefinition.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/meshtagdefinitions?page=0&size=2 HTTP/1.1
Authorization: Basic bm9fcmlnaHRzOm5vX3JpZ2h0cw==
Accept: application/vnd.meshcloud.api.meshtagdefinition.v1.hal+json
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshtagdefinitions?page=0&size=2' -i -u 'no_rights:no_rights' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshtagdefinition.v1.hal+json'
Response Fields
Path Type Description

_embedded

Object

Contains the actual content of the paged response.

_embedded.meshTagDefinitions[]

Array

List of meshTagDefinition.

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.meshtagdefinition.v1.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 2173

{
  "_embedded" : {
    "meshTagDefinitions" : [ {
      "kind" : "meshTagDefinition",
      "apiVersion" : "v1",
      "metadata" : {
        "name" : "meshWorkspace.costCenter"
      },
      "spec" : {
        "targetKind" : "meshWorkspace",
        "key" : "costCenter",
        "valueType" : {
          "string" : {
            "defaultValue" : "1001",
            "validationRegex" : "^\\d{4}$"
          }
        },
        "description" : "Must be exactly 4 digits.",
        "displayName" : "Cost Center",
        "sortOrder" : 9999,
        "mandatory" : true,
        "immutable" : false,
        "restricted" : false
      },
      "_links" : {
        "self" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshtagdefinitions/meshWorkspace.costCenter"
        }
      }
    }, {
      "kind" : "meshTagDefinition",
      "apiVersion" : "v1",
      "metadata" : {
        "name" : "meshWorkspace.workspaceOwner"
      },
      "spec" : {
        "targetKind" : "meshWorkspace",
        "key" : "workspaceOwner",
        "valueType" : {
          "string" : {
            "defaultValue" : "Anna Admin"
          }
        },
        "description" : "Person responsible for this workspace.",
        "displayName" : "Workspace Owner",
        "sortOrder" : 9999,
        "mandatory" : false,
        "immutable" : false,
        "restricted" : false,
        "replicationKey" : "owner"
      },
      "_links" : {
        "self" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshtagdefinitions/meshWorkspace.workspaceOwner"
        }
      }
    } ]
  },
  "_links" : {
    "first" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshtagdefinitions?page=0&size=2"
    },
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshtagdefinitions?page=0&size=2"
    },
    "next" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshtagdefinitions?page=1&size=2"
    },
    "last" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshtagdefinitions?page=1&size=2"
    }
  },
  "page" : {
    "size" : 2,
    "totalElements" : 3,
    "totalPages" : 2,
    "number" : 0
  }
}
Get meshTagDefinition

Get a single meshTagDefinition.

Request Headers
Name Description

Accept

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

apiVersion

String

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

metadata

Object

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

metadata.name

String

Must be of the form $targetKind.$key since tag definitions must be non-conflicting.

spec

Object

Specification for the meshTagDefinition.

_links

Object

Currently only contains the self link.

spec.key

String

The key of the tag.

spec.displayName

String

The display name of the tag.

spec.description

String

The detailed description of the tag.

spec.targetKind

String

The kind of meshObject this tag is defined for. At this moment only the following kinds are supported by meshStack: WORKSPACE, PROJECT, LANDING_ZONE, PAYMENT_METHOD, BUILDING_BLOCK_DEFINITION

spec.sortOrder

Number

The sort order for this tag when displayed in the UI. meshPanel sorts tags in ascending order.

spec.mandatory

Boolean

Indicates whether the tag is mandatory.

spec.immutable

Boolean

Indicates whether the tag value is not editable after initially set.

spec.restricted

Boolean

Indicates whether only admins can edit this tag.

spec.replicationKey

String

The key for this tag when replicated to cloud platforms. If null, replication is disabled.

spec.valueType

TagValueType

The TagValueType of the tag. Must define exactly one of the available types.

Response Fields - TagValueType Schema

This object describes the value type for a tag.

Path Type Description

string

Object

string, represented as JSON string

string.defaultValue

String

The default value of the tag.

string.validationRegex

String

The regex pattern that the tag value must match.

email

Object

email address, represented as JSON string

email.defaultValue

String

The default value of the tag.

email.validationRegex

String

The regex pattern that the tag value must match.

integer

Object

an integer, represented as a JSON number

integer.defaultValue

Number

The default value of the tag.

number

Object

a decimal number, represented a JSON number

number.defaultValue

Number

The default value of the tag.

singleSelect

Object

a string from a list of options, represented as a JSON string

singleSelect.options

Array

The allowed options for the tag as a string[]

singleSelect.defaultValue

String

The default value of the tag.

multiSelect

Object

one or multiple strings from a list of option, represented as a JSON array

multiSelect.options

Array

The allowed options for the tag as a string[]

multiSelect.defaultValue

Array

The default value of the tag.

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.meshtagdefinition.v1.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 650

{
  "kind" : "meshTagDefinition",
  "apiVersion" : "v1",
  "metadata" : {
    "name" : "meshWorkspace.costCenter"
  },
  "spec" : {
    "targetKind" : "meshWorkspace",
    "key" : "costCenter",
    "valueType" : {
      "string" : {
        "defaultValue" : "1001",
        "validationRegex" : "^\\d{4}$"
      }
    },
    "description" : "Must be exactly 4 digits.",
    "displayName" : "Cost Center",
    "sortOrder" : 9999,
    "mandatory" : true,
    "immutable" : false,
    "restricted" : false
  },
  "_links" : {
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshtagdefinitions/meshWorkspace.costCenter"
    }
  }
}

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: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 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 , INVALID_MESH_OBJECT

(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: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 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. The subjects array contains a list of users, where each name represents the username of an user assigned to the workspace.

apiVersion: v1
kind: meshWorkspaceUserBinding
roleRef:
  name: Workspace Manager
targetRef:
  name: my-mobile-app-team
subjects:
  - name: john-doe # Username of the user
  - name: jane-doe # Username of the user
{
  "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 subjects array contains a list of groups, where each name represents the group identifier of a group assigned to the workspace. 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 # Group Identifier
  - name: and-another-user-group # Group Identifier
{
  "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: v3
kind: meshProjectUserBinding
metadata:
  name: user-binding-name
roleRef:
  name: Project Admin
targetRef:
  name: mobile-app-prod
  ownedByWorkspace: my-mobile-app-team
subject:
  name: jane-doe
{
  "apiVersion": "v3",
  "kind": "meshProjectUserBinding",
  "metadata": {
    "name": "user-binding-name"
  },
  "roleRef": {
    "name": "Project Admin"
  },
  "targetRef": {
    "name": "mobile-app-prod",
    "ownedByWorkspace": "my-mobile-app-team"
  },
  "subject": {
    "name": "jane-doe"
  }
}
meshProjectGroupBinding
apiVersion: v3
kind: meshProjectGroupBinding
metadata:
  name: group-binding-name
roleRef:
  name: Project Employee
targetRef:
  name: mobile-app-prod
  ownedByWorkspace: my-mobile-app-team
subject:
  name: my-user-group
{
  "apiVersion": "v3",
  "kind": "meshProjectGroupBinding",
  "metadata": {
    "name": "group-binding-name"
  },
  "roleRef": {
    "name": "Project Employee"
  },
  "targetRef": {
    "name": "mobile-app-prod",
    "ownedByWorkspace": "my-mobile-app-team"
  },
  "subject": {
    "name": "my-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 meshWorkspace 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: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY

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: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Example Error Response
HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 162

{
  "message" : "MeshObjectCollection not-empty-collection cannot be deleted, because it is not empty",
  "errorCode" : "BadRequest",
  "errorId" : "oOuXU1R5X2"
}

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: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 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: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 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" ]
  }
}