CIÊNCIAVITAE – API

Through a API REST, the CIÊNCIAVITAE allows external systems to consult and update CV information across various functional areas, including personal information, education, professional background, projects, productions, and awards. This interoperability facilitates the exchange of information and the development of new applications within the scientific ecosystem.

Base URL
Two environments are available, one productive and one for quality testing (QA).

Production:

• https://api.cienciavitae.pt/docs/ (swagger documentation)

Testing (QA)

• https://qa.cienciavitae.pt/docs/ (swagger documentation)

Version
The version available is v1.1

THE API CIÊNCIAVITAE is publicly and freely available to all entities within the ecosystem. PTCRIS, com acesso realizado via credenciais fornecidas pela plataforma através do método Basic Authentication.

The request to access this service should be made to the following address: helpdesk@cienciavitae.pt, by the institution's representative, or someone authorized by them, including the following information from the subscribing entity:

• Name of entity or institution
• Entity URL
• Customer profile: public or semi-public
• Access level: read/write
• Name and email of the person responsible for customer service

After receiving the credentials, integrators will be able to develop the integration in the test environment of [the relevant authority/company]. API. O ambiente de produção será disponibilizado aos integradores que realizarem os testes no ambiente QA e implementarem as recomendações de uso aprovadas pela equipa CIÊNCIAVITAE.

Profile

Subscribing entities can choose between two access profiles: a profile public, which allows access to all public information from published resumes, or a profile semi-public, which allows access to both public and semi-public information on published CVs, as well as access to data authorized by CV users to the subscribing entity.

Permissions

Permissions are of two types: read or read/write, depending on the authorization provided by users. Permissions can be activated through a URL provided by the platform. CIÊNCIAVITAE, with the following format:

• Production Environment: https://cienciavitae.pt/cv/add-privilege/< client_id >
• Test Environment: https://qa.cienciavitae.pt/cv/add-privilege/< client_id >

Revocation of permissions is carried out by the CV user directly in the platform settings area. CIÊNCIAVITAE.

Metadata structure

The metadata structure of a CV is made up of the following information blocks:

• curriculum
  • identifying-info
    • person-info – personal information
    • citation-name – citation names
    • author-identifier – author identifiers
    • email – email addresses
    • phone-number – phone numbers
    • mailing address – addresses
    • web-address – web addresses
    • domain-activity – areas of knowledge
    • language-competency – languages
    • resume – resume summary
• degrees – training
• employments – professional career
• funding – projects
• outputs – production
• services – activities
• distinctions
• groups – associations between records (e.g. projects and productions)

The schemas associated with this metadata structure are available at https://api.cienciavitae.pt/schemas/curriculum/ in the “CV” area.

To ensure the effective functioning of API For the entire community, while avoiding peaks in simultaneous access, the following is recommended:

• Cache data whenever possible to avoid repetitive requests
• Monitor the use of API, com um máximo recomendado de 2 chamadas por segundo (120 por minuto)
• To obtain information from different areas of the CV, preferably use the curriculum method instead of calling out each functional area of the CV.
• In case of failure in accessing the service, report the problem via email to helpdesk@cienciavitae.pt

Uses that negatively impact the quality of the service, whether intentionally or through negligence, may result in limited or blocked access.

Formats
THE API It can return results in two formats: XML and JSON. The client can specify the desired format in each method using the accept parameter in the request header.

Types of methods
Depending on the function of API To be invoked, different HTTP methods are available:

GET – GET methods request a representation of the specified resource from the platform CIÊNCIAVITAE.

POST – POST methods send a new entity to the specified resource, often causing a change in the state of the information in the resource. CIÊNCIAVITAE.

PUT – PUT methods replace all current representations of the target resource in the CIÊNCIAVITAE for the data sent in the request.

DELETE – The DELETE methods remove the specified resource from the CIÊNCIAVITAE platform.

Response codes
Depending on the type of call to the service of API, poderão ser retornados os seguintes códigos de resposta:

200 – Successful operation
201 – Record created or modified successfully
204 – Record unchanged since last update date
400 – SCIENCE Invalid ID
403 – Invalid permissions to access the curriculum
404 – Record not found
409 – Registration already existing in the curriculum
500 – Operation error

All 4-xx series response codes must be handled during the integration process to ensure the normalization of calls to API CIÊNCIAVITAE. Response codes in the 5-xx series should be checked by the integrator, and if the problem cannot be resolved, the integrator's support should be contacted. CIÊNCIAVITAE via email helpdesk@cienciavitae.pt.

Dump files

THE CIÊNCIAVITAE annually releases a file containing public data for resumes registered on the platform. This file can be accessed through a link provided by calling the "dataset/public-data-files" method.

License to use

Platform data is available under the license Creative Commons Attribution 4.0 (CC BY 4.0).

Call to API To obtain the complete data from a resume:

curl -X GET “https://qa.cienciavitae.pt/api/v1.1/curriculum/CF1B-E0C0-D98C?lang=EN” -H “accept: application/xml” -H “authorization: Basic …”

—

Call to obtain complete data on a registered production:

curl -X GET “https://qa.cienciavitae.pt/api/v1.1/curriculum/CF1B-E0C0-D98C/output/46698?lang=EN” -H “accept: application/xml” -H “authorization: Basic …”

—

Call to validate access permissions to a CV:

curl -X GET “https://qa.cienciavitae.pt/api/v1.1/api-user/CF1B-E0C0-D98C/access-privileges?lang=EN” -H “accept: application/xml” -H “authorization: Basic …”

DEPLOY 20-JUN-2024
• Identification: functionality to allow the use of a short name in the display-name tag.

—

DEPLOY 16-MAY-2024
• Activities: changing the length of the student name to 120 characters.

—

DEPLOY 12-MAR-2024
•Productions: changing the size of the patent number to 50 characters.
• Implementation of Cp1252 encoding.