Download the PHP package it-bens/deqar-api-client without Composer

DEQAR API Client(s)

What is DEQAR?

DEQAR is the database of EQAR, the European Quality Assurance Register for Higher Education. It provides information about european institutions for higher education, the quality assurance agencies, their reports and their work.

The information can be retrieved from the DEQAR REST APIs:

• https://backend.deqar.eu/connectapi/v1/swagger/ (partially public)
• https://backend.deqar.eu/webapi/v2/swagger/ (authentication required)

There is also an API, which can be used to submit quality assurance reports:

• https://backend.deqar.eu/submissionapi/v1/swagger/ (authentication required)

How to install this package?

The package can be installed via Composer:

It requires at least PHP 8. It was tests against PHP 8.1.

Which API Client provides this package?

This package contains clients for the WebAPI and the SubmissionAPI.

The WebApi provides endpoints for agencies, countries, institutions and reports. There is always an endpoint for retrieving a collection of resources and one or more for retrieving more detailed resources. Currently, this client uses mostly the collection endpoints and provides methods for filtering them to retrieve a single less-detailed resource by unique identifiers.

There is also a cached implementation of the WebApi client. It decorates the ordinary WebApi client.

The submission API implements only two endpoints: submit/update a report and delete a report. The submission process involves several server-sided checks of the provided data. Some checks are performed immediately, which results in an error response if the data is invalid. Other checks are done asynchronously, which means that reports can be marked as invalid after a successful submission.

How to use the Client?

The Web API Client

The WebApiClientInterface implementations provide a static create method, that takes the minimal amount of required data and creates components like HTTP client and serializer by themselves.

The CachedWebApiClient decorates a WebApiClientInterface implementation.

The following methods are provided by the WebApiClientInterface:

The responses are mapped to DTOs via Symfony Serializer. The methods for retrieving a single less-detailed version of a resource, rely on filtering the collection responses. To prevent unnecessary DEQAR API hits, please use the CachedWebApiClient. The client caches its results for 1 day (86400 seconds).

Internally, the Symfony HttpClientInterface is used for requests. With the static create method of the WebApiClient, an instance with the Symfony HttpClient and Symfony Serializer (with the necessary normalizers and extractors) is created. However, the constructor is public and can be used to pass custom instances of the HttpClientInterface and the SerializerInterface.

The Submission API Client

The SubmissionApiClientInterface implementations provide a static create method, that takes the minimal amount of required data and creates components like HTTP client, validator and serializer by themselves.

⚠ The test parameter is important to use the DEQAR sandbox in a development or test environment. Currently, the DEQAR credentials are valid for the sandbox and the production environment. Without the test parameter, the SubmissionApiClient will send data to the public version of DEQAR!

To prevent sending invalid, data the inputs are validated against several constraints within this client. The data have to be provided as a SubmitReportRequest object, which is validated with the Symfony Validator.

The following constraints are applied to the SubmitReportRequest:

• agency: not blank, must exist in DEQAR (checked against the WebAPI)
• activity: not blank, must exist in DEQAR (checked against the WebAPI)
• status: 'part of obligatory EQA system' or 'voluntary'
• decision: 'positive', 'positive with conditions or restrictions', 'negative' or 'not applicable'
• validFrom: valid date
• files: if provided, all array elements must be valid FileRequest objects
• institutions: if provided, all array elements must be valid InstitutionRequest objects
• programmes: if provided, all array elements must be valid ProgrammeRequest objects
• id: nullable, but not blank
• contributingAgencies: nullable, but all array elements must be valid agencies (like above)
• localIdentifier: nullable, but length from 1 to 255 chars
• summary: nullable, but not blank
• validTo: nullable, but a valid date
• links: nullable, but all array elements must be valid LinkRequest objects
• comment: nullable, but not blank
• A certain number of institutions and programmes have to be provided according to (https://docs.deqar.eu/report_data/#activity)

The sub-objects of the request are validated too:

• FileRequest:
  • originalLocation: length from 1 to 500 chars, url that points to a remote PDF file (checked with the returned content-type header)
  • languages: at least one 3-letter country code
  • displayName: nullable, but length from 1 to 255 chars
• InstitutionRequest:
  • deqarId or (exclusive) eterId has to be provided and point to an existing institution
• LinkRequest:
  • link: length from 1 to 255 chars
  • displayName: nullable, but length from 1 to 200 chars
• ProgrammeRequest:
  • namePrimary: length from 1 to 255 chars
  • identifiers if provided, all array elements must be valid ProgrammeIdentifierRequest objects
  • qualificationPrimary: nullable, but length from 1 to 255 chars
  • alternativeNames: if provided, all array elements must be valid ProgrammeNameRequest objects
  • nqfLevel: nullable, but length from 1 to 255 chars
  • qfEheaLevel: nullable, but 'short cycle', 'first cycle', 'second cycle' or 'third cycle'
  • At least one the levels must not be null (NQF level or QF EHEA level)

To allow the report updating, a report_id can be provided.

The submitReport and the deleteReport methods return response objects. They contain a flag, that indicates if the request was successful and the returned data. The data contains important information about server-side constraints that were violated.

What packages can be used with together with this one?

Currently, two packages are planned:

• Symfony bundle to provide the clients as services
• DEQAR contract bundle to provide abstract entities and repositories for API results, that can be easily persisted locally

How to test the package?

The package provides PHPUnit tests for both API clients. In a local environment the tests and static code analysis can be executed via docker.

The PHPUnit tests and a static code analysis via PHPStan are also executed via GitHub actions on any push or PR. The GitHub Actions CI runs with all supported PHP versions and all supported Symfony versions.

Contributing

I am really happy that the software developer community loves Open Source, like I do! ♥

That's why I appreciate every issue that is opened (preferably constructive) and every pull request that provides other or even better code to this package.

You are all breathtaking!

Special Thanks

This project is financed by the European Quality Assurance Register (EQAR) and the European Union, which I am very thankful for!