# 5. API Reference

xly exposes three distinct HTTP surfaces, hosted in three separate Spring
Boot services. Each is documented on its own page below; the conceptual
overview lives in [concepts/api-surface](../concepts/api-surface.md).

| Page | Service | Context path | Use when |
|---|---|---|---|
| [Internal API](internal.md) | `xlyEntry` | `/xlyEntry` | You are extending the SPA or maintaining the framework runtime. |
| [External API](external.md) | `xlyApi` | `/xlyApi` | You are integrating an outside system that calls xly. |
| [Webhooks](webhooks.md) | `xlyInterface` | `/xlyInterface` | A third-party system needs to push events into xly. |
| [Messaging](messaging.md) | `xlyEntry` + `xlyErpJms*` | n/a (ActiveMQ / RocketMQ) | An asynchronous, fan-out integration is more appropriate than a synchronous HTTP call. |
| [Notifications](notifications.md) | `xlyMsg` (consumed as a library by `xlyEntry`, `xlyBusinessService`, `xlyInterface`, `xlyFlow`) | n/a (DingTalk / WeChat / email APIs) | A business event needs to push a chat-platform message or email to a user. |

## Reading order

If you arrived here as an external integrator, start with
[External API](external.md). If you're a Java developer extending the
framework, start with [Internal API](internal.md) (most of the universal
CRUD machinery is documented in the
[Maintainer runtime chapter](../reference/maintainer/runtime.md);
this chapter cross-links to it).

## Cross-cutting facts

- **Auth.** Internal calls use the SPA's session cookie + the
  `@CurrentUser` argument resolver. External calls use bearer tokens
  obtained from `/xlyApi/token/getToken`. Webhooks have per-channel
  conventions (signature header, query-param secret).
- **Tenant scoping.** Every authenticated controller method, in every
  service, runs `RequestAddParamUtil.me().addParams(params, userInfo)`
  before doing any work — see
  [the multi-tenancy concept page](../concepts/multi-tenancy.md). A
  request that bypasses this is a multi-tenant bug.
- **Logging.** External calls are logged to `sysapilog`; internal calls
  use the framework's standard `syslog4j` setup; webhooks log to
  whatever the per-channel handler chooses.