List Services belonging to a Project
Request
- projectIdstringrequired
ID of the Project to list Services for.
- stackIdstring (uuid)
ID of the Stack to list Services for.
- statusstring (einer von: running, stopped, error, creating, starting, stopping, unspecified)
Filters the list by the given status. The filter matches the stored status exactly, so it can differ from the
statusshown in the response:stoppingdoes not match containers that are being terminated (which are listed asstopping), andunspecifieddoes not filter at all. - requiresRecreateboolean
Filters the list depending on whether services requires recreate.
- searchTermstring
Search term to filter Services by. It matches exactly on a Service's
id,shortId,stackIdorprojectId, or case-insensitively as a substring of itsserviceName,messageordescription. - sortOrderstring (einer von: descriptionAsc, descriptionDesc)
Sorts the list with given order.
- limitinteger (≥ 0)
The max count of resources to return in the list response.
- skipinteger
Number of items to skip. Should be multiple of
limit. - pageinteger (≥ 0)
Page to display.
skipandpageend up doing the same. If bothpageandskipare set, skip is used.
Responses
- X-Pagination-Limitinteger
The limit used to select the resources for the response
- X-Pagination-Skipinteger
The number of skipped items
- X-Pagination-Pagenumber
The calculate page of the list response. Refer to parameters to learn more.
- X-Pagination-TotalCountinteger
The total amount of items available in the remote ressource. Use this value in combination with the limit to calculate the available pages.
OK
- Array[
- *object
- deployobject
- resourcesobject
- limits
- cpusstring
CPU limit for the container. The value can be specified as a decimal number, where
1corresponds to one full CPU core. For example,0.5means that the container is limited to using half of a CPU core. - memorystring
Memory limit for the container, as an integer followed by a unit, similar to the byte values used by Docker Compose:
b(bytes),korkb(kilobytes),mormb(megabytes) andgorgb(gigabytes). Units must be lowercase and are decimal (1g= 1,000,000,000 bytes). A number without a unit is not accepted.
- deployedStateobjectrequired
The actual state of the container that is currently deployed.
- commandArray von string
The container command (equivalent to the Docker cmd). When omitted, this defaults to the command defined in the image.
- Array[
- *string
]
- entrypointArray von string
The container entrypoint (equivalent to the Docker entrypoint). When omitted, this defaults to the entrypoint defined in the image.
- Array[
- *string
]
- envsobject
Key-value map of environment variables that should be passed into the container.
- *string
- imagestringrequired
The image to run, in the usual format also used by
docker runanddocker compose. When the image is pulled from a private registry, make sure to create it first, using thecontainer-create-registryendpoint. The appropriate registry is matched by hostname. - imageDigeststring
The digest of the image that is currently deployed.
- portsArray von string
Exposed ports. Follows the format
<public-port>:<container-port>/<protocol>. Exposed ports can be accessed from other containers (or managed apps) within the same project. To expose a port publicly, connect it with an ingress resource.- Array[
- *string
]
- volumesArray von string
Volume mounts for this container. These items always follow the format
<volume>:<mountpoint>. The<volume>may either be a named volume, or a file path in the (always present) project file system (which is shared among containers and managed apps within a project).- Array[
- *string
]
- descriptionstringrequired
- idstring (uuid)required
- messagestring
Message explaining the current state of the container. This may contain information about the current state of the container, or errors that occurred during deployment.
- pendingStateobjectrequired
The desired state that is waiting to be reconciled.
- commandArray von string
The container command (equivalent to the Docker cmd). When omitted, this defaults to the command defined in the image.
- Array[
- *string
]
- entrypointArray von string
The container entrypoint (equivalent to the Docker entrypoint). When omitted, this defaults to the entrypoint defined in the image.
- Array[
- *string
]
- envsobject
Key-value map of environment variables that should be passed into the container.
- *string
- imagestringrequired
The image to run, in the usual format also used by
docker runanddocker compose. When the image is pulled from a private registry, make sure to create it first, using thecontainer-create-registryendpoint. The appropriate registry is matched by hostname. - imageDigeststring
The digest of the image that is currently deployed.
- portsArray von string
Exposed ports. Follows the format
<public-port>:<container-port>/<protocol>. Exposed ports can be accessed from other containers (or managed apps) within the same project. To expose a port publicly, connect it with an ingress resource.- Array[
- *string
]
- volumesArray von string
Volume mounts for this container. These items always follow the format
<volume>:<mountpoint>. The<volume>may either be a named volume, or a file path in the (always present) project file system (which is shared among containers and managed apps within a project).- Array[
- *string
]
- requiresRecreatebooleanrequired
- restartPolicystring (einer von: no, always, on-failure, unless-stopped)
Restart policy of the container.
unless-stoppedcurrently behaves likeon-failure. - serviceNamestringrequired
- shortIdstringrequired
A short ID of the container. This is a unique identifier for the container within the project, and can be used to reference it in other API calls, or for SSH connections.
- statusstring (einer von: running, stopped, error, creating, starting, stopping, unspecified)required
Status of a Service.
creating: the Service was declared and has not reported a status yet.starting: the container is being started.running: the container is ready.stopping: the container is being stopped or terminated.stopped: the container was stopped or has exited.error: the container or its image is in an error state; see the Service'smessagefor details.unspecified: the cluster currently reports no decisive condition for the container. - statusSetAtstring (date-time)required
- templateIdstring
ID of the template used to create this service, if one was used.
]
Content-Type: application/json
[
{
"deploy": {
"resources": {
"limits": {
"cpus": "0.5",
"memory": "1gb"
}
}
},
"deployedState": {
"command": [
"mysqld",
"mysqld"
],
"entrypoint": [
"docker-entrypoint.sh",
"docker-entrypoint.sh"
],
"envs": {
"MYSQL_DATABASE": "my_db",
"MYSQL_PASSWORD": "my_password",
"MYSQL_ROOT_PASSWORD": "my_root_password",
"MYSQL_USER": "my_user"
},
"image": "mysql:8.0",
"imageDigest": "string",
"ports": [
"3306/tcp",
"3306:3306/tcp"
],
"volumes": [
"data:/var/lib/mysql",
"/home/p-XXXXX/html:/var/www",
"data:/var/lib/mysql",
"/home/p-XXXXX/html:/var/www"
]
},
"description": "MySQL DB",
"id": "f0f86186-0a5a-45b2-aa33-502777496347",
"message": "Container ready",
"pendingState": {
"command": [
"mysqld",
"mysqld"
],
"entrypoint": [
"docker-entrypoint.sh",
"docker-entrypoint.sh"
],
"envs": {
"MYSQL_DATABASE": "my_db",
"MYSQL_PASSWORD": "my_password",
"MYSQL_ROOT_PASSWORD": "my_root_password",
"MYSQL_USER": "my_user"
},
"image": "mysql:8.0",
"imageDigest": "string",
"ports": [
"3306/tcp",
"3306:3306/tcp"
],
"volumes": [
"data:/var/lib/mysql",
"/home/p-XXXXX/html:/var/www",
"data:/var/lib/mysql",
"/home/p-XXXXX/html:/var/www"
]
},
"requiresRecreate": true,
"restartPolicy": "always",
"serviceName": "mysql-db",
"shortId": "c-XXXXXX",
"status": "running",
"statusSetAt": "1985-10-26T01:21:00.000Z",
"templateId": "string"
}
]
{
"items": {
"properties": {
"deploy": {
"properties": {
"resources": {
"properties": {
"limits": {
"properties": {
"cpus": {
"description": "CPU limit for the container. The value can be specified as a decimal number, where `1` corresponds to\none full CPU core. For example, `0.5` means that the container is limited to using half of a CPU core.\n",
"example": "0.5",
"type": "string"
},
"memory": {
"description": "Memory limit for the container, as an integer followed by a unit, similar to the [byte values used by Docker Compose](https://docs.docker.com/reference/compose-file/extension/#specifying-byte-values): `b` (bytes), `k` or `kb` (kilobytes), `m` or `mb` (megabytes) and `g` or `gb` (gigabytes). Units must be lowercase and are decimal (`1g` = 1,000,000,000 bytes). A number without a unit is not accepted.\n",
"example": "1gb",
"type": "string"
}
}
}
},
"type": "object"
}
},
"type": "object"
},
"deployedState": {
"description": "The actual state of the container that is currently deployed.\n",
"properties": {
"command": {
"description": "The container command (equivalent to the [Docker cmd](https://docs.docker.com/reference/dockerfile/#cmd)). When omitted, this defaults to the command defined in the image.\n",
"example": [
"mysqld",
"mysqld"
],
"items": {
"type": "string"
},
"type": "array"
},
"entrypoint": {
"description": "The container entrypoint (equivalent to the [Docker entrypoint](https://docs.docker.com/reference/dockerfile/#entrypoint)). When omitted, this defaults to the entrypoint defined in the image.\n",
"example": [
"docker-entrypoint.sh",
"docker-entrypoint.sh"
],
"items": {
"type": "string"
},
"type": "array"
},
"envs": {
"additionalProperties": {
"type": "string"
},
"description": "Key-value map of environment variables that should be passed into the container.\n",
"example": {
"MYSQL_DATABASE": "my_db",
"MYSQL_PASSWORD": "my_password",
"MYSQL_ROOT_PASSWORD": "my_root_password",
"MYSQL_USER": "my_user"
},
"type": "object"
},
"image": {
"description": "The image to run, in the usual format also used by `docker run` and `docker compose`. When the image is pulled from a private registry, make sure to create it first, using the `container-create-registry` endpoint. The appropriate registry is matched by hostname.\n",
"example": "mysql:8.0",
"type": "string"
},
"imageDigest": {
"description": "The digest of the image that is currently deployed.\n",
"type": "string"
},
"ports": {
"description": "Exposed ports. Follows the format `<public-port>:<container-port>/<protocol>`. Exposed ports can be accessed from other containers (or managed apps) within the same project. To expose a port publicly, connect it with an ingress resource.\n",
"example": [
"3306/tcp",
"3306:3306/tcp"
],
"items": {
"type": "string"
},
"type": "array"
},
"volumes": {
"description": "Volume mounts for this container. These items always follow the format `<volume>:<mountpoint>`. The `<volume>` may either be a named volume, or a file path in the (always present) project file system (which is shared among containers and managed apps within a project).\n",
"example": [
"data:/var/lib/mysql",
"/home/p-XXXXX/html:/var/www",
"data:/var/lib/mysql",
"/home/p-XXXXX/html:/var/www"
],
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"image"
],
"type": "object"
},
"description": {
"example": "MySQL DB",
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"message": {
"description": "Message explaining the current state of the container. This may contain information about the current state of the container, or errors that occurred during deployment.\n",
"example": "Container ready",
"type": "string"
},
"pendingState": {
"description": "The desired state that is waiting to be reconciled.\n",
"properties": {
"command": {
"description": "The container command (equivalent to the [Docker cmd](https://docs.docker.com/reference/dockerfile/#cmd)). When omitted, this defaults to the command defined in the image.\n",
"example": [
"mysqld",
"mysqld"
],
"items": {
"type": "string"
},
"type": "array"
},
"entrypoint": {
"description": "The container entrypoint (equivalent to the [Docker entrypoint](https://docs.docker.com/reference/dockerfile/#entrypoint)). When omitted, this defaults to the entrypoint defined in the image.\n",
"example": [
"docker-entrypoint.sh",
"docker-entrypoint.sh"
],
"items": {
"type": "string"
},
"type": "array"
},
"envs": {
"additionalProperties": {
"type": "string"
},
"description": "Key-value map of environment variables that should be passed into the container.\n",
"example": {
"MYSQL_DATABASE": "my_db",
"MYSQL_PASSWORD": "my_password",
"MYSQL_ROOT_PASSWORD": "my_root_password",
"MYSQL_USER": "my_user"
},
"type": "object"
},
"image": {
"description": "The image to run, in the usual format also used by `docker run` and `docker compose`. When the image is pulled from a private registry, make sure to create it first, using the `container-create-registry` endpoint. The appropriate registry is matched by hostname.\n",
"example": "mysql:8.0",
"type": "string"
},
"imageDigest": {
"description": "The digest of the image that is currently deployed.\n",
"type": "string"
},
"ports": {
"description": "Exposed ports. Follows the format `<public-port>:<container-port>/<protocol>`. Exposed ports can be accessed from other containers (or managed apps) within the same project. To expose a port publicly, connect it with an ingress resource.\n",
"example": [
"3306/tcp",
"3306:3306/tcp"
],
"items": {
"type": "string"
},
"type": "array"
},
"volumes": {
"description": "Volume mounts for this container. These items always follow the format `<volume>:<mountpoint>`. The `<volume>` may either be a named volume, or a file path in the (always present) project file system (which is shared among containers and managed apps within a project).\n",
"example": [
"data:/var/lib/mysql",
"/home/p-XXXXX/html:/var/www",
"data:/var/lib/mysql",
"/home/p-XXXXX/html:/var/www"
],
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"image"
],
"type": "object"
},
"requiresRecreate": {
"type": "boolean"
},
"restartPolicy": {
"description": "Restart policy of the container. `unless-stopped` currently behaves like `on-failure`.\n",
"enum": [
"no",
"always",
"on-failure",
"unless-stopped"
],
"example": "always",
"type": "string"
},
"serviceName": {
"example": "mysql-db",
"type": "string"
},
"shortId": {
"description": "A short ID of the container. This is a unique identifier for the container within the project, and can be used to reference it in other API calls, or for SSH connections.\n",
"example": "c-XXXXXX",
"type": "string"
},
"status": {
"description": "Status of a Service. `creating`: the Service was declared and has not reported a status yet. `starting`: the container is being started. `running`: the container is ready. `stopping`: the container is being stopped or terminated. `stopped`: the container was stopped or has exited. `error`: the container or its image is in an error state; see the Service's `message` for details. `unspecified`: the cluster currently reports no decisive condition for the container.\n",
"enum": [
"running",
"stopped",
"error",
"creating",
"starting",
"stopping",
"unspecified"
],
"type": "string"
},
"statusSetAt": {
"format": "date-time",
"type": "string"
},
"templateId": {
"description": "ID of the template used to create this service, if one was used.",
"type": "string"
}
},
"required": [
"id",
"stackId",
"projectId",
"description",
"serviceName",
"pendingState",
"deployedState",
"status",
"shortId",
"statusSetAt",
"requiresRecreate"
],
"type": "object"
},
"type": "array"
}
Validation Error caused by invalid input data in the request
- type"ValidationError"required
- messagestring
- validationErrorsArray von objectrequired
- Array[
- *object
- messagestringrequired
The standard error message
- pathstringrequired
The path to the part of the data that was validated. JavaScript property access notation (e.g., ".prop[1].subProp") is used.
- typestringrequired
ajv validation error type (e.g. "format", "required", "type") or own validation error types
- contextobject
The object with the additional information about the error that can be used to create custom error messages. Keys depend on the type that failed validation (e.g. "missingProperty" for type "required")
- *string
]
Content-Type: application/json
{
"type": "ValidationError",
"message": "Validation failed",
"validationErrors": [
{
"message": "should be string",
"path": ".address.street",
"type": "format",
"context": {
"format": "email"
}
}
]
}
{
"type": "object",
"required": [
"type",
"validationErrors"
],
"properties": {
"type": {
"type": "string",
"enum": [
"ValidationError"
]
},
"message": {
"type": "string",
"example": "Validation failed"
},
"validationErrors": {
"type": "array",
"items": {
"type": "object",
"required": [
"message",
"path",
"type"
],
"properties": {
"message": {
"type": "string",
"description": "The standard error message",
"example": "should be string"
},
"path": {
"type": "string",
"description": "The path to the part of the data that was validated. JavaScript property access notation (e.g., \".prop[1].subProp\") is used.\n",
"example": ".address.street"
},
"type": {
"type": "string",
"description": "ajv validation error type (e.g. \"format\", \"required\", \"type\") or own validation error types",
"example": "format"
},
"context": {
"type": "object",
"example": {
"format": "email"
},
"description": "The object with the additional information about the error that can be used to create custom error messages. Keys depend on the\ntype that failed validation (e.g. \"missingProperty\" for type \"required\")\n",
"additionalProperties": {
"type": "string"
}
}
}
}
}
}
}
An unexpected Error that occurred while handling the request
- messagestringrequired
- typestringrequired
Content-Type: application/json
{
"message": "Something went wrong",
"type": "InternalServerError"
}
{
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"message": {
"type": "string",
"example": "Something went wrong"
},
"type": {
"type": "string",
"example": "InternalServerError"
}
}
}
An unexpected Error that occurred while handling the request
- messagestringrequired
- typestringrequired
Content-Type: application/json
{
"message": "Something went wrong",
"type": "InternalServerError"
}
{
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"message": {
"type": "string",
"example": "Something went wrong"
},
"type": {
"type": "string",
"example": "InternalServerError"
}
}
}
Your request ran into a rate limit. You have to wait until rate limit expires
- messagestring
- typestring
Content-Type: application/json
{
"message": "too many requests",
"type": "RateLimitError"
}
{
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "too many requests"
},
"type": {
"type": "string",
"example": "RateLimitError"
}
}
}
An unexpected Error that occurred while handling the request
- messagestringrequired
- typestringrequired
Content-Type: application/json
{
"message": "Something went wrong",
"type": "InternalServerError"
}
{
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"message": {
"type": "string",
"example": "Something went wrong"
},
"type": {
"type": "string",
"example": "InternalServerError"
}
}
}
An unexpected Error that occurred while handling the request
- messagestringrequired
- typestringrequired
Content-Type: application/json
{
"message": "Something went wrong",
"type": "InternalServerError"
}
{
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"message": {
"type": "string",
"example": "Something went wrong"
},
"type": {
"type": "string",
"example": "InternalServerError"
}
}
}
Nutzungsbeispiele
$ curl \
--fail \
--location \
-H "Authorization: Bearer $MITTWALD_API_TOKEN" \
https://api.mittwald.de/v2/projects/string/services?stackId=f0f86186-0a5a-45b2-aa33-502777496347&status=running&requiresRecreate=true&searchTerm=string&sortOrder=descriptionAsc&limit=50&page=1
import { MittwaldAPIV2Client } from "@mittwald/api-client";
import { assertStatus } from "@mittwald/api-client-commons";
const client = MittwaldAPIClient.newWithToken(process.env.MITTWALD_API_TOKEN);
const response = await client.container.listServices({
"projectId": "string",
"queryParameters": {
"stackId": "f0f86186-0a5a-45b2-aa33-502777496347",
"status": "running",
"requiresRecreate": true,
"searchTerm": "string",
"sortOrder": "descriptionAsc",
"limit": 50,
"page": 1
}
});
assertStatus(response, 200);
use \Mittwald\ApiClient\Generated\V2\Clients\Container\ListServices\ListServicesRequest;
$client = MittwaldAPIClient::newWithToken(getenv('MITTWALD_API_TOKEN'));
$request = (new ListServicesRequest(
projectId: "string"
))
->withStackId("f0f86186-0a5a-45b2-aa33-502777496347")
->withStatus("running")
->withRequiresRecreate(true)
->withSearchTerm("string")
->withSortOrder("descriptionAsc")
->withLimit(50)
->withPage(1);
$response = $client->container()->listServices($request);
var_dump($response->getBody();