# Packages from other Jadpo apps

Your app can call another Jadpo app's API through a package made from
that app's OpenAPI document, exactly, with nothing to correct by hand.

## What the document carries

Jadpo's OpenAPI documents carry `x-jadpo` fields that say what plain
OpenAPI can't: `x-jadpo-changes` (the operation changes something),
`x-jadpo-idempotency`, `x-jadpo-failure` (each failure's `code` and
`kind`), `x-jadpo-constraints` and `x-jadpo-events`
([OpenAPI](openapi.md)). Other tools ignore them. Every API serves
its document at `<prefix>/openapi.json` by default.

The OpenAPI importer uses these fields whenever it finds them, so
importing a Jadpo app's document gives an exact package that needs no
corrections or recordings. A provider that isn't a Jadpo app is imported
from its plain OpenAPI. There is one importer and one package format.

## Getting the package

- **In one repository**, `jadpo package add ../orders` reads the other
  app's generated OpenAPI.
- **Across repositories**, the other app's package comes from git, like
  any private package.
- **For another company's public API**,
  `jadpo package add https://api.orders.example/v1` fetches the document
  it serves.

Each is read once, when the package is added or updated, then pinned in
the lock with its source and digest.

## Connecting to it

The result is an ordinary installed provider package in
`packages/<name>/<version>/`. It has no fixed host, so the connection
gives `host:`, and its credential is a service key
([Service credentials](service-credentials.md)):

```jadpo
// app.jadpo
orders: {
    package: Orders.v1
    domains: [fulfilment]
    host: config.orders_url
    credential: config.orders_service_key
}
```

At runtime the two apps meet only over HTTP, and the called app can't
tell what made the call.

## When the other app changes

An additive change to the other API regenerates as a minor version
through `jadpo package update`, and `jadpo check` says when yours is out
of date. A breaking change, which already needs an acceptance in the
other app ([The public API record](the-public-api-record.md)),
becomes a new major version, installed side by side while callers move.

In one repository, `jadpo check` in the called app reads the other apps'
locks and reports which of their calls a change breaks, before it merges.

> Reporting breaks across apps isn't built yet.