Skip to main content

How to Develop and Test Locally

There is no way to start the mStudio public API locally. This makes the local development of extensions challenging if the extension heavily integrates with the mStudio. However, there are ways to assist the local extension development besides mocking the mStudio API, which might be difficult without deep knowledge of the API. We will explore these in the rest of this page.

Authenticated Domain Actions​

The easiest way to effectively test the interaction of your business logic and the mStudio is to use the mStudio public API directly. It is usually necessary to authenticate against the API.

...via a Personal API Token​

It is a good idea to use your personal API token during the early development of your extension, while you evaluate your business idea and work on a proof of concept. You can use this token for local development. However, it is important that you do not check in API tokens into version control systems like Git.

For more information about obtaining an API token, see obtaining an API token.

...via Extension Instance Secret Rotation​

Rotating the extension instance secret is another possibility for using the mStudio public API authenticated without implementing the authentication methods intended for extensions. For this, you can use the PUT/v2/contributors/{contributorId}/extensions/{extensionId}/extension-instances/{extensionInstanceId}/secret/ operation. The mStudio returns the new extension secret in the response and transfers it to the extension per webhook. We recommend you store the obtained secret securely, similar to personal API tokens. In the future, you can use this secret to obtain access tokens, as described in authenticating with the extension instance secret. When using this route, the mStudio executes the webhook call synchronously. If the webhook call fails, it is not sent again. Also, the new secret is not valid if the webhook call failes. To test without a working webhook handler, you can add "allowWebhookFailure": true to the request body. This way, the mStudio ignores failures of the webhook calls and the mStudio responds to the request with the new secret.

If you plan to implement the authentication using the extension instance secret later, this method is especially useful. Additionally, you can test initialization processes executed after webhook calls with a working secret without creating a new extension instance in the mStudio for every attempt.

...via OAuth2​

If you want to test the authentication and execution of domain actions per OAuth2, we recommend setting up a local redirect URI in the OAuth2 client. This can either be the localhost or a domain with an entry to your local host configuration. You should ensure that no public domain is used as an entry to your local host configuration that is not in your control to mitigate security risk.

Testing Lifecycle Webhooks​

...via the Local Development Server​

You can use the GitHub repository marketplace-local-dev-server to locally test lifecycle webhooks, including the verification of the sender identity.

The repository contains a docker-compose configuration that starts a local server. This server can send lifecycle webhooks. For this, it provides an API you can use to request lifecycle webhooks. You can freely choose the values transmitted by the webhooks. If you don't set some values, the server randomly generates those values.

If, for example, you set the extension instance IDs of the requested lifecycle webhooks and use a consistent ID, you can simulate complete lifecycles of extension instances.

...via Dry Run Webhooks​

You can use the mStudio backend to simulate lifecycle webhooks by using the POST/v2/contributors/{contributorId}/extensions/{extensionId}/extension-instances/{extensionInstanceId}/actions/dry-run/{webhookKind}/ operation. The mStudio will send the requested lifecycle webhook to the URL configured for the extension. You can only execute dry-run webhooks for extension instances belonging to you, the contributor. Similarly to the local development server, you can specify values for the content of the lifecycle webhooks or let the mStudio backend generate random values. For an overview of the values you can statically specify, see the linked operation.

The mStudio returns the result of the executed webhook containing the response body, headers, and status code as a response to the dry-run webhook request.

You can additionally process the executing-user-id parameter for documentation purposes. This parameter is additionally added to every dry-run webhook automatically. It contains the user ID of the user who requested the dry-run webhook.