2.4.1 <apps:section>

Within <apps:section>, you specify identification and parameters for your application:

• <app id="..." version="..." coreVersion="...">

  • id: A unique identifier for your application (e.g., pim, marketing, warehouse).

  • version: The application’s version (e.g., 1.0, 2.3).

  • coreVersion: The minimum or tested Retailys core version your app is compatible with (e.g., 3.2).

• <about>: Basic metadata—application label, description, author name, contact info (phone, email), and other details.

• <dependencies>: Used if your application relies on other applications (commonly datanest and dashboard). For instance:

  <dependencies>
    <apps>
      <depends on="datanest" version="0.1"/>
      <depends on="dashboard" version="0.1"/>
    </apps>
  </dependencies>

• <interface>: Defines where and how the Retailys core can reach your application’s private API:

  • base="..." sets the base URL of your service (e.g., https://pim.retailys.com).

  • type="..." indicates the interface type (often openapi).

  • <methods> lists the mandatory endpoints you must implement:

    • <ping url="..."/> – checked periodically by the core to ensure your app is up.

    • <enroll url="..."/> – used when registering the app with the core.

    • <remove url="..."/> – called when the app is removed/uninstalled.

    • <section url="..."/> – processes additional sections from the manifest (e.g., <datanest:section>, <dashboard:section>).

    • <response url="..."/> – endpoint receiving public API requests that the Retailys API Gateway forwards.

    • <alert url="..."/> – used by the core to notify your app about critical errors or warnings.

• <gateway>: If your app wants to expose public API endpoints, you declare them here. For example, if you have an OpenAPI spec in JSON or YAML:

  <gateway type="openapi" format="yaml" source="/openapi.yaml"/>

  This instructs the Retailys Gateway to fetch your openapi.yaml file and merge it into the official public API.

• <section>: You can include extra files (XSD, schemas, etc.) if your app or blueprint needs them:

  <section type="xsd" format="xml" source="/section.xsd"/>

Simplified example:

<apps:section xmlns:apps="https://blueprint.retailys.com/blueprint.xsd">
    <app id="pim" version="1.0" coreVersion="0.1">
        <about>
            <label>PIM (Product Information Management)</label>
            <desc>Application for rich product data management.</desc>
            <author>Retailys</author>
            <url>https://pim.retailys.com</url>
            <phone>[phone]</phone>
            <email>[email protected]</email>
        </about>
        <dependencies>
            <apps>
                <depends on="datanest" version="0.1"/>
                <depends on="dashboard" version="0.1"/>
            </apps>
        </dependencies>
        <interface base="https://pim.retailys.com" type="openapi">
            <security>
                <oauth2/>
            </security>
            <methods>
                <ping url="/api/ping"/>
                <enroll url="/api/enroll"/>
                <remove url="/api/remove"/>
                <section url="/api/section"/>
                <response url="/api/response"/>
                <alert url="/api/alert"/>
            </methods>
        </interface>
    </app>
    <gateway type="openapi" format="yaml" source="/openapi.yaml"/>
    <section type="xsd" format="xml" source="/section.xsd"/>
</apps:section>