it-bens/deqar-api-client

WebAPI和SubmissionAPI的DEQAR客户端。

维护者

详细信息

github.com/it-bens/deqar-api-client

源代码

问题

安装: 9

依赖: 1

建议者: 0

安全性: 0

星标: 0

关注者: 1

分支: 0

开放问题: 1

类型:package

v0.2.0 2022-01-03 23:48 UTC

Requires

Requires (Dev)

MIT 597e0e0a5b7ac2cd33df4805bed998a0a697f2a5

  • Martin Bens <martin.bens.woop@it-bens.de>

This package is auto-updated.

Last update: 2024-09-15 07:35:49 UTC

README

Maintenance Status CI Status codecov

什么是DEQAR？

DEQAR是欧洲质量保障注册（EQAR）的数据库。它提供了关于欧洲高等教育机构、质量保障机构和它们的报告及工作信息。

信息可以通过DEQAR REST API检索

还有一个API，可以用于提交质量保障报告

如何安装此包？

该包可以通过Composer安装

composer require it-bens/deqar-api-client

它需要至少PHP 8，并在PHP 8.1上进行了测试。

哪个API客户端提供了此包？

此包包含WebAPI和SubmissionAPI的客户端。

WebApi为机构、国家、机构和报告提供端点。总有一个端点用于检索资源集合，以及一个或多个用于检索更详细资源的端点。目前，此客户端主要使用集合端点，并提供通过唯一标识符过滤它们以检索单个较不详细资源的方法。

还有一个WebApi客户端的缓存实现。它装饰了普通WebApi客户端。

提交API仅实现两个端点：提交/更新报告和删除报告。提交过程涉及对提供数据的几个服务器端检查。一些检查是立即执行的，如果数据无效，则会导致错误响应。其他检查是异步进行的，这意味着报告可以在成功提交后标记为无效。

如何使用客户端？

Web API客户端

WebApiClientInterface的实现提供了一个静态的create方法，该方法接受所需的最少数据，并自行创建HTTP客户端和序列化器等组件。

use ITB\DeqarApiClient\WebApi\WebApiClient;

$webApiClient = WebApiClient::create($_ENV['DEQAR_API_USERNAME'], $_ENV['DEQAR_API_PASSWORD']);

CachedWebApiClient装饰了一个WebApiClientInterface实现。

use ITB\DeqarApiClient\WebApi\CachedWebApiClient;

$cachedWebApiClient = CachedWebApiClient::create($webApiClient);

WebApiClientInterface提供了以下方法

use ITB\DeqarApiClient\WebApi\WebApiClient;

$webApiClient = new WebApiClient($username, $password, $httpClient, $serializer);

// returns an activity array (extracted from the agencies)
$activities = $webApiClient->getActivities();

// returns a single activity or null (identified by 'id' or 'activity' property)
$activity = $webApiClient->getActivity($identifier);

// returns an agency array
$agencies = $webApiClient->getAgencies();

// returns a single agency or null (identified by 'id', 'deqar_id' or 'name_primary' property)
$agency = $webApiClient->getAgencySimple($identifier);

// returns a country array
$countries = $webApiClient->getCountries();

// returns an institution array ('limit' and 'offset' can reduce the results)
$institutions = $webApiClient->getInstitutions(limit: 500, offset: 200);

// returns a single institution or null (identified by 'deqar_id' or 'eter_id' property)
$institution = $webApiClient->getInstitutionSimple();

// returns a report array ('limit' and 'offset' can reduce the results)
$reports = $webApiClient->getReports(limit: 500, offset: 200);

响应通过Symfony Serializer映射到DTO。用于检索单个较不详细资源版本的方法依赖于过滤集合响应。为了防止不必要的DEQAR API调用，请使用CachedWebApiClient。客户端将其结果缓存1天（86400秒）。

内部，使用Symfony HttpClientInterface进行请求。通过WebApiClient的静态create方法，创建了一个带有Symfony HttpClient和Symfony Serializer（带有必要的规范化器和提取器）的实例。然而，构造函数是公开的，可以用来传递自定义的HttpClientInterface和SerializerInterface实例。

提交API客户端

SubmissionApiClientInterface的实现提供了一个静态的create方法，该方法接受所需的最少数据，并自行创建HTTP客户端、验证器和序列化器等组件。

use ITB\DeqarApiClient\SubmissionApi\SubmissionApiClient;

$submissionApiClient = SubmissionApiClient::create($_ENV['DEQAR_API_USERNAME'], $_ENV['DEQAR_API_PASSWORD'], test: true);

⚠ 使用 DEQAR 沙箱进行开发和测试环境时，test 参数非常重要。目前，DEQAR 凭证对沙箱和生产环境有效。如果没有 test 参数，SubmissionApiClient 将会将数据发送到 DEQAR 的公开版本！

为了防止发送无效数据，此客户端内部对输入进行了多个约束的验证。数据必须以 SubmitReportRequest 对象的形式提供，该对象使用 Symfony 验证器进行验证。

use ITB\DeqarApiClient\SubmissionApi\Model\SubmitReportRequest;

$request = new SubmitReportRequest(...);
$response = $this->submissionApiClient->submitReport($request);

以下约束应用于 SubmitReportRequest

  • agency：不能为空，必须在 DEQAR 中存在（通过 WebAPI 进行检查）
  • activity：不能为空，必须在 DEQAR 中存在（通过 WebAPI 进行检查）
  • status：'必选 EQA 系统的一部分' 或 '自愿'
  • decision：'正面'、'有条件或限制的正面'、'负面' 或 '不适用'
  • validFrom：有效日期
  • files：如果提供，所有数组元素都必须是有效的 FileRequest 对象
  • institutions：如果提供，所有数组元素都必须是有效的 InstitutionRequest 对象
  • programmes：如果提供，所有数组元素都必须是有效的 ProgrammeRequest 对象
  • id：可以为空，但不能为空
  • contributingAgencies：可以为空，但所有数组元素都必须是有效的机构（如上所述）
  • localIdentifier：可以为空，但长度从 1 到 255 个字符
  • summary：可以为空，但不能为空
  • validTo：可以为空，但必须是有效日期
  • links：可以为空，但所有数组元素都必须是有效的 LinkRequest 对象
  • comment：可以为空，但不能为空
  • 必须根据 (https://docs.deqar.eu/report_data/#activity) 提供一定数量的机构和项目

请求的子对象也进行验证

  • FileRequest:
    • originalLocation：长度从 1 到 500 个字符，指向远程 PDF 文件的 URL（通过返回的内容类型头进行检查）
    • languages：至少一个 3 个字母的国家代码
    • displayName：可以为空，但长度从 1 到 255 个字符
  • InstitutionRequest:
    • deqarId 或（排他性）eterId 必须提供，并指向一个存在的机构
  • LinkRequest:
    • link：长度从 1 到 255 个字符
    • displayName：可以为空，但长度从 1 到 200 个字符
  • ProgrammeRequest:
    • namePrimary：长度从 1 到 255 个字符
    • identifiers 如果提供，所有数组元素都必须是有效的 ProgrammeIdentifierRequest 对象
    • qualificationPrimary：可以为空，但长度从 1 到 255 个字符
    • alternativeNames：如果提供，所有数组元素都必须是有效的 ProgrammeNameRequest 对象
    • nqfLevel：可以为空，但长度从 1 到 255 个字符
    • qfEheaLevel：可以为空，但 '短期循环'、'第一循环'、'第二循环' 或 '第三循环'
    • 至少有一个级别不能为空（NQF 级别或 QF EHEA 级别）

为了允许更新报告，可以提供 report_id。

submitReport 和 deleteReport 方法返回响应对象。它们包含一个标志，指示请求是否成功以及返回的数据。数据包含有关服务器端违反的约束的重要信息。

可以与此包一起使用哪些包？

目前，计划了两个包

  • Symfony 包以提供作为服务的客户端
  • DEQAR 合同包以提供 API 结果的抽象实体和存储库，可以轻松本地持久化

如何测试这个包？

该包为 API 客户端提供了 PHPUnit 测试。在本地环境中，可以通过 docker 执行测试和静态代码分析。

./development.sh docker-build
docker-compose run --rm -T phpunit php vendor/bin/phpunit --configuration phpunit.xml tests
docker-compose run --rm -T phpunit php -d memory_limit=2G vendor/bin/phpstan analyse src tests --level 8

PHPUnit 测试和 PHPStan 的静态代码分析也通过 GitHub actions 在任何推送或 PR 上执行。GitHub Actions CI 使用所有支持的 PHP 版本和所有支持的 Symfony 版本运行。

贡献

我真的很高兴软件开发社区喜欢开源，就像我一样！♥

因此，我非常感激每一个被提出的（最好是建设性的）问题和每一个提供其他或更好代码的pull request。

你们都令人叹为观止！

特别感谢

这个项目由欧洲质量保证注册（EQAR）和欧盟资助，对此我非常感激！