• English

      • Calling sub-app APIs

      App supervisorEnterprise Edition+

      In a multi-app setup, each sub-app has its own independent APIs. When calling a sub-app API, the entry app needs to know which sub-app the request should be routed to.

      For example, a main app API is usually:

      GET /api/users:list

      /api is the default API prefix and can be customized with the API_BASE_PATH environment variable.

      To call the same API in a sub-app, specify the sub-app name in the request.

      Use a path prefix

      Use the /api/__app/<appName>/ prefix to call sub-app APIs:

      GET /api/__app/a_xxx/users:list

      Where:

      • a_xxx is the sub-app name
      • users:list is the resource and action to call
      • /api is the current system's API base path

      Query parameters can be appended as usual:

      GET /api/__app/a_xxx/users:list?page=1&pageSize=20

      This approach is explicit and works well when sub-app APIs are accessed through the entry app in multi-environment deployments.

      Specify the sub-app with a request header

      If the caller already uses a fixed /api/... address, specify the sub-app with the X-App request header:

      curl \
  -H "X-App: a_xxx" \
  http://localhost:13003/api/users:list

      This is suitable for backend service calls, or when a frontend request utility already centralizes API URLs and only needs an additional header.

      Specify the sub-app with a query parameter

      You can also specify the sub-app with the __appName query parameter:

      GET /api/users:list?__appName=a_xxx

      If there are other query parameters, pass them together:

      GET /api/users:list?__appName=a_xxx&page=1&pageSize=20

      In general, the path prefix or request header is clearer because the target sub-app is more explicit.

      API address in multi-environment deployments

      In multi-environment deployments, there is usually an entry app and multiple runtime environments.

      For example:

      • Entry app address: http://localhost:13003
      • Runtime environment address: http://localhost:14000

      When calling sub-app APIs, it is recommended to access them through the entry app:

      GET http://localhost:13003/api/__app/a_xxx/users:list

      The entry app routes the request to the corresponding sub-app according to the app configuration. If you clearly know which runtime environment to access, you can also call through that environment address.

      GET http://localhost:14000/api/__app/a_xxx/users:list

      Sub-app custom domains

      If a sub-app has its own access domain, you can also call that sub-app's APIs directly through that domain:

      GET https://app-example.example.com/api/users:list

      If you want to go through the entry app uniformly, continue using the entry app's /api/__app/<appName>/... address.

      Authentication

      When calling sub-app APIs, permission checks are still based on the target sub-app.

      This means:

      • A sign-in state or access token valid for the sub-app is required
      • The main app sign-in state does not automatically equal API permissions in the sub-app

      If the request does not carry valid authentication information, the sub-app returns an unauthenticated or unauthorized error according to its own authentication configuration.