API 应用调用外部 API 时的流程叫做**回调**。因为外部开发者编写的软件发送请求至您的 API，然后您的 API 要进行回调，并把请求发送至外部 API。

此时，我们需要存档外部 API 的*信息*，比如应该有哪些*路径操作*，返回什么样的请求体，应该返回哪种响应等。

## 使用回调的应用

示例如下。

假设要开发一个创建发票的应用。

发票包括 `id`、`title`（可选）、`customer`、`total` 等属性。

API 的用户 （外部开发者）要在您的 API 内使用 POST 请求创建一条发票记录。

（假设）您的 API 将：

* 把发票发送至外部开发者的消费者
* 归集现金
* 把通知发送至 API 的用户（外部开发者）
    * 通过（从您的 API）发送 POST 请求至外部 API （即**回调**）来完成

## 常规 **FastAPI** 应用

    // GET /api/admin/backup/files
    @Execute
    public JsonResponse<ApiResult> files() {
        final List<Map<String, String>> list = getBackupItems();
        return asJson(new ApiBackupFilesResponse().files(list).total(list.size()).status(ApiResult.Status.OK).result());
    }

    // GET /api/admin/backup/file/{id}
    @Execute
    public StreamResponse get$file(final String id) {

        return asJson(
                new ApiResult.ApiConfigsResponse<EditBody>().settings(list.stream().map(this::createEditBody).collect(Collectors.toList()))
                        .total(pager.getAllRecordCount()).status(ApiResult.Status.OK).result());
    }

    // GET /api/admin/duplicatehost/setting/{id}
    @Execute
    public JsonResponse<ApiResult> get$setting(final String id) {

        return asJson(new ApiResult.ApiLogsResponse<EditBody>().logs(list.stream().map(this::createEditBody).collect(Collectors.toList()))
                .total(pager.getAllRecordCount()).status(ApiResult.Status.OK).result());
    }

    // GET /api/admin/crawlinginfo/log/{id}
    @Execute
    public JsonResponse<ApiResult> get$log(final String id) {

        final List<FailureUrl> list = failureUrlService.getFailureUrlList(pager);
        return asJson(new ApiResult.ApiLogsResponse<EditBody>().logs(list.stream().map(this::createEditBody).collect(Collectors.toList()))
                .total(pager.getAllRecordCount()).status(ApiResult.Status.OK).result());
    }

    // GET /api/admin/failureurl/log/{id}
    @Execute
    public JsonResponse<ApiResult> get$log(final String id) {

		d.replaceHashed(path, nil, *flat)
		return
	}
	total := d.totalChildrenRec(path.Key())
	if total < limit {
		return
	}

	// Appears to be printed with _MINIO_SERVER_DEBUG=off
	// console.Debugf(" %d children found, compacting %v\n", total, path)

	leaves := make([]struct {
		objects uint64
		path    dataUsageHash
	}, total)
	// Collect current leaves that have children.
	leaves = leaves[:0]

## An app with callbacks

Let's see all this with an example.

Imagine you develop an app that allows creating invoices.

These invoices will have an `id`, `title` (optional), `customer`, and `total`.

The user of your API (an external developer) will create an invoice in your API with a POST request.

Then your API will (let's imagine):

* Send the invoice to some customer of the external developer.

## Um aplicativo com callbacks

Vamos ver tudo isso com um exemplo.

Imagine que você tem um aplicativo que permite criar faturas.

Essas faturas terão um `id`, `title` (opcional), `customer` e `total`.

O usuário da sua API (um desenvolvedor externo) criará uma fatura em sua API com uma solicitação POST.

Então sua API irá (vamos imaginar):

* Enviar uma solicitação de pagamento para o desenvolvedor externo.

    int readFsFullSizeInformationWireFormat( byte[] buffer, int bufferIndex )
    {
        int start = bufferIndex;
        
        SmbInfoAllocation info = new SmbInfoAllocation();
        
        // Read total allocation units.
        info.alloc = readInt8( buffer, bufferIndex );
        bufferIndex += 8;
        
        // read caller available allocation units 
        info.free = readInt8( buffer, bufferIndex );

        with:
          python-version: "3.10"
          # Issue ref: https://github.com/actions/setup-python/issues/436
          # cache: "pip"
          # cache-dependency-path: pyproject.toml
      - name: Install build dependencies
        run: pip install build
      - name: Build distribution
        env:
          TIANGOLO_BUILD_PACKAGE: ${{ matrix.package }}
        run: python -m build