CIÊNCIAVITAE – API

Através de uma API REST, o CIÊNCIAVITAE possibilita que sistemas externos consultem e atualizem informações de currículos nas várias áreas funcionais, como informação pessoal, formação, percurso profissional, projetos, produções e distinções. Essa interoperabilidade facilita o intercâmbio de informações e o desenvolvimento de novas aplicações no ecossistema científico.

Base URL
São disponibilizados dois ambientes, um produtivo e outro de testes em qualidade (QA).

Produção:

• https://api.cienciavitae.pt/docs/ (documentação swagger)

Testes (QA)

• https://qa.cienciavitae.pt/docs/ (documentação swagger)

Versão
A versão disponibilizada é a v1.1

A API CIÊNCIAVITAE está disponível de forma pública e gratuita para todas as entidades do ecossistema PTCRIS, com acesso realizado via credenciais fornecidas pela plataforma através do método Basic Authentication.

O pedido de acesso a este serviço deverá ser feito para o endereço helpdesk@cienciavitae.pt, pelo representante da instituição, ou alguém por si mandatado, incluindo as seguintes informações da entidade subscritora:

• Nome da entidade ou instituição
• URL da entidade
• Perfil do cliente: público ou semi-público
• Nível de acesso: leitura/escrita
• Nome e e-mail do responsável pelo serviço cliente

Após a receção das credenciais, os integradores poderão desenvolver a integração no ambiente de testes da 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.

Perfil

As entidades subscritoras podem optar por dois perfis de acesso: um perfil público, que permite acesso a toda a informação pública de currículos publicados, ou um perfil semi-público, que permite acesso tanto à informação pública quanto à informação semi-pública de currículos publicados, além de acesso a dados autorizados pelos utilizadores do currículo à entidade subscritora.

Permissões

As permissões são de dois tipos, leitura ou leitura/escrita, dependendo da autorização fornecida pelos utilizadores. As permissões podem ser ativadas através de um URL disponibilizado pela plataforma CIÊNCIAVITAE, com o seguinte formato:

• Ambiente de Produção: https://cienciavitae.pt/cv/add-privilege/< client_id >
• Ambiente de Testes: https://qa.cienciavitae.pt/cv/add-privilege/< client_id >

A revogação de permissões é realizada pelo utilizador do currículo diretamente na área de definições da plataforma CIÊNCIAVITAE.

Estrutura de metadados

A estrutura de metadados de um currículo é composta pelos seguintes blocos informativos:

• curriculum
  • identifying-info
    • person-info – informação pessoal
    • citation-name – nomes de citação
    • author-identifier – identificadores de autor
    • email – endereços de e-mail
    • phone-number – números de telefone
    • mailing-address – moradas
    • web-address – endereços web
    • domain-activity – áreas do conhecimento
    • language-competency – idiomas
    • resume – resumo do currículo
• degrees – formação
• employments – percurso profissional
• fundings – projetos
• outputs – produção
• services – atividades
• distinctions – distinções
• groups – associações entre registos (ex: projetos e produções)

Os schemas associados a esta estrutura de metadados estão disponíveis em https://api.cienciavitae.pt/schemas/curriculum/ na área de “cv”.

Para garantir o funcionamento eficaz da API para toda a comunidade, evitando picos de acessos simultâneos, recomenda-se:

• Armazenar os dados em cache, sempre que possível, para evitar solicitações repetitivas
• Monitorizar o uso da API, com um máximo recomendado de 2 chamadas por segundo (120 por minuto)
• Para obter informações de diversas áreas do currículo, usar preferencialmente o método curriculum ao invés de chamadas a cada área funcional do CV
• Em caso de falha no acesso ao serviço, comunicar o problema via e-mail para helpdesk@cienciavitae.pt

Utilizações que impactem negativamente a qualidade do serviço, intencionalmente ou por negligência, poderão resultar em limitação ou bloqueio do acesso.

Formatos
A API pode devolver resultados em dois formatos: XML e JSON. O cliente pode especificar o formato desejado em cada método, utilizando o parâmetro accept no header do pedido.

Tipos de métodos
Dependendo da função da API a ser invocada, estão disponíveis diferentes métodos HTTP:

GET – Os métodos GET solicitam uma representação do recurso especificado na plataforma CIÊNCIAVITAE.

POST – Os métodos POST enviam uma nova entidade ao recurso especificado, frequentemente provocando uma alteração no estado da informação no CIÊNCIAVITAE.

PUT – Os métodos PUT substituem todas as representações atuais do recurso de destino no CIÊNCIAVITAE pelos dados enviados na solicitação.

DELETE – Os métodos DELETE removem o recurso especificado da plataforma CIÊNCIAVITAE.

Códigos de resposta
Mediante o tipo de chamada ao serviço da API, poderão ser retornados os seguintes códigos de resposta:

200 – Operação com sucesso
201 – Registo criado ou alterado com sucesso
204 – Registo sem alterações desde a última data de atualização
400 – CIÊNCIA ID inválido
403 – Permissões inválidas para acesso ao currículo
404 – Registo não encontrado
409 – Registo já existente no currículo
500 – Erro de operação

Todos os códigos de resposta da série 4-x-x devem ser tratados durante o processo de integração para assegurar a normalização das chamadas à API CIÊNCIAVITAE. Os códigos de resposta da série 5-x-x devem ser verificados pelo integrador, e, caso não seja possível resolver o problema, deve ser contactado o suporte do CIÊNCIAVITAE através do e-mail helpdesk@cienciavitae.pt.

Ficheiros dump

O CIÊNCIAVITAE disponibiliza anualmente um ficheiro contendo os dados públicos dos currículos registados na plataforma. Este ficheiro pode ser acedido através de um link fornecido pela chamada ao método “dataset/public-data-files”.

Licença de uso

Os dados da plataforma estão disponíveis sob a licença Creative Commons Attribution 4.0 (CC BY 4.0).

Chamada à API para obter os dados completos de um currículo:

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

—

Chamada para obter dados completos de uma produção registada:

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 …”

—

Chamada para validar as permissões de acesso a um currículo:

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
• Identificação: funcionalidade para permitir o uso de nome abreviado em tag display-name.

—

DEPLOY 16-MAI-2024
• Atividades: alteração do tamanho do nome de aluno para 120 caracteres.

—

DEPLOY 12-MAR-2024
•Produções: alteração do tamanho do número da patente para 50 caracteres.
• Implementação de encoding Cp1252.