From 628f3d7173f37ac5d4b2c40d5b3c4f7f9e515125 Mon Sep 17 00:00:00 2001 From: Viren Nadkarni Date: Thu, 27 Jun 2024 14:16:36 +0530 Subject: [PATCH 1/6] Embed Swagger UI in internal endpoints page --- content/en/references/internal-endpoints.md | 47 +- static/openapi.json | 1501 +++++++++++++++++++ 2 files changed, 1507 insertions(+), 41 deletions(-) create mode 100644 static/openapi.json diff --git a/content/en/references/internal-endpoints.md b/content/en/references/internal-endpoints.md index b8ba56a579..8824fc14d2 100644 --- a/content/en/references/internal-endpoints.md +++ b/content/en/references/internal-endpoints.md @@ -1,50 +1,15 @@ --- title: Internal Endpoints weight: 50 +type: swagger tags: - internal-endpoints - localstack-endpoints -description: > - Overview of LocalStack and AWS specific internal endpoints for local development and testing +description: LocalStack REST API for internal and AWS-complementary features --- -LocalStack provides several internal endpoints for various local AWS services and LocalStack-specific features. These endpoints are not part of the official AWS API and are available in the `/_localstack` and `/_aws` paths. You can use [`cURL`](https://curl.se/) or your favourite HTTP REST client to access endpoints. +LocalStack provides a REST API for internal features such as init hooks, dynamic configuration, diagnostics, etc. and features that complement the AWS services. +These endpoints are available in the `/_localstack` and `/_aws` root paths respectively. +You may use [`cURL`](https://curl.se/) or your preferred HTTP client to access endpoints. -## LocalStack endpoints - -The API path for the LocalStack internal resources is `/_localstack`. The following endpoints are available: - -| Endpoint | Description | -| ---------------------------------| --------------------------------------------------------------------------- | -| `/_localstack/health`| To check the available and running AWS services in LocalStack. You can use the endpoint to restart the LocalStack services. | -| `/_localstack/plugins` | Shows the [Plux plugins ](https://github.com/localstack/localstack/blob/master/docs/localstack-concepts/README.md#plugins) information in LocalStack. | -| `/_localstack/init`| Shows the initialization status after setting up [Init hooks](https://docs.localstack.cloud/references/init-hooks/). | -| `/_localstack/cloudformation/deploy` | Enables you to deploy CloudFormation templates locally through a web interface. | -| `/_localstack/diagnose`| Reports extensive and sensitive data from LocalStack instance, enabled via the `DEBUG=1` configuration variable. | -| `/_localstack/config` | Enables dynamic configuration updates at runtime, enabled via the `ENABLE_CONFIG_UPDATES` configuration variable. | -| `/_localstack/state//save` | Get a snapshot of the given AWS service using the Persistence mechanism. | -| `/_localstack/state//load` | Load the most recent snapshot of the given service using the Persistence mechanism. | -| `/_localstack/state/reset` | Reset the state of the services using the Persistence mechanism. | -| `/_localstack/state//reset` | Reset the state of the given service using the Persistence mechanism. | - -{{< callout "tip" >}} -You can use the `/_localstack/health` endpoint to restart or kill the services. You can use `cURL` or your HTTP REST client to access the endpoint: -{{< command >}} -$ curl -v --request POST --header "Content-Type: application/json" --data '{"action":"restart"}' http://localhost:4566/_localstack/health -$ curl -v --request POST --header "Content-Type: application/json" --data '{"action":"kill"}' http://localhost:4566/_localstack/health -{{< /command >}} -{{< /callout >}} - -## AWS endpoints - -The API path for the AWS internal resources is `/_aws`. The following endpoints are available: - -| Endpoint | Description | -|----------------------------------------|-----------------------------------------------------------| -| `/_aws/lambda/runtimes` | List Lambda runtimes. See [Lambda – Special Tools]({{< ref "user-guide/aws/lambda#special-tools" >}}) | -| `/_aws/sqs/messages` | Access all messages within a SQS queue | -| `/_aws/sns/platform-endpoint-messages` | Access and delete all the published SNS platform messages | -| `/_aws/ses` | Access and delete all the sent SES emails | -| `/_aws/cloudwatch/metrics/raw` | Access all the raw CloudWatch metrics | -| `/_aws/cognito-idp` | Access the local Cognito login form | -| `/_aws/dynamodb/expired` | Trigger the DynamoDB TTL worker at convenience | +{{< swaggerui src="/openapi.json" >}} diff --git a/static/openapi.json b/static/openapi.json new file mode 100644 index 0000000000..6c66ce5b56 --- /dev/null +++ b/static/openapi.json @@ -0,0 +1,1501 @@ +{ + "openapi": "3.1.0", + "info": { + "title": "LocalStack REST API for Pro", + "summary": "The LocalStack REST API exposes functionality related to diagnostics, health checks, plugins, initialisation hooks, service introspection, and more.", + "termsOfService": "https://www.localstack.cloud/legal/tos", + "contact": { + "name": "LocalStack Support", + "url": "https://www.localstack.cloud/contact", + "email": "info@localstack.cloud" + }, + "version": "3.5.1.dev" + }, + "externalDocs": { + "description": "LocalStack Documentation", + "url": "https://docs.localstack.cloud" + }, + "components": { + "schemas": { + "SessionInfo": { + "type": "object", + "additionalProperties": false, + "required": [ + "version", + "edition", + "is_license_activated", + "session_id", + "machine_id", + "system", + "is_docker", + "server_time_utc", + "uptime" + ], + "properties": { + "version": { + "type": "string" + }, + "edition": { + "type": "string" + }, + "is_license_activated": { + "type": "boolean" + }, + "session_id": { + "type": "string" + }, + "machine_id": { + "type": "string" + }, + "system": { + "type": "string" + }, + "is_docker": { + "type": "boolean" + }, + "server_time_utc": { + "type": "string" + }, + "uptime": { + "type": "integer" + } + } + }, + "InitScripts": { + "type": "object", + "additionalProperties": false, + "required": [ + "completed", + "scripts" + ], + "properties": { + "completed": { + "type": "object", + "additionalProperties": false, + "required": [ + "BOOT", + "START", + "READY", + "SHUTDOWN" + ], + "properties": { + "BOOT": { + "type": "boolean" + }, + "START": { + "type": "boolean" + }, + "READY": { + "type": "boolean" + }, + "SHUTDOWN": { + "type": "boolean" + } + } + }, + "scripts": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ + "stage", + "name", + "state" + ], + "properties": { + "stage": { + "type": "string" + }, + "name": { + "type": "string" + }, + "state": { + "type": "string" + } + } + } + } + } + }, + "SnsSubscriptionTokenError": { + "type": "object", + "additionalProperties": false, + "required": [ + "error", + "subscription_arn" + ], + "properties": { + "error": { + "type": "string" + }, + "subscription_arn": { + "type": "string" + } + } + }, + "SesSentEmail": { + "type": "object", + "additionalProperties": false, + "required": [ + "Id", + "Region", + "Timestamp", + "Destination", + "RawData", + "Source", + "Subject", + "Template", + "TemplateData", + "Body" + ], + "properties": { + "Id": { + "type": "string" + }, + "Region": { + "type": "string" + }, + "Timestamp": { + "type": "string" + }, + "Destination": { + "type": "string" + }, + "RawData": { + "type": "string" + }, + "Source": { + "type": "string" + }, + "Subject": { + "type": "string" + }, + "Template": { + "type": "string" + }, + "TemplateData": { + "type": "string" + }, + "Body": { + "type": "object", + "additionalProperties": false, + "required": [ + "html_part", + "text_part" + ], + "properties": { + "html_part": { + "type": "string" + }, + "text_part": { + "type": "string" + } + } + } + } + } + }, + "parameters": { + "SesMessageId": { + "name": "id", + "description": "ID of the message (`id` field of SES message)", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + "SnsAccountId": { + "name": "accountId", + "description": "`accountId` field of the resource", + "in": "query", + "required": false, + "schema": { + "type": "string", + "default": "000000000000" + } + }, + "SnsRegion": { + "name": "region", + "description": "`region` field of the resource", + "in": "query", + "required": false, + "schema": { + "type": "string", + "default": "us-east-1" + } + }, + "SnsEndpointArn": { + "name": "endpointArn", + "description": "`endpointArn` field of the resource", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + "SnsPhoneNumber": { + "name": "phoneNumber", + "description": "`phoneNumber` field of the resource", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + } + } + }, + "paths": { + "/_aws/cloudwatch/metrics/raw": { + "get": { + "description": "Retrieve CloudWatch metrics", + "responses": { + "200": { + "description": "CloudWatch metrics", + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": false, + "required": [ + "metrics" + ], + "properties": { + "metrics": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ + "ns", + "n", + "v", + "t", + "d", + "account", + "region" + ], + "properties": { + "ns": { + "type": "string", + "description": "Namespace" + }, + "n": { + "type": "string", + "description": "Metric name" + }, + "v": { + "type": "string", + "description": "Metric value" + }, + "t": { + "type": "number", + "description": "Timestamp" + }, + "d": { + "type": "array", + "description": "Dimensions", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ + "n", + "v" + ], + "properties": { + "n": { + "type": "string", + "description": "Dimension name" + }, + "v": { + "type": "string", + "description": "Dimension value" + } + } + } + }, + "account": { + "type": "string", + "description": "Account ID" + }, + "region": { + "type": "string", + "description": "Region name" + } + } + } + } + } + } + } + } + } + } + } + }, + "/_aws/dynamodb/expired": { + "delete": { + "description": "Delete expired items from TTL-enabled DynamoDB tables", + "responses": { + "200": { + "description": "Operation was successful", + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": false, + "required": [ + "ExpiredItems" + ], + "properties": { + "ExpiredItems": { + "description": "Number of expired items that were deleted", + "type": "integer" + } + } + } + } + } + } + } + } + }, + "/_aws/events/rules/{rule_arn}/trigger": { + "get": { + "description": "Trigger a scheduled EventBridge rule", + "parameters": [ + { + "name": "rule_arn", + "description": "EventBridge rule ARN", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "EventBridge rule was triggered" + }, + "404": { + "description": "Not found" + } + } + } + }, + "/_aws/lambda/init": { + "get": { + "description": "Retrieve Lambda runtime init binary", + "responses": { + "200": { + "description": "Lambda runtime init binary", + "content": { + "application/octet-stream": {} + } + } + } + } + }, + "/_aws/lambda/runtimes": { + "get": { + "description": "List available Lambda runtimes", + "parameters": [ + { + "name": "filter", + "in": "query", + "required": false, + "schema": { + "type": "string", + "default": "supported", + "enum": [ + "all", + "deprecated", + "supported" + ] + } + } + ], + "responses": { + "200": { + "description": "Available Lambda runtimes", + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": false, + "required": [ + "Runtimes" + ], + "properties": { + "Runtimes": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + } + } + } + }, + "/_aws/ses": { + "get": { + "description": "Retrieve sent SES messages", + "parameters": [ + { + "$ref": "#/components/parameters/SesMessageId" + }, + { + "name": "email", + "description": "Source of the message (`source` field of SES message)", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "List of sent messages", + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": false, + "required": [ + "messages" + ], + "properties": { + "messages": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SesSentEmail" + } + } + } + } + } + } + } + } + }, + "delete": { + "description": "Discard sent SES messages", + "parameters": [ + { + "$ref": "#/components/parameters/SesMessageId" + } + ], + "responses": { + "204": { + "description": "Message was successfully discarded" + } + } + } + }, + "/_aws/sns/platform-endpoint-messages": { + "get": { + "description": "Retrieve SNS platform endpoint messages", + "parameters": [ + { + "$ref": "#/components/parameters/SnsAccountId" + }, + { + "$ref": "#/components/parameters/SnsRegion" + }, + { + "$ref": "#/components/parameters/SnsEndpointArn" + } + ], + "responses": { + "200": { + "description": "Platform endpoint messages", + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": false, + "required": [ + "platform_endpoint_messages", + "region" + ], + "properties": { + "platform_endpoint_messages": { + "type": "object" + }, + "region": { + "type": "string" + } + } + } + } + } + } + } + }, + "delete": { + "description": "Discard SNS platform endpoint messages", + "parameters": [ + { + "$ref": "#/components/parameters/SnsAccountId" + }, + { + "$ref": "#/components/parameters/SnsRegion" + }, + { + "$ref": "#/components/parameters/SnsEndpointArn" + } + ], + "responses": { + "204": { + "description": "Platform endpoint message was discarded" + } + } + } + }, + "/_aws/sns/sms-messages": { + "get": { + "description": "Retrieve SNS SMS messages", + "parameters": [ + { + "$ref": "#/components/parameters/SnsAccountId" + }, + { + "$ref": "#/components/parameters/SnsRegion" + }, + { + "$ref": "#/components/parameters/SnsPhoneNumber" + } + ], + "responses": { + "200": { + "description": "SNS SMS messages", + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": false, + "required": [ + "sms_messages", + "region" + ], + "properties": { + "sms_messages": { + "type": "object" + }, + "region": { + "type": "string" + } + } + } + } + } + } + } + }, + "delete": { + "description": "Discard SNS SMS messages", + "parameters": [ + { + "$ref": "#/components/parameters/SnsAccountId" + }, + { + "$ref": "#/components/parameters/SnsRegion" + }, + { + "$ref": "#/components/parameters/SnsPhoneNumber" + } + ], + "responses": { + "204": { + "description": "SMS message was discarded", + "content": { + "text/plain": {} + } + } + } + } + }, + "/_aws/sns/subscription-tokens/{subscription_arn}": { + "get": { + "description": "Retrieve SNS subscription token for confirmation", + "parameters": [ + { + "name": "subscription_arn", + "description": "`subscriptionArn` resource of subscription token", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Subscription token", + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": false, + "required": [ + "subscription_token", + "subscription_arn" + ], + "properties": { + "subscription_token": { + "type": "string" + }, + "subscription_arn": { + "type": "string" + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SnsSubscriptionTokenError" + } + } + } + }, + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SnsSubscriptionTokenError" + } + } + } + } + } + } + }, + "/_aws/sqs/messages": { + "get": { + "description": "List SQS queue messages without side effects", + "parameters": [ + { + "name": "QueueUrl", + "description": "SQS queue URL", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "SQS queue messages", + "content": { + "text/xml": {} + } + }, + "400": { + "description": "Bad request", + "content": { + "text/xml": {} + } + }, + "404": { + "description": "Not found", + "content": { + "text/xml": {} + } + } + } + } + }, + "/_aws/sqs/messages/{region}/{account_id}/{queue_name}": { + "get": { + "description": "List SQS messages without side effects", + "parameters": [ + { + "name": "region", + "description": "SQS queue region", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "account_id", + "description": "SQS queue account ID", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "queue_name", + "description": "SQS queue name", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "SQS queue messages", + "content": { + "text/xml": {} + } + }, + "400": { + "description": "Bad request", + "content": { + "text/xml": {} + } + }, + "404": { + "description": "Not found", + "content": { + "text/xml": {} + } + } + } + } + }, + "/_localstack/config": { + "get": { + "description": "Get current LocalStack configuration", + "responses": { + "200": { + "description": "Current LocalStack configuration", + "content": { + "application/json": { + "schema": { + "type": "object" + } + } + } + } + } + }, + "post": { + "requestBody": { + "description": "Configuration option to update with new value", + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": false, + "required": [ + "variable", + "value" + ], + "properties": { + "variable": { + "type": "string", + "pattern": "^[_a-zA-Z0-9]+$" + }, + "value": { + "type": [ + "number", + "string" + ] + } + } + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Configuration option is updated", + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": false, + "required": [ + "variable", + "value" + ], + "properties": { + "variable": { + "type": "string" + }, + "value": { + "type": [ + "number", + "string" + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": {} + } + } + } + } + }, + "/_localstack/diagnose": { + "get": { + "description": "Get diagnostics report", + "responses": { + "200": { + "description": "Diagnostics report", + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": false, + "required": [ + "version", + "info", + "services", + "config", + "docker-inspect", + "docker-dependent-image-hosts", + "file-tree", + "important-endpoints", + "logs", + "usage" + ], + "properties": { + "version": { + "type": "object", + "additionalProperties": false, + "required": [ + "image-version", + "localstack-version", + "host" + ], + "properties": { + "image-version": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "sha256", + "tag", + "created" + ], + "properties": { + "id": { + "type": "string" + }, + "sha256": { + "type": "string" + }, + "tag": { + "type": "string" + }, + "created": { + "type": "string" + } + } + }, + "localstack-version": { + "type": "object", + "additionalProperties": false, + "required": [ + "build-date", + "build-git-hash", + "build-version" + ], + "properties": { + "build-date": { + "type": [ + "string", + "null" + ] + }, + "build-git-hash": { + "type": [ + "string", + "null" + ] + }, + "build-version": { + "type": [ + "string", + "null" + ] + } + } + }, + "host": { + "type": "object", + "additionalProperties": false, + "required": [ + "kernel" + ], + "properties": { + "kernel": { + "type": "string" + } + } + } + } + }, + "info": { + "$ref": "#/components/schemas/SessionInfo" + }, + "services": { + "type": "object" + }, + "config": { + "type": "object" + }, + "docker-inspect": { + "type": "object" + }, + "docker-dependent-image-hosts": { + "type": "object" + }, + "file-tree": { + "type": "object" + }, + "important-endpoints": { + "type": "object" + }, + "logs": { + "type": "object", + "additionalProperties": false, + "required": [ + "docker" + ], + "properties": { + "docker": { + "type": "string" + } + } + }, + "usage": { + "type": "object" + } + } + } + } + } + } + } + } + }, + "/_localstack/health": { + "get": { + "description": "Get available LocalStack features and AWS services", + "parameters": [ + { + "name": "reload", + "in": "query", + "allowEmptyValue": true, + "schema": { + "type": "string" + }, + "required": false + } + ], + "responses": { + "200": { + "description": "Available LocalStack features and AWS services", + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": false, + "required": [ + "edition", + "features", + "services", + "version" + ], + "properties": { + "edition": { + "type": "string", + "enum": [ + "community", + "pro", + "enterprise", + "unknown" + ] + }, + "features": { + "type": "object" + }, + "services": { + "type": "object" + }, + "version": { + "type": "string" + } + } + } + } + } + } + } + }, + "head": { + "responses": { + "200": { + "description": "", + "content": { + "text/plain": {} + } + } + } + }, + "post": { + "description": "Restart or terminate LocalStack session", + "responses": { + "200": { + "description": "Action was successful", + "content": { + "text/plain": {} + } + }, + "400": { + "description": "Bad request", + "content": { + "text/plain": {} + } + } + }, + "requestBody": { + "description": "Action to perform", + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": false, + "required": [ + "action" + ], + "properties": { + "action": { + "type": "string", + "enum": [ + "restart", + "kill" + ] + } + } + } + } + }, + "required": true + } + }, + "put": { + "description": "Store arbitrary data to in-memory state", + "responses": { + "200": { + "description": "Data was saved", + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": false, + "required": [ + "status" + ], + "properties": { + "status": { + "type": "string" + } + } + } + } + } + } + }, + "requestBody": { + "description": "Data to save", + "content": { + "application/json": { + "schema": { + "type": "object" + } + } + } + } + } + }, + "/_localstack/info": { + "get": { + "description": "Get information about the current LocalStack session", + "responses": { + "200": { + "description": "Information about the current LocalStack session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SessionInfo" + } + } + } + } + } + } + }, + "/_localstack/init": { + "get": { + "description": "Get information about init scripts", + "responses": { + "200": { + "description": "Information about init scripts", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InitScripts" + } + } + } + } + } + } + }, + "/_localstack/init/{stage}": { + "get": { + "description": "Get information about init scripts in a specific stage", + "parameters": [ + { + "name": "stage", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Information about init scripts in a specific stage", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InitScripts" + } + } + } + } + } + } + }, + "/_localstack/plugins": { + "get": { + "description": "", + "responses": { + "200": { + "description": "", + "content": { + "application/json": {} + } + } + } + } + }, + "/_localstack/usage": { + "get": { + "description": "", + "responses": { + "200": { + "description": "", + "content": { + "application/json": {} + } + } + } + } + }, + "/_aws/cognito-idp/forgotPassword": { + "get": { + "description": "Cognito forgot password endpoint", + "tags": [ + "pro" + ], + "externalDocs": { + "url": "https://docs.aws.amazon.com/cognito/latest/developerguide/hosted-UI-endpoints.html" + } + }, + "post": { + "description": "Cognito forgot password endpoint", + "tags": [ + "pro" + ], + "externalDocs": { + "url": "https://docs.aws.amazon.com/cognito/latest/developerguide/hosted-UI-endpoints.html" + } + } + }, + "/_aws/cognito-idp/login": { + "get": { + "description": "Cognito login endpoint", + "tags": [ + "pro" + ], + "externalDocs": { + "url": "https://docs.aws.amazon.com/cognito/latest/developerguide/hosted-UI-endpoints.html" + } + }, + "post": { + "description": "Cognito login endpoint", + "tags": [ + "pro" + ], + "externalDocs": { + "url": "https://docs.aws.amazon.com/cognito/latest/developerguide/hosted-UI-endpoints.html" + } + } + }, + "/_aws/cognito-idp/logout": { + "get": { + "description": "Cognito logout endpoint", + "tags": [ + "pro" + ], + "externalDocs": { + "url": "https://docs.aws.amazon.com/cognito/latest/developerguide/hosted-UI-endpoints.html" + } + }, + "post": { + "description": "Cognito logout endpoint", + "tags": [ + "pro" + ], + "externalDocs": { + "url": "https://docs.aws.amazon.com/cognito/latest/developerguide/hosted-UI-endpoints.html" + } + } + }, + "/_aws/cognito-idp/oauth2/authorize": { + "get": { + "description": "Cognito OAuth 2.0 authorization endpoint", + "tags": [ + "pro" + ], + "externalDocs": { + "url": "https://docs.aws.amazon.com/cognito/latest/developerguide/authorization-endpoint.html" + } + } + }, + "/_aws/cognito-idp/oauth2/token": { + "post": { + "description": "Cognito OAuth 2.0 token endpoint", + "tags": [ + "pro" + ], + "externalDocs": { + "url": "https://docs.aws.amazon.com/cognito/latest/developerguide/token-endpoint.html" + } + } + }, + "/_aws/cognito-idp/oauth2/userInfo": { + "get": { + "description": "Cognito OpenID Connect userInfo endpoint", + "tags": [ + "pro" + ], + "externalDocs": { + "url": "https://docs.aws.amazon.com/cognito/latest/developerguide/userinfo-endpoint.html" + } + } + }, + "/_aws/cognito-idp/saml2/idpresponse": { + "get": { + "description": "Cognito SAML 2.0 idpresponse endpoint", + "tags": [ + "pro" + ], + "externalDocs": { + "url": "https://docs.aws.amazon.com/cognito/latest/developerguide/saml2-idpresponse-endpoint.html" + } + }, + "post": { + "description": "Cognito SAML 2.0 idpresponse endpoint", + "tags": [ + "pro" + ], + "externalDocs": { + "url": "https://docs.aws.amazon.com/cognito/latest/developerguide/saml2-idpresponse-endpoint.html" + } + } + }, + "/_aws/cognito-idp/signup": { + "get": { + "description": "Cognito signup endpoint", + "tags": [ + "pro" + ], + "externalDocs": { + "url": "https://docs.aws.amazon.com/cognito/latest/developerguide/hosted-UI-endpoints.html" + } + }, + "post": { + "description": "Cognito signup endpoint", + "tags": [ + "pro" + ], + "externalDocs": { + "url": "https://docs.aws.amazon.com/cognito/latest/developerguide/hosted-UI-endpoints.html" + } + } + }, + "/_aws/iot/LocalStackIoTRootCA.pem": { + "get": { + "description": "Retrieve certificate for LocalStack IoT root certificate authority", + "tags": [ + "pro" + ] + } + }, + "/_localstack/chaos": {}, + "/_localstack/cloudformation/deploy": {}, + "/_localstack/pods": {}, + "/_localstack/pods/{name}": {}, + "/_localstack/pods/{name}/versions": {}, + "/_localstack/pods/environment": {}, + "/_localstack/pods/remotes": {}, + "/_localstack/pods/remotes/{name}": {}, + "/_localstack/pods/remotes/token": {}, + "/_localstack/pods/state": {}, + "/_localstack/pods/state/metamodel": {}, + "/_localstack/stackinfo": { + "get": { + "description": "", + "tags": [ + "pro" + ], + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": false, + "required": [ + "server_time_utc", + "session_id", + "api_key", + "system", + "version", + "is_ci", + "is_docker", + "duration_in_seconds", + "top_user_agent", + "number_of_services", + "number_of_api_calls_success", + "number_of_api_calls_error" + ], + "properties": { + "server_time_utc": { + "type": "string" + }, + "session_id": { + "type": "string" + }, + "api_key": { + "type": "string" + }, + "system": { + "type": "string" + }, + "version": { + "type": "string" + }, + "is_ci": { + "type": "boolean" + }, + "is_docker": { + "type": "boolean" + }, + "duration_in_seconds": { + "type": "integer" + }, + "top_user_agent": { + "type": "string" + }, + "number_of_services": { + "type": "integer" + }, + "number_of_api_calls_success": { + "type": "integer" + }, + "number_of_api_calls_error": { + "type": "integer" + } + } + } + } + } + } + } + } + }, + "/_localstack/state/load": {}, + "/_localstack/state/reset": { + "post": { + "description": "Reset all service states", + "tags": [ + "pro" + ], + "responses": { + "200": { + "description": "Successful" + } + } + } + }, + "/_localstack/state/save": {}, + "/_localstack/state/{service}/load": {}, + "/_localstack/state/{service}/reset": { + "post": { + "description": "Reset a service state", + "tags": [ + "pro" + ], + "parameters": [ + { + "name": "service", + "description": "Service name", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Successful" + } + } + } + }, + "/_localstack/state/{service}/save": {} + }, + "tags": [ + { + "name": "pro", + "description": "Available in LocalStack Pro" + } + ] +} From f923285d66e6f1a7fc66d3611cb8638dd899b8d7 Mon Sep 17 00:00:00 2001 From: Viren Nadkarni Date: Thu, 27 Jun 2024 14:32:43 +0530 Subject: [PATCH 2/6] Update spec --- static/openapi.json | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/static/openapi.json b/static/openapi.json index 6c66ce5b56..cbbc2ffd52 100644 --- a/static/openapi.json +++ b/static/openapi.json @@ -15,6 +15,11 @@ "description": "LocalStack Documentation", "url": "https://docs.localstack.cloud" }, + "servers": [ + { + "url": "http://localhost.localstack.cloud:4566" + } + ], "components": { "schemas": { "SessionInfo": { From e28d4eef959dc4aed7a54e9a62167c551eab3435 Mon Sep 17 00:00:00 2001 From: Viren Nadkarni Date: Thu, 27 Jun 2024 14:54:17 +0530 Subject: [PATCH 3/6] Add callout about Swagger UI --- content/en/references/internal-endpoints.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/content/en/references/internal-endpoints.md b/content/en/references/internal-endpoints.md index 8824fc14d2..b38058853c 100644 --- a/content/en/references/internal-endpoints.md +++ b/content/en/references/internal-endpoints.md @@ -10,6 +10,11 @@ description: LocalStack REST API for internal and AWS-complementary features LocalStack provides a REST API for internal features such as init hooks, dynamic configuration, diagnostics, etc. and features that complement the AWS services. These endpoints are available in the `/_localstack` and `/_aws` root paths respectively. -You may use [`cURL`](https://curl.se/) or your preferred HTTP client to access endpoints. +You may use [cURL](https://curl.se/) or your preferred HTTP client to access these endpoints. + +{{< callout "tip" >}} +You can use the Swagger UI below to interact with the API right from your browser. +This may require changing the LocalStack [security settings]({{< ref "configuration#security" >}}) by allowing `https://docs.localstack.cloud` as CORS origin. +{{< /callout >}} {{< swaggerui src="/openapi.json" >}} From baf057721440baed1f121f116d430427517c226e Mon Sep 17 00:00:00 2001 From: Viren Nadkarni Date: Thu, 27 Jun 2024 18:43:15 +0530 Subject: [PATCH 4/6] Update spec --- static/openapi.json | 335 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 318 insertions(+), 17 deletions(-) diff --git a/static/openapi.json b/static/openapi.json index cbbc2ffd52..150afbbb0e 100644 --- a/static/openapi.json +++ b/static/openapi.json @@ -199,6 +199,24 @@ } } } + }, + "PodRemoteConfig": { + "type": "object", + "additionalProperties": false, + "required": [], + "properties": {} + }, + "PodSaveRequest": { + "type": "object", + "additionalProperties": false, + "required": [], + "properties": {} + }, + "PodEvent": { + "type": "object", + "additionalProperties": false, + "required": [], + "properties": {} } }, "parameters": { @@ -248,6 +266,15 @@ "schema": { "type": "string" } + }, + "ServiceName": { + "name": "service", + "description": "Service name", + "in": "path", + "required": true, + "schema": { + "type": "string" + } } } }, @@ -1373,15 +1400,219 @@ }, "/_localstack/chaos": {}, "/_localstack/cloudformation/deploy": {}, - "/_localstack/pods": {}, - "/_localstack/pods/{name}": {}, - "/_localstack/pods/{name}/versions": {}, + "/_localstack/pods": { + "get": { + "description": "List cloud pods", + "tags": [ + "pro" + ], + "parameters": [ + { + "name": "creator", + "description": "User ID of the pod creator. Special values like `me` are accepted.", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PodRemoteConfig" + } + } + } + }, + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": false, + "required": [ + "cloudpods" + ], + "properties": { + "cloudpods": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ + "pod_name", + "max_version" + ], + "properties": { + "pod_name": { + "type": "string" + }, + "max_version": { + "type": "string" + } + } + } + } + } + } + } + } + } + } + } + }, + "/_localstack/pods/{name}": { + "post": { + "description": "Create and register a cloud pod version", + "tags": [ + "pro" + ], + "parameters": [ + { + "name": "name", + "description": "Cloud pod name", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "local", + "in": "query", + "required": false, + "schema": { + "type": "boolean" + } + }, + { + "name": "version", + "description": "Cloud pod version", + "in": "query", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PodSaveRequest" + } + } + } + }, + "responses": { + "200": { + "description": "", + "content": { + "application/x-ndjson": { + "schema": { + "$ref": "#/components/schemas/PodEvent" + } + } + } + } + } + }, + "put": { + "description": "Load a cloud pod version", + "tags": [ + "pro" + ], + "parameters": [], + "requestBody": {}, + "responses": {} + }, + "delete": { + "description": "Delete a cloud pod", + "tags": [ + "pro" + ], + "parameters": [], + "requestBody": {}, + "responses": {} + } + }, + "/_localstack/pods/{name}/versions": { + "get": { + "description": "List versions for a cloud pod", + "tags": [ + "pro" + ], + "parameters": [ + { + "name": "name", + "description": "Cloud pod name", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PodRemoteConfig" + } + } + } + }, + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": false, + "required": [ + "versions" + ], + "properties": { + "versions": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + } + } + } + }, "/_localstack/pods/environment": {}, "/_localstack/pods/remotes": {}, "/_localstack/pods/remotes/{name}": {}, "/_localstack/pods/remotes/token": {}, "/_localstack/pods/state": {}, - "/_localstack/pods/state/metamodel": {}, + "/_localstack/pods/state/metamodel": { + "get": { + "description": "Extract a metamodel representing the state of the current LocalStack session", + "tags": [ + "pro" + ], + "responses": { + "200": { + "description": "Metamodel representing the state of the current LocalStack session", + "content": { + "application/json": {} + } + } + } + } + }, "/_localstack/stackinfo": { "get": { "description": "", @@ -1455,7 +1686,22 @@ } } }, - "/_localstack/state/load": {}, + "/_localstack/state/load": { + "post": { + "description": "Load all service states", + "tags": [ + "pro" + ], + "responses": { + "200": { + "description": "Successful", + "content": { + "application/x-ndjson": {} + } + } + } + } + }, "/_localstack/state/reset": { "post": { "description": "Reset all service states", @@ -1464,13 +1710,51 @@ ], "responses": { "200": { - "description": "Successful" + "description": "Successful", + "content": { + "text/plain": {} + } + } + } + } + }, + "/_localstack/state/save": { + "post": { + "description": "Save all service states", + "tags": [ + "pro" + ], + "responses": { + "200": { + "description": "Successful", + "content": { + "application/x-ndjson": {} + } + } + } + } + }, + "/_localstack/state/{service}/load": { + "post": { + "description": "Load a service state", + "tags": [ + "pro" + ], + "parameters": [ + { + "$ref": "#/components/parameters/ServiceName" + } + ], + "responses": { + "200": { + "description": "Successful", + "content": { + "text/plain": {} + } } } } }, - "/_localstack/state/save": {}, - "/_localstack/state/{service}/load": {}, "/_localstack/state/{service}/reset": { "post": { "description": "Reset a service state", @@ -1479,23 +1763,40 @@ ], "parameters": [ { - "name": "service", - "description": "Service name", - "in": "path", - "required": true, - "schema": { - "type": "string" - } + "$ref": "#/components/parameters/ServiceName" } ], "responses": { "200": { - "description": "Successful" + "description": "Successful", + "content": { + "text/plain": {} + } } } } }, - "/_localstack/state/{service}/save": {} + "/_localstack/state/{service}/save": { + "post": { + "description": "Save a service state", + "tags": [ + "pro" + ], + "parameters": [ + { + "$ref": "#/components/parameters/ServiceName" + } + ], + "responses": { + "200": { + "description": "Successful", + "content": { + "text/plain": {} + } + } + } + } + } }, "tags": [ { From 10b8c19d54a01658e06d558532c77f3c7bfa4086 Mon Sep 17 00:00:00 2001 From: Viren Nadkarni Date: Thu, 27 Jun 2024 18:45:01 +0530 Subject: [PATCH 5/6] Fix grammar --- content/en/references/internal-endpoints.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/references/internal-endpoints.md b/content/en/references/internal-endpoints.md index b38058853c..55c0f507d5 100644 --- a/content/en/references/internal-endpoints.md +++ b/content/en/references/internal-endpoints.md @@ -14,7 +14,7 @@ You may use [cURL](https://curl.se/) or your preferred HTTP client to access the {{< callout "tip" >}} You can use the Swagger UI below to interact with the API right from your browser. -This may require changing the LocalStack [security settings]({{< ref "configuration#security" >}}) by allowing `https://docs.localstack.cloud` as CORS origin. +This may require changing the LocalStack [security settings]({{< ref "configuration#security" >}}) to allow `https://docs.localstack.cloud` as CORS origin. {{< /callout >}} {{< swaggerui src="/openapi.json" >}} From 6569311a3fa6ebe2fb9ef6e90a04587b054969c6 Mon Sep 17 00:00:00 2001 From: Viren Nadkarni Date: Wed, 31 Jul 2024 18:34:44 +0530 Subject: [PATCH 6/6] Remove sentence about curl --- content/en/references/internal-endpoints.md | 1 - 1 file changed, 1 deletion(-) diff --git a/content/en/references/internal-endpoints.md b/content/en/references/internal-endpoints.md index 55c0f507d5..4ca39da2bf 100644 --- a/content/en/references/internal-endpoints.md +++ b/content/en/references/internal-endpoints.md @@ -10,7 +10,6 @@ description: LocalStack REST API for internal and AWS-complementary features LocalStack provides a REST API for internal features such as init hooks, dynamic configuration, diagnostics, etc. and features that complement the AWS services. These endpoints are available in the `/_localstack` and `/_aws` root paths respectively. -You may use [cURL](https://curl.se/) or your preferred HTTP client to access these endpoints. {{< callout "tip" >}} You can use the Swagger UI below to interact with the API right from your browser.