gchq · patchwork01 · Apr 14, 2026 · Mar 5, 2026 · Mar 10, 2026 · Mar 10, 2026
diff --git a/.github/config/chunks.yaml b/.github/config/chunks.yaml
@@ -9,6 +9,7 @@ chunks:
       - deployment/cdk-custom-resources
       - deployment/cdk-environment
       - deployment/build-uptime-lambda
+      - rest-api
       - system-test/system-test-cdk
       - system-test/system-test-configuration
       - system-test/system-test-data-generation

diff --git a/.github/workflows/chunk-clients-cdk.yaml b/.github/workflows/chunk-clients-cdk.yaml
@@ -17,6 +17,7 @@ on:
       - 'java/deployment/cdk-custom-resources/**'
       - 'java/deployment/cdk-environment/**'
       - 'java/deployment/build-uptime-lambda/**'
+      - 'java/rest-api/**'
       - 'java/system-test/system-test-cdk/**'
       - 'java/system-test/system-test-configuration/**'
       - 'java/system-test/system-test-data-generation/**'

diff --git a/docs/deployment/docker-images.md b/docs/deployment/docker-images.md
@@ -64,6 +64,7 @@ Docker image for each lambda jar.
 | cdk-custom-resources-`<version-number>`.jar         | custom-resources-lambda           | false                |
 | metrics-`<version-number>`.jar                      | metrics-lambda                    | false                |
 | statestore-lambda-`<version-number>`.jar            | statestore-lambda                 | false                |
+| rest-api-`<version-number>`.jar                     | rest-api-lambda                   | false                |
 
 
 ## Building and pushing

diff --git a/docs/usage/properties/instance/cdk/common.md b/docs/usage/properties/instance/cdk/common.md
@@ -39,3 +39,4 @@ The following instance properties are commonly used throughout Sleeper.
 | sleeper.statestore.committer.dlq.arn                             | The ARN of the dead letter queue for statestore commit requests.                                                                                                           |
 | sleeper.statestore.committer.log.group                           | The name of the log group for the state store committer.                                                                                                                   |
 | sleeper.statestore.committer.event.source.id                     | The UUID of the event source mapping for the state store committer.                                                                                                        |
+| sleeper.rest.api.url                                             | The URL for the Sleeper REST API.                                                                                                                                          |
diff --git a/docs/usage/properties/instance/user/common.md b/docs/usage/properties/instance/user/common.md
@@ -15,7 +15,7 @@ The following instance properties are commonly used throughout Sleeper.
 | sleeper.retain.logs.after.destroy           | Whether to keep the sleeper log groups when the instance is destroyed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | true                                                                                                                                                                                 | true                        |
 | sleeper.default.table.retain.after.removal  | This property is used when applying an instance configuration and a table has been removed.<br>If this is true (default), removing the table from the configuration will just take the table offline.<br>If this is false, it will delete all data associated with the table when the table is removed.<br>Be aware that if a table is renamed in the configuration, the CDK will see it as a delete of the old table name and a create of the new table name. If this is set to false when that happens it will remove the table's data.<br>This property isn't currently in use but will be in https://github.com/gchq/sleeper/issues/5870.                                                               | true                                                                                                                                                                                 | false                       |
 | sleeper.default.table.reuse.existing        | This property is used when applying an instance configuration and a table has been added.<br>By default, or if this property is false, when a table is added to an instance configuration it's created in the instance. If it already exists the update will fail.<br>If this property is true, the existing table will be reused and imported as part of the instance configuration. If it doesn't exist the update will fail.                                                                                                                                                                                                                                                                             | false                                                                                                                                                                                | false                       |
-| sleeper.optional.stacks                     | The optional stacks to deploy. Not case sensitive.<br>Valid values: [IngestStack, IngestBatcherStack, EmrServerlessBulkImportStack, EmrBulkImportStack, PersistentEmrBulkImportStack, EksBulkImportStack, EmrStudioStack, BulkExportStack, QueryStack, WebSocketQueryStack, AthenaStack, KeepLambdaWarmStack, CompactionStack, GarbageCollectorStack, PartitionSplittingStack, DashboardStack, TableMetricsStack]                                                                                                                                                                                                                                                                                           | IngestStack,IngestBatcherStack,EmrServerlessBulkImportStack,EmrStudioStack,QueryStack,CompactionStack,GarbageCollectorStack,PartitionSplittingStack,DashboardStack,TableMetricsStack | true                        |
+| sleeper.optional.stacks                     | The optional stacks to deploy. Not case sensitive.<br>Valid values: [IngestStack, IngestBatcherStack, EmrServerlessBulkImportStack, EmrBulkImportStack, PersistentEmrBulkImportStack, EksBulkImportStack, EmrStudioStack, BulkExportStack, QueryStack, WebSocketQueryStack, AthenaStack, KeepLambdaWarmStack, CompactionStack, GarbageCollectorStack, PartitionSplittingStack, RestApiStack, DashboardStack, TableMetricsStack]                                                                                                                                                                                                                                                                             | IngestStack,IngestBatcherStack,EmrServerlessBulkImportStack,EmrStudioStack,QueryStack,CompactionStack,GarbageCollectorStack,PartitionSplittingStack,DashboardStack,TableMetricsStack | true                        |
 | sleeper.lambda.deploy.type                  | The deployment type for AWS Lambda. Not case sensitive.<br>There are two types of Lambda deployments, jar and container.<br>If the size of the jar file is too large, it will always be deployed as a container.<br>Valid values: [jar, container]                                                                                                                                                                                                                                                                                                                                                                                                                                                          | jar                                                                                                                                                                                  | true                        |
 | sleeper.endpoint.url                        | The AWS endpoint URL. This should only be set for a non-standard service endpoint. Usually this is used to set the URL to LocalStack for a locally deployed instance.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |                                                                                                                                                                                      | false                       |
 | sleeper.vpc                                 | The id of the VPC to deploy to. This property may be passed as an argument during deployment. If using the Sleeper CDK app, you can set the context variable "vpc". If using your own CDK app, you can set this in SleeperInstanceProps under networking.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |                                                                                                                                                                                      | false                       |

diff --git a/example/basic/instance.properties b/example/basic/instance.properties
@@ -44,7 +44,7 @@ sleeper.id=basic-example
 # Valid values: [IngestStack, IngestBatcherStack, EmrServerlessBulkImportStack, EmrBulkImportStack,
 # PersistentEmrBulkImportStack, EksBulkImportStack, EmrStudioStack, BulkExportStack, QueryStack,
 # WebSocketQueryStack, AthenaStack, KeepLambdaWarmStack, CompactionStack, GarbageCollectorStack,
-# PartitionSplittingStack, DashboardStack, TableMetricsStack]
+# PartitionSplittingStack, RestApiStack, DashboardStack, TableMetricsStack]
 # (default value shown below, uncomment to set a value)
 # sleeper.optional.stacks=IngestStack,IngestBatcherStack,EmrServerlessBulkImportStack,EmrStudioStack,QueryStack,CompactionStack,GarbageCollectorStack,PartitionSplittingStack,DashboardStack,TableMetricsStack
 

diff --git a/example/full/instance.properties b/example/full/instance.properties
@@ -125,7 +125,7 @@ sleeper.logging.root.level=INFO
 # Valid values: [IngestStack, IngestBatcherStack, EmrServerlessBulkImportStack, EmrBulkImportStack,
 # PersistentEmrBulkImportStack, EksBulkImportStack, EmrStudioStack, BulkExportStack, QueryStack,
 # WebSocketQueryStack, AthenaStack, KeepLambdaWarmStack, CompactionStack, GarbageCollectorStack,
-# PartitionSplittingStack, DashboardStack, TableMetricsStack]
+# PartitionSplittingStack, RestApiStack, DashboardStack, TableMetricsStack]
 # (default value shown below, uncomment to set a value)
 # sleeper.optional.stacks=IngestStack,IngestBatcherStack,EmrServerlessBulkImportStack,EmrStudioStack,QueryStack,CompactionStack,GarbageCollectorStack,PartitionSplittingStack,DashboardStack,TableMetricsStack
 

diff --git a/java/core/src/main/java/sleeper/core/deploy/LambdaHandler.java b/java/core/src/main/java/sleeper/core/deploy/LambdaHandler.java
@@ -199,6 +199,10 @@ public class LambdaHandler {
             .jar(LambdaJar.STATESTORE)
             .handler("sleeper.statestore.lambda.transaction.TransactionLogFollowerLambda::handleRequest")
             .core().add();
+    public static final LambdaHandler REST_API_HANDLER = builder()
+            .jar(LambdaJar.REST_API)
+            .handler("sleeper.restapi.RestApiLambda::handleEvent")
+            .core().add();
 
     private final LambdaJar jar;
     private final String handler;

diff --git a/java/core/src/main/java/sleeper/core/deploy/LambdaJar.java b/java/core/src/main/java/sleeper/core/deploy/LambdaJar.java
@@ -99,6 +99,9 @@ public class LambdaJar {
     public static final LambdaJar STATESTORE = builder().filenameFormat("statestore-lambda-%s.jar")
             .imageName("statestore-lambda")
             .artifactId("statestore-lambda").add();
+    public static final LambdaJar REST_API = builder().filenameFormat("rest-api-%s.jar")
+            .imageName("rest-api-lambda")
+            .artifactId("rest-api").add();
 
     private final String filenameFormat;
     private final String imageName;

diff --git a/java/core/src/main/java/sleeper/core/properties/instance/CdkDefinedInstanceProperty.java b/java/core/src/main/java/sleeper/core/properties/instance/CdkDefinedInstanceProperty.java
@@ -781,6 +781,12 @@ static List<CdkDefinedInstanceProperty> getAllInGroup(PropertyGroup group) {
             .propertyGroup(InstancePropertyGroup.BULK_IMPORT)
             .build();
 
+    // REST API
+    CdkDefinedInstanceProperty REST_API_URL = Index.propertyBuilder("sleeper.rest.api.url")
+            .description("The URL for the Sleeper REST API.")
+            .propertyGroup(InstancePropertyGroup.COMMON)
+            .build();
+
     @Override
     default boolean isSetByCdk() {
         return true;

diff --git a/java/core/src/main/java/sleeper/core/properties/model/OptionalStack.java b/java/core/src/main/java/sleeper/core/properties/model/OptionalStack.java
@@ -51,6 +51,9 @@ public enum OptionalStack {
     GarbageCollectorStack,
     PartitionSplittingStack,
 
+    // Rest Api
+    RestApiStack,
+
     // Metrics
     DashboardStack,
     TableMetricsStack;

diff --git a/java/deployment/cdk/src/main/java/sleeper/cdk/stack/RestApiStack.java b/java/deployment/cdk/src/main/java/sleeper/cdk/stack/RestApiStack.java
@@ -0,0 +1,85 @@
+/*
+ * Copyright 2022-2026 Crown Copyright
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package sleeper.cdk.stack;
+
+import software.amazon.awscdk.CfnOutput;
+import software.amazon.awscdk.CfnOutputProps;
+import software.amazon.awscdk.Duration;
+import software.amazon.awscdk.NestedStack;
+import software.amazon.awscdk.aws_apigatewayv2_integrations.HttpLambdaIntegration;
+import software.amazon.awscdk.services.apigatewayv2.AddRoutesOptions;
+import software.amazon.awscdk.services.apigatewayv2.HttpApi;
+import software.amazon.awscdk.services.apigatewayv2.HttpMethod;
+import software.amazon.awscdk.services.lambda.IFunction;
+import software.constructs.Construct;
+
+import sleeper.cdk.artefacts.SleeperInstanceArtefacts;
+import sleeper.cdk.lambda.SleeperLambdaCode;
+import sleeper.cdk.stack.core.LoggingStack.LogGroupRef;
+import sleeper.cdk.util.Utils;
+import sleeper.core.deploy.LambdaHandler;
+import sleeper.core.properties.instance.CdkDefinedInstanceProperty;
+import sleeper.core.properties.instance.InstanceProperties;
+import sleeper.core.util.EnvironmentUtils;
+
+import java.util.List;
+import java.util.Map;
+
+import static sleeper.core.properties.instance.CommonProperty.ID;
+
+/**
+ * REST API for interacting with the Sleeper instance.
+ * Utilises API Gateway.
+ */
+public class RestApiStack extends NestedStack {
+
+    public RestApiStack(Construct scope, String id, InstanceProperties instanceProperties,
+            SleeperInstanceArtefacts artefacts, SleeperCoreStacks coreStacks) {
+        super(scope, id);
+        setUpRestApi(instanceProperties, artefacts, coreStacks);
+    }
+
+    private void setUpRestApi(InstanceProperties instanceProperties, SleeperInstanceArtefacts artefacts,
+            SleeperCoreStacks coreStacks) {
+        String instanceId = Utils.cleanInstanceId(instanceProperties.get(ID));
+        SleeperLambdaCode lambdaCode = artefacts.lambdaCodeAtScope(this);
+        Map<String, String> env = EnvironmentUtils.createDefaultEnvironment(instanceProperties);
+        String functionName = String.join("-", "sleeper", instanceId, "rest-api-handler");
+        IFunction lambda = lambdaCode.buildFunction(LambdaHandler.REST_API_HANDLER, "RestApiHandlerlambda", builder -> builder
+                .functionName(functionName)
+                .description("Implements a REST API for interacting with Sleeper")
+                .environment(env)
+                .memorySize(1024)
+                .logGroup(coreStacks.getLogGroup(LogGroupRef.REST_API_HANDLER))
+                .timeout(Duration.seconds(29)));
+
+        HttpApi restHttpApi = HttpApi.Builder.create(this, "RestApi")
+                .description("Sleeper REST API")
+                .apiName(lambda.getFunctionName())
+                .build();
+
+        HttpLambdaIntegration integration = HttpLambdaIntegration.Builder.create(instanceId, lambda).build();
+        restHttpApi.addRoutes(AddRoutesOptions.builder()
+                .path("/sleeper")
+                .methods(List.of(HttpMethod.GET))
+                .integration(integration).build());
+
+        new CfnOutput(this, "RestApiUrl", CfnOutputProps.builder()
+                .value(restHttpApi.getApiEndpoint())
+                .build());
+        instanceProperties.set(CdkDefinedInstanceProperty.REST_API_URL, restHttpApi.getApiEndpoint());
+    }
+}
diff --git a/java/deployment/cdk/src/main/java/sleeper/cdk/stack/SleeperOptionalStacks.java b/java/deployment/cdk/src/main/java/sleeper/cdk/stack/SleeperOptionalStacks.java
@@ -170,6 +170,11 @@ public static void create(
             new IngestBatcherStack(scope, "IngestBatcher", props, coreStacks, ingestStacks);
         }
 
+        // Stack to provide a Rest API for sleeper
+        if (optionalStacks.contains(OptionalStack.RestApiStack)) {
+            new RestApiStack(scope, "RestApi", instanceProperties, artefacts, coreStacks);
+        }
+
         if (optionalStacks.contains(OptionalStack.DashboardStack)) {
             new DashboardStack(scope, "Dashboard",
                     ingestStack,

diff --git a/java/deployment/cdk/src/main/java/sleeper/cdk/stack/core/LoggingStack.java b/java/deployment/cdk/src/main/java/sleeper/cdk/stack/core/LoggingStack.java
@@ -121,7 +121,8 @@ public enum LogGroupRef {
         QUERY_WEBSOCKET_HANDLER("query-websocket-handler"),
         QUERY_KEEP_WARM("query-keep-warm"),
         SIMPLE_ATHENA_HANDLER("Simple-athena-handler"),
-        ITERATOR_APPLYING_ATHENA_HANDLER("IteratorApplying-athena-handler");
+        ITERATOR_APPLYING_ATHENA_HANDLER("IteratorApplying-athena-handler"),
+        REST_API_HANDLER("rest-api-handler");
 
         private final String shortName;
         private final String prefix;

diff --git a/java/deployment/cdk/src/test/java/sleeper/cdk/artefacts/repositories.approved.json b/java/deployment/cdk/src/test/java/sleeper/cdk/artefacts/repositories.approved.json
@@ -342,6 +342,18 @@
           "UpdateReplacePolicy": "Delete",
           "DeletionPolicy": "Delete"
         },
+        "Repositoryrestapilambda2BEFC68A": {
+          "Type": "AWS::ECR::Repository",
+          "Properties": {
+            "EmptyOnDelete": true,
+            "LifecyclePolicy": {
+              "LifecyclePolicyText": "{\"rules\":[{\"rulePriority\":1,\"description\":\"Delete untagged images\",\"selection\":{\"tagStatus\":\"untagged\",\"countType\":\"sinceImagePushed\",\"countNumber\":1,\"countUnit\":\"days\"},\"action\":{\"type\":\"expire\"}},{\"rulePriority\":2,\"description\":\"Keep images for 365 days\",\"selection\":{\"tagStatus\":\"any\",\"countType\":\"sinceImagePushed\",\"countNumber\":365,\"countUnit\":\"days\"},\"action\":{\"type\":\"expire\"}}]}"
+            },
+            "RepositoryName": "test-deployment/rest-api-lambda"
+          },
+          "UpdateReplacePolicy": "Delete",
+          "DeletionPolicy": "Delete"
+        },
         "Repositoryingest2C547FF9": {
           "Type": "AWS::ECR::Repository",
           "Properties": {

diff --git a/java/deployment/cdk/src/test/java/sleeper/cdk/default-instance.approved.json b/java/deployment/cdk/src/test/java/sleeper/cdk/default-instance.approved.json
@@ -3283,6 +3283,25 @@
             ]
           }
         },
+        "restapihandler6C03CFA2": {
+          "Type": "AWS::Logs::LogGroup",
+          "DeletionPolicy": "Retain",
+          "UpdateReplacePolicy": "Retain",
+          "Properties": {
+            "RetentionInDays": 30,
+            "LogGroupName": "sleeper-test-instance-rest-api-handler",
+            "Tags": [
+              {
+                "Key": "DeploymentStack",
+                "Value": "Logging"
+              },
+              {
+                "Key": "InstanceID",
+                "Value": "test-instance"
+              }
+            ]
+          }
+        },
         "partitionsplittinghandler1B821F8F": {
           "Type": "AWS::Logs::LogGroup",
           "DeletionPolicy": "Retain",
@@ -26419,4 +26438,4 @@
       }
     }
   }
-}
+}