Technical Specifications

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 replace an existing resource as a whole, or to create it under a key you choose
DELETE	Used to delete an existing resource

Whether PUT can create a meshObject depends on how the meshObject is identified:

• By a key you choose, such as metadata.name for a workspace or a tag definition: PUT creates the meshObject if it does not exist and answers 201 Created. If it exists, PUT updates it and answers 200 OK.
• By a UUID, such as metadata.uuid for a platform or a building block definition: meshStack always generates the UUID. Create the meshObject with POST, and take its UUID from the response. PUT only updates it and answers 404 Not Found for an unknown UUID.

Each endpoint page shows its path key and whether it can answer 201 Created.

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.
202 Accepted	meshStack accepted the request and finishes it in the background, for example a deletion.
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 request has no valid authentication. Check your token or credentials. A token is short-lived, so get a new one when it has expired.
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.
406 Not Acceptable	The Accept header names no media type of this endpoint, or a version that is no longer supported.
409 Conflict	The request conflicts with the current state, for example an object with the same name already exists, or the object is still in use. The message names the conflict.
415 Unsupported Media Type	The Content-Type header names no media type that this endpoint accepts.
422 Unprocessable Entity	meshStack understands the request but cannot process it. The message names the reason.

Errors

An error response has the media type application/json and a CustomErrorMessage body with an errorCode, a message and an errorId, and, for an outdated client such as the meshStack CLI or the Terraform provider, a clientVersionHint. A 400 Bad Request message names the invalid path variable, query parameter or body field. It names a body field by its JSON path, for example:

{
  "errorCode": "HttpMessageNotReadable",
  "message": "Invalid value 'not-a-uuid' for field spec.parentBuildingBlocks[0].buildingBlockUuid: it must be a UUID",
  "errorId": "Kq7wZ3xRbN"
}

When you contact support about an error, give them the errorId.

Data Types

• Dates are usually handled as UTC dates and formatted to ISO 8601 standard (for example 2020-12-22T09:37:43Z or 2020-12-22T09:37:43.071Z). A few endpoints use a shorter date format. Please check the per-endpoint documentation for more details.
• 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.

Follow the links in a response to get from one resource to the next. When you build a URI, each endpoint page shows which value goes into each path variable, for example :uuid for metadata.uuid or :workspace.project for <workspace>.<project>.

Notice that HAL hrefs can be templated. For example, the _links object may include an entry like the following:

{
  "_links": {
    "meshapikeys": {
      "href": "https://example.meshstack.io/api/meshobjects/meshapikeys{?ownedByWorkspace}",
      "templated": true
    }
  }
}

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

Versioning

meshStack's meshObject API uses custom media types in the Accept and Content-Type headers for versioning.

Note meshObject API versions each resource like meshWorkspace or meshProject individually. This means you need to specify the specific media type corresponding to the endpoint you are calling.

For example, when meshStack introduces a new version of the meshWorkspace resource, this has no effect on other resources like the meshProject. This allows the API to evolve in a granular way.

API clients must always set an Accept header with the explicitly versioned resource media type. meshObject API will reject requests without an Accept header using a 406 Not Acceptable status code. Each endpoint page has a version picker that shows the media type of the selected version. You can open a page at a version with ?version=v2 in its URL. For example, this is the media type required to access the v1 version of a meshWorkspace resource:

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

Requests that need to send a body like POST or PUT must also set the Content-Type header with the correct media type. For example, this is the media type required to POST a meshProject:

Content-Type: application/vnd.meshcloud.api.meshproject.v2.hal+json

If a request has a body and its Content-Type is not one the endpoint accepts, the endpoint answers 415 Unsupported Media Type. Each endpoint page lists the media types it accepts.

Preview APIs

We make preview APIs available to allow customers to test and provide feedback on new features before they are generally available (GA). Preview APIs are marked with a -preview suffix in the media type, for example: application/vnd.meshcloud.api.meshbuildingblock.v2-preview.hal+json.

Preview APIs Limitations

Endpoints marked as preview (-preview suffix in the media type) are not generally available (GA) and carry the following implications:

• Breaking changes without notice: We may introduce incompatible changes at any time and without prior notice. Customers using preview APIs must be prepared to stay up to date with meshStack release notes and adjust their integrations accordingly.
• Bugs are possible: Preview APIs are still under active development — some rough edges and bugs should be expected.
• Not covered by SLA: Use of preview APIs is not covered by our service level agreement (SLA). We provide support for preview APIs on a best-effort basis only.

Media type changes at GA: When a preview version of the meshStack API becomes generally available, requests with its -preview media type and apiVersion keep working. Responses carry the version without -preview. Switch to the media type and apiVersion without -preview.

You are welcome to explore preview APIs for non-production use cases and we appreciate you providing us feedback on any issues you encounter with them.

Deprecation Policy

As we introduce new features and enhance existing functionalities, some API endpoints may become obsolete or outdated. Deprecating old endpoints is important to ensure the health and maintainability of the API.

Explicit versioning provides API clients time to transition to newer versions of endpoints in a controlled manner.

Deprecation follows a phased approach:

• outdated: As soon as a newer generally available version exists, the old version is outdated but keeps working. API clients are advised to migrate to newer versions at their earliest convenience.
• deprecated: We have announced an end-of-life (EoL) date. The endpoint works until that date. Move to a newer version before then.
• retired: After the EoL date, we can remove the endpoint at any time. A removed endpoint answers 406, 415 or 404.

Please refer to the Deprecated Resources section for a list of deprecated and outdated endpoints.

The OpenAPI specification states the lifecycle of each media type in x-meshstack-lifecycle, so tools can find deprecated versions. Its state is Preview, GA, Outdated or Deprecated. The retired endpoints are listed in x-meshstack-retired-endpoints.

Rate Limiting

meshStack APIs are designed to handle a large volume of requests while maintaining optimal performance.

To ensure optimal performance and avoid rate limits in your meshStack instance, please follow these best practices:

• Use responsible pagination to limit the number of results returned in each response. This reduces the amount of data that needs to be transferred and processed.
• Apply filters to limit the number of data requested to your specific use case.
• The API may enforce rate limits and respond to requests with HTTP 429 (Too Many Requests). To prevent running into rate limits, clients are advised to process only a single request at a time per API key.

By adhering to these best practices, you can ensure that the API can handle your requests efficiently. If you have any questions or concerns about API performance, please contact the support team for assistance.

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 number of elements on one page (default 50, at most 350). A larger value is lowered to 350.

Responses are structured like the following snippet:

{
    "_embedded": {
        "meshWorkspaces": [ ]
    },
    "_links": {
        "self" : {
          "href" : "https://example.meshstack.io/api/meshobjects/meshworkspaces"
        },
        "first" : {
          "href" : "https://example.meshstack.io/api/meshobjects/meshworkspaces?page=0&size=50"
        },
        "next" : {
          "href" : "https://example.meshstack.io/api/meshobjects/meshworkspaces?page=1&size=50"
        },
        "last" : {
          "href" : "https://example.meshstack.io/api/meshobjects/meshworkspaces?page=1&size=50"
        }
    },
    "page": {
        "size": 50,
        "totalElements": 64,
        "totalPages": 2,
        "number": 0
    }
}

The above example is taken from the meshWorkspace list endpoint. All relevant paging information is provided in the page element. In addition, links to the first, next (if exists), previous (if exists), and last page are provided. Pagination links are only provided if there is more than one page available for the given pagination parameters. _embedded always contains the list, which is empty when nothing matches.

Sorting

List endpoints take sort=<key>,asc or sort=<key>,desc; repeat it to sort by several keys. Each endpoint page lists its sort keys and its default order, which is the creation order on most endpoints. An unknown sort key gives 400 Bad Request. The order is stable, so going through all pages returns each element exactly once.

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 the form of a list, regardless of the number of values present.

An example could look like this:

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