diff --git a/content/en/docs/apidocs-mxsdk/apidocs/marketplace/_index.md b/content/en/docs/apidocs-mxsdk/apidocs/marketplace/_index.md new file mode 100644 index 00000000000..8a2fa17276d --- /dev/null +++ b/content/en/docs/apidocs-mxsdk/apidocs/marketplace/_index.md @@ -0,0 +1,11 @@ +--- +title: "APIs for Marketplace" +url: /apidocs-mxsdk/apidocs/apis-for-marketplace/ +type: swagger +no_list: false +description_list: true +description: "Provides the documentation of APIs for Marketplace." +linktitle: "Marketplace" +--- + +Mendix offers the following APIs for Marketplace: diff --git a/content/en/docs/apidocs-mxsdk/apidocs/content-api.md b/content/en/docs/apidocs-mxsdk/apidocs/marketplace/content-api.md similarity index 81% rename from content/en/docs/apidocs-mxsdk/apidocs/content-api.md rename to content/en/docs/apidocs-mxsdk/apidocs/marketplace/content-api.md index 4a9c6dcc061..7d0b1daaedd 100644 --- a/content/en/docs/apidocs-mxsdk/apidocs/content-api.md +++ b/content/en/docs/apidocs-mxsdk/apidocs/marketplace/content-api.md @@ -1,11 +1,10 @@ --- -title: "Content API" -linktitle: "Marketplace Content" +title: "Marketplace Content API" url: /apidocs-mxsdk/apidocs/content-api/ type: swagger description: "The Content API accesses both public and company-specific Marketplace content information." restapi: true -weight: 45 +weight: 10 --- ## Introduction @@ -22,7 +21,7 @@ If you have Marketplace content, this API can help you get the following informa ### Generating a PAT -For details on how to generate a PAT, see the [Personal Access Tokens](/portal/user-settings/#pat) section of *User Settings*. +For details on how to generate a PAT, refer to the [Personal Access Tokens](/portal/user-settings/#pat) section of *User Settings*. Select at least the following as the **Marketplace** scope: @@ -39,7 +38,7 @@ GET /content HTTP/1.1 Authorization: MxToken 7LJE…vk ``` -To authenticate calls when using the OpenAPI specification below, click **Authorize** and use the value `MxToken {GENERATED_PAT}`. +To authenticate calls when using the OpenAPI specification included in the next section, click **Authorize** and use the value `MxToken {GENERATED_PAT}`. ## API Reference diff --git a/content/en/docs/apidocs-mxsdk/apidocs/marketplace/publish-api.md b/content/en/docs/apidocs-mxsdk/apidocs/marketplace/publish-api.md new file mode 100644 index 00000000000..0153168d4aa --- /dev/null +++ b/content/en/docs/apidocs-mxsdk/apidocs/marketplace/publish-api.md @@ -0,0 +1,44 @@ +--- +title: "Marketplace Publish API" +url: /apidocs-mxsdk/apidocs/publish-api/ +type: swagger +description: "The Publish API accesses both public and company-specific Marketplace content information." +restapi: true +weight: 20 +--- + +## Introduction + +The Marketplace Publish API allows you to manage the releases of your Marketplace components. It provides endpoints to create new releases with version metadata, upload source files, check release status as it moves through review and publication workflows, and unpublish releases when needed. +The API handles both public and private components. + +{{% alert color="warning" %}} +You can currently only publish new releases of existing components. +{{% /alert %}} + +## Authentication {#authentication} + +### Generating a PAT + +For details on how to generate a PAT, refer to the [Personal Access Tokens](/portal/user-settings/#pat) section of *User Settings*. + +Select at least the following as the **Marketplace** scope: + +* `mx:marketplace:write` + +Store the generated value `{GENERATED_PAT}` somewhere safe so you can use it to authorize your Content API calls. + +### Using the PAT + +Each request must contain an `Authorization` header with the value `MxToken {GENERATED_PAT}`. Here is an example: + +```http +GET /content HTTP/1.1 +Authorization: MxToken 7LJE…vk +``` + +To authenticate calls when using the OpenAPI specification included in the next section, click **Authorize** and use the value `MxToken {GENERATED_PAT}`. + +## API Reference + +{{< swaggerui-disable-try-it-out src="/openapi-spec/marketplace-publish.yaml" >}} diff --git a/content/en/docs/control-center/marketplace/submitted-requests.md b/content/en/docs/control-center/marketplace/submitted-requests.md index 8f7d566730e..274c6af7cae 100644 --- a/content/en/docs/control-center/marketplace/submitted-requests.md +++ b/content/en/docs/control-center/marketplace/submitted-requests.md @@ -16,7 +16,7 @@ The **Submitted Requests** page gives you the governance capabilities to approve * Company guidelines assurance: It enables you to meet regulatory requirements and internal policies by thoroughly reviewing components. * Efficient management: It offers a centralized approval process to save time and resources, preventing additional communication outside of the platform. -{{% alert color="info" %}}As a Mendix Admin or component owner, you can always unpublish content from the Marketplace of your organization. This can help your organization keep its private Marketplace neat, with only relevant company content. To do so, go to [Company Content](/appstore/home-page/#company-content) in the Marketplace home page, click the {{% icon name="three-dots-menu-horizontal" %}} icon on the component card, then select **Unpublish all versions**. {{% /alert %}} +{{% alert color="info" %}}As a Mendix Admin or component owner, you can always unpublish content from the Marketplace of your organization. This can help your organization keep its private Marketplace neat, with only relevant company content. To do so, go to [Published](/appstore/home-page/#published) in the **Manage Components** section of the Marketplace home page, click **Manage Versions** in the contextual menu of the component, then select **Unpublish**. {{% /alert %}} The **Submitted Requests** page contains the following tabs: diff --git a/content/en/docs/control-center/security/software-composition/components.md b/content/en/docs/control-center/security/software-composition/components.md index bb9428e8699..38e80684e99 100644 --- a/content/en/docs/control-center/security/software-composition/components.md +++ b/content/en/docs/control-center/security/software-composition/components.md @@ -50,7 +50,7 @@ The component list contains the following information: * **Version** — The version of the component that is being used. * **Findings** — The number of findings of each type, color-coded according to severity level. * **License** — For components derived from the Mendix Marketplace, this is the end-user license for the component. -* **Marketplace** – Whether the component is **Public** or **Private**. A public component is available to the whole Mendix community in the Marketplace, while a private component is available only via your [Company Content](/appstore/home-page/#company-content) page. +* **Marketplace** – Whether the component is **Public** or **Private**. A public component is available to the whole Mendix community in the Marketplace, while a private component is only available for your organisation. On the Marketplace homepage, you can use the **Visibility** filter to display specific components. * **Apps using component** – The number of apps where the component is used. * **Latest version** — For components derived from the Mendix Marketplace, this is the latest version of the component. * **Publisher** — For components derived from the Mendix Marketplace, this is the name of the organization that published the component. diff --git a/content/en/docs/control-center/security/software-composition/overview.md b/content/en/docs/control-center/security/software-composition/overview.md index 1f1780186d0..916df8f9dd3 100755 --- a/content/en/docs/control-center/security/software-composition/overview.md +++ b/content/en/docs/control-center/security/software-composition/overview.md @@ -134,7 +134,7 @@ The component usage list contains the following information: For more information, refer to [Content Support Categories](/appstore/marketplace-content-support/#category). * **License** – For components derived from the Mendix Marketplace, this is the end-user license for the component. * **Latest version** – For components derived from the Mendix Marketplace, this is the latest version of the component. -* **Marketplace** – Whether the component is **Public** or **Private**. A public component is available to the whole Mendix community in the Marketplace, while a private component is available only via your [Company Content](/appstore/home-page/#company-content) page. +* **Marketplace** – Whether the component is **Public** or **Private**. A public component is available to the whole Mendix community in the Marketplace, while a private component is only available for your organisation. On the Marketplace homepage, you can use the **Visibility** filter to display specific components. * **Latest Runtime Compatible Version** — The most recent runtime version to which the component is compatible. * **Publisher** – For components derived from the Mendix Marketplace, this is the name of the organization that published the component. * Column customization ({{% icon name="view" %}}) – You can customize the columns of the list by clicking the {{% icon name="view" %}} icon and selecting or deselecting options. diff --git a/content/en/docs/deployment/general/software-composition.md b/content/en/docs/deployment/general/software-composition.md index ce8cf241d97..904c8ba1dbd 100644 --- a/content/en/docs/deployment/general/software-composition.md +++ b/content/en/docs/deployment/general/software-composition.md @@ -155,7 +155,7 @@ The component list contains the following information: * **Version** — The version of the component that is being used. * **Findings** — The number of findings of each type, color-coded according to severity level. * **License** — For components derived from the Mendix Marketplace, this is the end-user license for the component. -* **Marketplace** – Whether the component is **Public** or **Private**. A public component is available to the whole Mendix community in the Marketplace, while a private component is available only via your [Company Content](/appstore/home-page/#company-content) page. +* **Marketplace** – Whether the component is **Public** or **Private**. A public component is available to the whole Mendix community in the Marketplace, while a private component is only available for your organisation. On the Marketplace homepage, you can use the **Visibility** filter to display specific components. * **Latest version** — For components derived from the Mendix Marketplace, this is the latest version of the component. * **Publisher** — For components derived from the Mendix Marketplace, this is the name of the organization that published the component. * **View details** — Clicking this opens the [Component App Details](#component-usage) page. diff --git a/content/en/docs/marketplace/overview/component-details.md b/content/en/docs/marketplace/overview/component-details.md index b2adbe05ee8..296053f8be4 100644 --- a/content/en/docs/marketplace/overview/component-details.md +++ b/content/en/docs/marketplace/overview/component-details.md @@ -22,7 +22,7 @@ The header for a component includes the following details: * **Recommended**: If the header contains this label, it means that the component meets your company's policies and guidelines, and therefore is recommended by your Mendix Admins. * The name of the component -* **Save** – Click this to add the component to your [Saved Content](/appstore/home-page/#personal) list. +* **Save** – Click this to add the component to your **Saved** list. * Depending on the content type: * **Use in Studio Pro** for modules and widgets – Click this to copy the content ID so that you can [search for and use the component in Studio Pro](/appstore/use-content/#current-sp). diff --git a/content/en/docs/marketplace/overview/marketplace-home-page.md b/content/en/docs/marketplace/overview/marketplace-home-page.md index c9f8ecfcdcc..348cb341ca1 100644 --- a/content/en/docs/marketplace/overview/marketplace-home-page.md +++ b/content/en/docs/marketplace/overview/marketplace-home-page.md @@ -29,8 +29,8 @@ The search box at the top of the page allows you to explore the Mendix Marketpla You can refine search results using the following filters: * **Support** – Select between the available support categories. For details, see the [Marketplace Content Support](/appstore/marketplace-content-support/). -* **Visibility** – Choose whether you want to display [public or private](/appstore/submit-content/#support-licensing) content. -* **Content Types** – Choose the type of content to display. For details, see the [Types of Marketplace Components](/appstore/#components-type) section in *Marketplace*. +* **Visibility** – Choose whether you want to display public, private, or company components. +* **Content Types** – Choose the type of content to display. For details, refer to the [Types of Marketplace Components](/appstore/#components-type) section in *Marketplace*. * **Category** – Select specific domains in which components or services share characteristics, functions, or purposes. * **Industry** – Select specific sectors or business domains in which components or services are used. * **Compatibility** – Choose between Studio Pro major versions. @@ -40,9 +40,39 @@ You can refine search results using the following filters: For details on finding and installing Marketplace content in Studio Pro, see the [Finding and Downloading Content in Studio Pro](/appstore/use-content/#downloading) section of *Using Marketplace Content*. {{% /alert %}} -## Personal {#personal} +## Manage Components -The **Personal** category contains the items described in the following sections. +The **Manage Components** category contains the items described in the following sections. + +### Published {#published} + +This page includes all components that you have access to, along with the following information for each: + +* **Name** – The component's name. Clicking the name of a component in the list opens its [details page](/appstore/component-details/). +* **Visibility** – Indicates whether the component is public or private. + If a component is marked as private, that means the component is your company's private Marketplace content. For details on how this is configured, refer to the [Adding New Marketplace Content](/appstore/submit-content/#adding) section of *Uploading to the Marketplace*. This content can be shared with [guests](#guests). +* **Support Type** – The category of support Mendix offers for the component. +* **Component Type** – The type of component. For details, refer to the [Types of Marketplace Components](/appstore/#components-type) section in *Marketplace*. +* **Company Group** – The [company groups](#content-groups) that the component belongs to, if any. +* **Last Updated On** – The date when the component was last updated. +* **Latest Version** – The latest version of the component. +* **Studio Pro Version** – The Studio Pro version required for the component to work. +* **Actions** – Select one of these contextual actions: + + * **Add New Release** – Add a new version of the component. + * **Manage Versions** – Edit or unpublish any version of the component. Keep in mind the following: + + * If the component is [protected](#group-content) within a [content group](#content-groups), a [group member](#members) can unpublish any version. + * If the component is not protected within a content group, you can only unpublish a version that you have published yourself. + * Select **Unpublish** to remove all your versions of the component. + * The option to unpublish is only available for deprecated components. + + For details on editing, refer to the [Adding New Marketplace Content](/appstore/submit-content/#adding) section of *Uploading to the Marketplace*. + + * **Deprecate Component** – Deprecate the component, and select alternatives. + For details on deprecating components, refer to [Deprecating Marketplace Content](/appstore/deprecate-content/). + +From this page, you can also upload a new component by clicking **Upload Component**. For details, refer to [Uploading Content to the Marketplace](/appstore/submit-content/). ### Drafts {#my-drafts} @@ -70,40 +100,14 @@ Click **More Options** ({{% icon name="three-dots-menu-horizontal" %}}) on a com Keep in mind the following: -* Only one draft version of a component can exist at a time, so when one draft version is in progress, you cannot initiate another. * If there is a draft version in progress, you can edit or delete it. * If there is a draft version in progress, and it is assigned to another user, you can reassign it to to yourself. For more information on creating a draft version, refer to the [Updating Existing Marketplace Content](/appstore/submit-content/#updating) section of *Uploading to the Marketplace*. -### Components {#my-content} - -Clicking **Components** opens the **My Components** page, where you can see a list of the Marketplace components for which you have created at least one version. -Clicking the name of a component in the list opens its [details page](/appstore/component-details/). - -Click the contextual **Actions** menu to access options for managing your content: - -* **Add New Release** – Add a new version of the component. -* **Manage Versions** – Edit or unpublish any version of the component. - Keep in mind the following: - - * If the component is [protected](#group-content) within a [content group](#content-groups), a [group member](#members) can unpublish any version. - * If the component is not protected within a content group, you can only unpublish a version that you have published yourself. - * Select **Unpublish** to remove all your versions of the component. - * The option to unpublish is only available for deprecated components. - - For details on editing, refer to the [Adding New Marketplace Content](/appstore/submit-content/#adding) section of *Uploading to the Marketplace*. - -* **Deprecate Component** – Deprecate the component, and select alternatives. - For details on deprecating components, refer to [Deprecating Marketplace Content](/appstore/deprecate-content/). - -A **Private** label on a component means the component is your company's private Marketplace content. For details on how this is configured, refer to the [Adding New Marketplace Content](/appstore/submit-content/#adding) section of *Uploading to the Marketplace*. This content can be shared with [guests](#guests). +## Personal -A component assigned as [group content](#group-content) will have a label for the [content group](#content-groups) to which it is assigned. - -### Shared with Me {#shared-with-me} - -This page contains private content shared with you by other companies who have marked you as a [guest](#guests). +The **Personal** category contains the items described in the following sections. ### Saved {#saved-components} @@ -116,25 +120,18 @@ Click the contextual menu to access options for managing this component: * **Receive/Stop Email Notifications** – Start receiving email notifications, or stop the notifications if they are enabled. * **Unsave** – Remove the component from your saved content. -### Reviews {#my-reviews} - -Clicking **Reviews** opens the **My Reviews** page, which contains reviews of [My Components](#my-content) by other users, as well as **My reviews** that you have written for other content. - -## Company {#company} - -The **Company** category contains the items described in the following sections. - -### Components {#company-content} +### Shared with Me {#shared-with-me} -Clicking **Components** opens the **My Company Components** page, where you can see all the content your company has published to the Marketplace as private. +This page contains private content shared with you by other companies who have marked you as a [guest](#guests). -Click the name of the component to access its [details page](/appstore/component-details/). +### Reviews {#my-reviews} -Click the contextual menu to access options for managing this content. +Clicking **Reviews** opens the **My Reviews** page, which contains the following tabs: -The options in this menu are the same as those for the [My Components](#my-content) section. +* **My Content** – Reviews of your components provided by other users. +* **My Reviews** – Reviews that you have written for other content. -### Groups {#content-groups} +## Company Groups {#content-groups} Clicking **Groups** opens the **Content Groups** page. This is visible to all users, but only [Mendix Admins](/control-center/company-settings/) can create and delete content groups. Both [Group Admins](#members) and Mendix Admins can manage content group members. @@ -142,15 +139,16 @@ You can configure content groups for various levels of access to your company co This table breaks down the roles and permissions for content groups: -| Roles | Manage Groups (Create & Delete) | Manage Group Members | Assign Content to Group | Manage Content (Add New Release, Manage Versions) | View & Download Group Content | View Group List | -| ------------------------------------------- | ------------------------------- | -------------------- | ----------------------- | -------------------------------------------------- | ----------------------------- | --------------- | -| Mendix Admin | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | -| Group Admin | ✘ | ✔ | ✔ | ✔ | ✔ | ✔ | -| Group Member | ✘ | ✘ | ✘ | ✔ | ✔ | ✔ | -| Organization member (not part of any group) | ✘ | ✘ | ✘ | ✘ | ✔ | ✔ | -| Guest | ✘ | ✘ | ✘ | ✘ | ✔ | ✘ | +| Roles | Manage groups (create & delete) | Manage group members | Assign content to group | Manage content (Add new release, manage releases) | View & download group content | View group list | Manage drafts | +| ------------------------------------------- | ------------------------------- | -------------------- | ----------------------- | -------------------------------------------------- | ----------------------------- | --------------- | ------------------ | +| Mendix Admin | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✘ | +| Group Admin | ✘ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | +| Group Member | ✘ | ✘ | ✘ | ✔ | ✔ | ✔ | ✔ | +| Organization member (not part of any group) | ✘ | ✘ | ✘ | ✘ | ✔ | ✔ | ✘ | +| Guest | ✘ | ✘ | ✘ | ✘ | ✔ | ✘ | ✘ | +| Developer (not part of any group) | ✘ | ✘ | ✘ | ✔ | ✔ | ✔ | ✔ | -#### Content Tab {#group-content} +### Content Tab {#group-content} On this tab, you can assign content that can only be managed by members of this group. To assign a component to a content group, click **Assign Content**, and select a Marketplace component from the dialog box. @@ -160,9 +158,9 @@ A component can only be assigned to one content group at a time. If a component Click the contextual menu to access options for managing this content. -The options in this menu are the same as those for the [My Components](#my-content) section. The **Unassign from Group** button is only available for [Group Admins](#members), and can be used to remove content from the content group. +The options in this menu are the same as those for the [Published](#published) section. The **Unassign from Group** button is only available for [Group Admins](#members), and can be used to remove content from the content group. -#### Members Tab {#members} +### Members Tab {#members} On this tab, you can enter the email address of a Mendix Platform user from your company and click **Add Member** to add them as a content group member. Content group members can manage the [content](#group-content) assigned to the group. @@ -170,7 +168,7 @@ Once a member is added, you can select their permission level: **Group Member** To remove a member, click **Remove** next to their name. -#### Guests Tab {#guests} +### Guests Tab {#guests} A guest is a Mendix Platform user from outside your organization who can download the selected private [content](#group-content) of this group. @@ -184,7 +182,7 @@ The guest must be a registered Mendix Platform user. Otherwise, they will not be To remove a guest, click **Remove**. -#### Settings Tab {#settings} +### Settings Tab {#settings} {{% alert color="info" %}} This tab is only accessible to [Group Admins](#members) and [Mendix Admins](/control-center/company-settings/). diff --git a/content/en/docs/marketplace/upload-content/_index.md b/content/en/docs/marketplace/upload-content/_index.md index ee3be8f00d3..453d137135c 100755 --- a/content/en/docs/marketplace/upload-content/_index.md +++ b/content/en/docs/marketplace/upload-content/_index.md @@ -49,7 +49,7 @@ Some fields only apply to specific component types, so follow the on-screen prom * **Public** – Your component will be available to the entire Mendix community. This content must be reviewed and approved by Mendix before it is available. - * **Private** – Your content will receive the **Private** label, and be available only via your [Company Content](/appstore/home-page/#company-content) page. + * **Private** – Your content will receive the **Private** label. On the Marketplace homepage, you can use the **Visibility** filter to choose whether to display private components. Selected private content of a content group can also be made available to [content group guests](/appstore/home-page/#guests) for download. This content is not reviewed by Mendix. @@ -218,8 +218,7 @@ To update content that has already been published, follow these steps: 1. Find the component in one of the following sections: - * **My Content** - * **Company Content** + * **Published** * **Content Group** {{% alert color="info" %}}If an existing Marketplace component is assigned to a [content group](/appstore/home-page/#content-groups) as specific content group [content](/appstore/home-page/#group-content), you can only update the component if you are a member of that group.{{% /alert %}} @@ -229,8 +228,6 @@ To update content that has already been published, follow these steps: * **Manage Versions** – This option gives you access to the **Edit** and **Unpublish** actions for each version of the component. * **Unpublish Component** - {{% alert color="info" %}}Only one draft version of a component can exist at a time, so when one draft version is in progress, another draft cannot be started. If there is a draft version in progress, click **Edit Draft** on the page where you manage the component in order to see the draft.{{% /alert %}} - 3. You can edit all component details, as described in the [Adding New Marketplace Content](#adding) section above. 4. In the **Version** section of the **Package** page, update the **Major**, **Minor**, and **Patch** numbers so that the component is saved as a new version: diff --git a/content/en/docs/releasenotes/marketplace/general-marketplace/2020.md b/content/en/docs/releasenotes/marketplace/general-marketplace/2020.md index 98d25da461d..6d71813928f 100644 --- a/content/en/docs/releasenotes/marketplace/general-marketplace/2020.md +++ b/content/en/docs/releasenotes/marketplace/general-marketplace/2020.md @@ -50,7 +50,7 @@ numberless_headings: true * Downloading private content from the App Store available in Studio Pro/Desktop Modeler has been temporarily disabled due to a security vulnerability. * You will be able to download private content from the App Store available in Studio Pro/Desktop Modeler again once a fix is released in a future [8.x](/releasenotes/studio-pro/8/), [8.6.x](/releasenotes/studio-pro/8.6/), and 7.23.x release. This functionality will then only be available in those specific versions with the fix and subsequent versions. This functionality will not be available again for the App Store in Desktop Modeler version 6. - * You can continue downloading the latest version of private App Store content from the [Company Content](/appstore/home-page/#company-content) page in the [Mendix Marketplace](https://marketplace.mendix.com/) and use it in the respective versions of Studio Pro/Desktop Modeler. + * You can continue downloading the latest version of private App Store content from the **Company Content** page in the [Mendix Marketplace](https://marketplace.mendix.com/) and use it in the respective versions of Studio Pro/Desktop Modeler. ## February 2020 diff --git a/content/en/docs/releasenotes/marketplace/general-marketplace/2026.md b/content/en/docs/releasenotes/marketplace/general-marketplace/2026.md index 930833b4c44..96c0cfbf9a9 100644 --- a/content/en/docs/releasenotes/marketplace/general-marketplace/2026.md +++ b/content/en/docs/releasenotes/marketplace/general-marketplace/2026.md @@ -7,6 +7,21 @@ weight: 1 numberless_headings: true --- +## June 2026 + +### June 18, 2026 + +#### New Features + +* We have released a new API which allows you to upload new releases of existing components. In the future, this API will also enable you to upload completely new components. + For details, refer to [Publish API](/apidocs-mxsdk/apidocs/publish-api/). +* You can now create more than one draft for the same component. +* In an effort to streamline the Marketplace user interface, we have made the following updates and additions: + + * The **Personal** section has been renamed to **Manage Components**. It includes a new page, named **Published**, which contains all the components that you can manage. + * The **My Company Components** page no longer exists. Its content is now consolidated within the newly added **Published** page, under the **Personal** section. + * The Marketplace homepage **Visibility** filter now includes the **From My Company** option, which allows you to choose whether you want to display components uploaded by your company. + ## May 2026 ### May 28, 2026 diff --git a/static/openapi-spec/marketplace-publish.yaml b/static/openapi-spec/marketplace-publish.yaml new file mode 100755 index 00000000000..39b9ea87408 --- /dev/null +++ b/static/openapi-spec/marketplace-publish.yaml @@ -0,0 +1,474 @@ +openapi: "3.0.0" +info: + version: 1.0.0 + title: Publish API + description: The API to upload new releases of existing Marketplace components. + termsOfService: https://www.mendix.com/terms-of-use/ + contact: + name: Mendix Support + url: 'https://support.mendix.com' +servers: + - url: "https://marketplace-api.mendix.com/v1" +paths: + /releases/{releaseId}: + get: + tags: + - components + summary: Returns the status and metadata of a specific release. + description: |- + Retrieves the current status and metadata of a specific release. This allows Marketplace component publishers to monitor the release status progress and make informed decisions about next steps. + + **Authorization:** The user must have access to view the release. + + **Status Values:** + - `Draft`: The release is in `Draft` state and hasn't been submitted for review or published yet. + - `InReview`: The release is under review. + - For private components, it is ready to be reviewed by a Mendix Admin if private approval is enabled for the related company. + - For public components, it undergoes security scanning and review by the security system. + - `Declined`: The release is declined. + - For private components, the release is declined by a Mendix Admin. + - For public components, the security checks did not pass for the release. + - `Published`: The release is published to the Marketplace and ready to be consumed. + operationId: getReleaseStatus + parameters: + - $ref: '#/components/parameters/releaseId' + responses: + '200': + description: successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/releaseStatus' + '401': + $ref: '#/components/responses/error401' + '404': + $ref: '#/components/responses/error404' + '500': + $ref: '#/components/responses/error500' + delete: + tags: + - components + summary: Unpublishes a specific release of the component. + description: |- + Unpublishes a release from Marketplace. This allows component developers to remove releases when needed, either for corrections or for component retirement. + + **Supported States:** It is supported for releases in any state (`Draft`, `InReview`, `Declined`, `Published`). + + **Authorization:** The user must have access to manage the component. The user is a developer of the component and meets user group rules. + + **Special Cases:** + - If the client attempts to unpublish the only remaining release of a non-deprecated component, a `409 Conflict` response is returned. The component must first be deprecated before deleting its last remaining release. + - If the last remaining release of a deprecated component is unpublished, the whole component is automatically unpublished and removed from Marketplace. + operationId: unpublishRelease + parameters: + - $ref: '#/components/parameters/releaseId' + responses: + '204': + description: The release was successfully unpublished. No content is returned. + '401': + $ref: '#/components/responses/error401' + '404': + $ref: '#/components/responses/error404' + '409': + $ref: '#/components/responses/error409' + '500': + $ref: '#/components/responses/error500' + /components/{componentId}/releases: + post: + tags: + - components + summary: Creates a new release for a component. + description: |- + Creates a new release in `Draft` state for a specific component. This allows Marketplace component publishers to prepare a new version of their component. + + **Authorization:** The user must have permission to create releases for the component. The user is a developer of the component and meets user group rules. + + **Parameters:** + - The componentId: The corresponding component must exist in Marketplace. + + **Response:** Returns HTTP 201 Created with a Location header containing the URI of the created release. + operationId: createRelease + parameters: + - $ref: '#/components/parameters/componentId' + requestBody: + description: |- + The release metadata for the new release. Provide the following fields in the request body. + + The `versionNumber` field must include the version number of the release. It must be unique across all releases (no existing release with the same version in any state), and must follow the semantic versioning format: `major.minor.patch` (for example, `2.0.0`). + + The `mendixVersion` field must include the Mendix Studio Pro version the release is built on. It must follow the semantic versioning format: `major.minor.patch` (for example, `11.0.0`). + + The `releaseNotes` field must include human-readable information about the release. This field is required and must be a non-empty string describing the changes introduced in the release. + + The `publishManually` field must include a boolean flag that controls what happens after a source file is uploaded using the `PUT /releases/{releaseId}/source-file` endpoint. If `publishManually` is false or omitted (default), the release may be automatically submitted for processing, and will transition to either `InReview` or `Published` depending on the component and Marketplace rules. If `publishManually` is true, the release remains in `Draft` after the source file is uploaded, and must be manually published by the user. + + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/createReleaseRequest' + responses: + '201': + description: The release was successfully created and it is in `Draft` state. The `Location` header contains the URI of the new release. + headers: + Location: + description: The URI of the newly created release (for example, `https://marketplace-api.mendix.com/v1/releases/{releaseId}`). + schema: + type: string + example: "https://marketplace-api.mendix.com/v1/releases/{releaseId}/v1/releases/3fa85f64-5717-4562-b3fc-2c963f66afa6" + '400': + description: |- + The request contains invalid or missing data. + + Possible reasons include: + - Invalid `versionNumber` format. This must be `major.minor.patch` (for example, `2.0.0`). + - Invalid `mendixVersion` format. + - Missing required fields (`versionNumber`, `mendixVersion`, `releaseNotes`) + - Empty request body. + content: + application/json: + schema: + $ref: '#/components/schemas/error' + examples: + invalid-version-format: + value: + error: + code: 400 + message: Bad Request + detail: "Invalid version number format. Must be `major.minor.patch` (for example, 2.0.0)." + missing-required-field: + value: + error: + code: 400 + message: Bad Request + detail: "Missing required field: versionNumber" + '401': + $ref: '#/components/responses/error401' + '404': + $ref: '#/components/responses/error404' + '409': + description: |- + A release with the same version number already exists. + + This error occurs when attempting to create a release with a `versionNumber` that is already used by another release, which can be in any state: `Draft`, `InReview`, `Declined`, or `Published`. + content: + application/json: + schema: + $ref: '#/components/schemas/error' + examples: + duplicate-version: + value: + error: + code: 409 + message: Conflict + detail: "A release with the same version number already exists." + '500': + $ref: '#/components/responses/error500' + + /releases/{releaseId}/source-file: + put: + tags: + - components + summary: Uploads or updates the source file for a release. + description: |- + Uploads or updates the source file for a specific release. This allows Marketplace component publishers to provide the component package and to transition the release from `Draft` or `Declined` to `InReview` or `Published`. + + **Authorization:** The user must have access to manage the component. The user is a developer of the component and meets user group rules. + + **Validation:** + - A release with the given `releaseId` must exist in Marketplace. + - The release must be in `Draft` or `Declined`. Cannot update the source file if it is already in `InReview` or `Published`. + - The source file is validated (for example, widget validation, file name extension validation). + + **State Transition:** + After a successful upload, the release transitions to one of the following states: + - `Draft` + - If the `publishManually` field was set to `true` when the release was created. + - `InReview` + - Mendix Admin approval is required (for private components) or + - A security scan is required (for public components). + - `Published` + - Mendix Admin approval is not required (for private components) and + - A security scan is not required. + + A release in the `InReview` state is automatically published to Marketplace and transitions to `Published` once all required review conditions have been satisfied. + + **Supported File Types:** + - For platform-supported components and private components, any file type. + - For non-platform-supported components and public components, only the following file types are supported: + - `.mpk` - Mendix Package file + - `.mxmodule` - Mendix Module file + - `.mxsolution` - Mendix Solution file + operationId: uploadReleaseSourceFile + parameters: + - $ref: '#/components/parameters/releaseId' + - $ref: '#/components/parameters/fileName' + requestBody: + description: The binary content of the source file to upload. + required: true + content: + application/octet-stream: + schema: + type: string + format: binary + responses: + '202': + description: The source file was successfully uploaded and the release is now in `InReview` or `Published`. + '400': + description: |- + The request contains invalid data or the validation failed. + + Possible reasons include: + - Invalid file format or extension + - Widget validation errors (for example, widget name already taken) + - Missing required header (file-name) + content: + application/json: + schema: + $ref: '#/components/schemas/error' + examples: + widget-name-taken: + value: + error: + code: 400 + message: Bad Request + detail: "Widget name is already taken." + invalid-file-extension: + value: + error: + code: 400 + message: Bad Request + detail: "Invalid file extension." + '401': + $ref: '#/components/responses/error401' + '404': + $ref: '#/components/responses/error404' + '409': + description: |- + The request could not be completed due to a conflict with the current state of the release. + + This error occurs when trying to upload a source file for a release that is already in `InReview` or `Published`. + content: + application/json: + schema: + $ref: '#/components/schemas/error' + examples: + invalid-state: + value: + error: + code: 409 + message: Conflict + detail: "The source file cannot be updated for the release with `InReview` or `Published` state." + '500': + $ref: '#/components/responses/error500' + +components: + parameters: + componentId: + name: componentId + in: path + description: "This is the numeric ID of the component." + required: true + schema: + type: integer + format: int64 + example: 12345 + releaseId: + name: releaseId + in: path + description: "This is the UUID of the release." + required: true + schema: + type: string + format: uuid + fileName: + name: file-name + in: header + description: "The name of the source file being uploaded, including the file extension (for example, 'MyWidget.mpk', 'MyModule.mxmodule'). Supported extensions are: .mpk, .mxmodule, .mxsolution." + required: true + schema: + type: string + example: "MyComponent.mpk" + + responses: + error400: + description: |- + The request may contain invalid or missing data. + + The error message gives additional information. + content: + application/json: + schema: + $ref: '#/components/schemas/error' + examples: + example-400: + value: + error: + code: 400 + message: Bad Request + detail: "The request could not be processed by the server because the input parsing/processing failed." + error401: + description: |- + No usable authentication credentials were found. + + The error message gives additional information. + content: + application/json: + schema: + $ref: '#/components/schemas/error' + examples: + example-401: + value: + error: + code: 401 + message: Unauthorized + error404: + description: |- + The required item could not be found. + + The error message provides additional information. + content: + application/json: + schema: + $ref: '#/components/schemas/error' + examples: + example-404: + value: + error: + code: 404 + message: Not Found + error409: + description: |- + The request could not be completed due to a conflict with the current state of the resource. + + The error message provides additional information. + content: + application/json: + schema: + $ref: '#/components/schemas/error' + examples: + example-409: + value: + error: + code: 409 + message: Conflict + detail: "Cannot unpublish the only remaining release of a non-deprecated component. Deprecate the component first before deleting its last release." + error500: + description: |- + An error occurred during the processing of the request. + + The error message provides additional information. + content: + application/json: + schema: + $ref: '#/components/schemas/error' + examples: + example-500: + value: + error: + code: 500 + message: Internal Server Error + detail: "Something went wrong." + schemas: + createReleaseRequest: + type: object + description: "Request body for creating a new release." + required: + - versionNumber + - mendixVersion + - releaseNotes + properties: + versionNumber: + type: string + pattern: "^\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}$" + example: "2.0.0" + description: "The `versionNumber` is the version number of the release. It must be unique across all releases (in any state) and must follow the semantic versioning format: `major.minor.patch` (for example, `2.0.0`)." + mendixVersion: + type: string + pattern: "^\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}$" + example: "10.6.0" + description: "The `mendixVersion` is the Mendix Studio Pro version the release is built on. It must follow the semantic versioning format: `major.minor.patch` (for example, `11.0.0`)." + releaseNotes: + type: string + example: "Bug fixes and performance improvements." + description: "The `releaseNotes` contains human-readable information about the release. This field is required and must be a non-empty string describing the changes in this release." + publishManually: + type: boolean + default: false + example: true + description: "The `publishManually` is a boolean flag that controls the publishing behavior after a source file upload. If `true`, the release remains in `Draft` and must be published manually. If `false` (default), the release may be automatically submitted for processing and transition to `InReview` or `Published` depending on Marketplace rules." + + error: + type: object + properties: + code: + type: integer + minimum: 0 + example: 400 + message: + type: string + example: Bad Request + detail: + type: string + example: Malformed request body + + releaseStatus: + type: object + description: "The status and metadata of a specific release. This schema is used to track the lifecycle state of a release from draft to publication." + required: + - name + - status + - releaseId + - versionNumber + - minSupportedMendixVersion + properties: + name: + type: string + example: "3d Viewer" + description: "This is the name of the release of the component." + status: + type: string + enum: + - Draft + - InReview + - Declined + - Published + example: "Draft" + description: "The current status of the release. Possible values are: `Draft` (being prepared), `InReview` (submitted for review), `Declined` (reviewed and declined), `Published` (approved and publicly available)." + releaseId: + type: string + format: uuid + example: "3fa85f64-5717-4562-b3fc-2c963f66afa6" + description: "This is the UUID of the release." + versionNumber: + type: string + pattern: "^\\b((?:\\d{1,3}|1000)(?:\\.\\d{1,3}|\\.1000){0,2})(?:-[a-zA-Z]+)?\\b$" + example: '10.1.1' + description: "This is the version number of the release. The format is `major.minor.patch` (for example, `2.0.0`)." + minSupportedMendixVersion: + type: string + pattern: "^\\b((?:\\d{1,3}|1000)(?:\\.\\d{1,3}|\\.1000){0,2})\\b$" + example: '10.1.1' + description: "This is the Studio Pro version selected during the onboarding. This means that any Studio Pro version equal to or greater than this version is compatible with the latest release of the component." + publicationDate: + type: string + format: yyyy-MM-ddTHH-mm-ssZ + example: '2023-09-01T09:04:00Z' + description: "The date when the release was published. This field is only present for releases with the `Published` status." + releaseNotes: + type: string + example: "These are the release notes for this release." + description: "The release notes for this release." + + securitySchemes: + PersonalAccessToken: + name: Authorization + type: apiKey + in: header + description: 'For more information about requesting and using a token, refer to the [documentation](https://docs.mendix.com/portal/user-settings/#pat).
The header must be set to `MxToken `.' + +security: + - PersonalAccessToken: [] + +tags: + - name: components