Descrição

Documentação da API do portal público da Plataforma Sucupira. Esta página tem como objetivo auxiliar o usuário da API a conhecer seus aspectos de consumo e lógica. São explorados os conceitos de facetas, query e search, além de informações sobre paginação dos dados e possíveis mensagens de erro.

Detalhes de consumo de cada endpoint podem ser visto na Documentação Swagger.

Facetas

Faceta é um aspecto ou característica usada para filtrar ou organizar os dados. Ela é um campo presente no conjunto de dados.

As facetas podem ser acessadas pelo endpoint http://apigw-proxy.capes.gov.br/observatorio/facetas/data/observatorio/projeto_pesquisa acessando o endpoint é possível obter a listagem das facetas, valores aceitos, entre outras informações.

Abaixo é possível ter a relação das facetas existentes para o enpoint http://apigw-proxy.capes.gov.br/observatorio/facetas/data/observatorio/projeto_pesquisa. Mais informações a respeito de cada uma devem ser vistos no proprio endpoint

Nome	Key	Valores aceitos
Ano da coleta	ano-base	/observatorio/facetas/data/observatorio/projeto_pesquisa/ano-base
Instituição de ensino	id-ies	/observatorio/facetas/data/observatorio/projeto_pesquisa/id-ies
Programa de pós-graduação	id-programa	/observatorio/facetas/data/observatorio/projeto_pesquisa/id-programa
Natureza do projeto	id-natureza-projeto	/observatorio/facetas/data/observatorio/projeto_pesquisa/id-natureza-projeto
Situação do projeto	id-situacao-projeto	/observatorio/facetas/data/observatorio/projeto_pesquisa/id-situacao-projeto
Perfil	id-pessoa	/observatorio/facetas/data/observatorio/projeto_pesquisa/id-pessoa

Valores aceitos

Os valores que podem ser recebidos pelas facetas para realizar a filtragem podem ser obtidos pelo endpoint /facetas/data/{origem}/{path}/{key}. Na listagem dos valores aceitos temos os sequintes dados:

• "tipo": Tipo da faceta;
• "nome": Nome que descreve a faceta;
• "key": Chave, usada para realizar a filtragem em si;
• "value": Valor que é exibido nos registros.

Ao lado temos um exemplo, nele temos o campo de "key", o conteúdo desse campo que deve ser usado para realização da filtragem pelas facetas.

                [ {
  "tipo" : 2,
  "nome" : "Ano da coleta",
  "key" : "2024",
  "value" : "2024"
}, {
  "tipo" : 2,
  "nome" : "Ano da coleta",
  "key" : "2023",
  "value" : "2023"
}, {
  "tipo" : 2,
  "nome" : "Ano da coleta",
  "key" : "2022",
  "value" : "2022"
} ]
            

Parâmetro "Search"

Parâmetro utilizado para procurar registros que contenham o termo informado.

Exemplo de uso

Nesse exemplo serão buscados todos os dados que contenham "sao paulo" em seu contexto.

• http://apigw-proxy.capes.gov.br/observatorio/data/observatorio/projeto_pesquisa?search=sao+paulo&page=0&size=10

Paginação

Todos os serviços são passíveis de paginação, ou seja, por padrão serão exibidos os 20 primeiros registros, mas sendo possível navegar até os últimos por meio da paginação. Vale salientar que a paginação está sendo aplicada igualmente para os serviços de listagem como para os serviços de paginação.

Campo de paginação

page: Representa o número da página que você deseja recuperar. A numeração das páginas começa em 0, então a primeira página é a página 0, a segunda é a página 1, e assim por diante.
size: Define o número de registros (ou elementos) que você deseja recuperar por página. Por exemplo, se size for definido como 10, cada página conterá até 10 registros.

Exemplo de como acessar os 10 primeiros registros:

• http://apigw-proxy.capes.gov.br/observatorio/data/observatorio/projeto_pesquisa?page=0&size=10

Exemplo de como acessar os registros do 11 ao 20, ou seja, a segunda página com 10 registros:

• http://apigw-proxy.capes.gov.br/observatorio/data/observatorio/projeto_pesquisa?page=1&size=10

Errors

A página a seguir contém uma descrição resumida dos possíveis erros apresentados pela aplicação durante seu uso. A documentação segui o padrão da RFC 7807 para descrição de erros em APIs HTTP.

Os códigos de status de resposta apresentados estão em conformidade com o descrito na MDN.

Informação não encontrada

Esse erro é apresentado quando se solicita um recurso específico (pelo identificador, por exemplo) aos endpoints que não existe na base de dados. É retornado código 404 (Not Found), tipo de retorno 'application/problem+json' e um objeto JSON no corpo contendo o status da resposta, título e detalhe do erro resumidos, e o recurso requisitado pelo usuário.

Exemplo:

               
{
    "type": null,
    "title": "Informação não encontrada",
    "detail": "O recurso solicitado não foi encontrado.",
    "status": 404,
    "instance": "/data/online/ies/1"
}
               
            

Origem e/ou path não existe

Esse erro é apresentado quando se solicita um recurso aos endpoints que solicitam os parâmetros ‘origem’ e ‘path’, mas são passados valores que não existem na base de dados. É retornado código 400 (BAD REQUEST), tipo de retorno 'application/problem+json' e um objeto JSON no corpo contendo o status da resposta, título e detalhe do erro resumidos, e o recurso requisitado pelo usuário.

Exemplo:

                
{
    "type": null,
    "title": "Origem e/ou path não existe",
    "detail": "Origem e/ou caminho requisitado não existe.",
    "status": 400,
    "instance": "/data/teste/teste"
}
                
            

A materialização não existe

Esse erro é apresentado quando se solicita os dados de uma materialização aos endpoints que solicita o parâmetro ‘view’ mas é passado valor que não existe na base de dados. É retornado código 400 (BAD REQUEST), tipo de retorno 'application/problem+json' e um objeto JSON no corpo contendo o status da resposta, título e detalhe do erro resumidos, e o recurso requisitado pelo usuário.

Exemplo:

                
{
    "type": null,
    "title": "A materialização não existe",
    "detail": "A materialização solicitada não existe.",
    "status": 400,
    "instance": "/materializado/first/a"
}
                
            

A faceta não existe

Esse erro é apresentado quando se solicita o conjunto de facetas de um dado grupo de parâmetros ‘origem’ e ‘path’, mas são passados valores que não existem na base de dados. É retornado código 400 (BAD REQUEST), tipo de retorno 'application/problem+json' e um objeto JSON no corpo contendo o status da resposta, título e detalhe do erro resumidos, e o recurso requisitado pelo usuário.

Exemplo:

                
{
    "type": null,
    "title": "A faceta não existe",
    "detail": "Não existem facetas disponíveis para origem e/ou path requisitados.",
    "status": 400,
    "instance": "/facetas/data/a/s"
}
                
            

Erro interno

Esse erro é apresentado quando algum erro inesperado ocorre na aplicação durante a execução de um pedido. É retornado código 500 (INTERNAL SERVER ERROR), tipo de retorno 'application/problem+json' e um objeto JSON no corpo contendo o status da resposta, título e detalhe do erro resumidos, e o recurso requisitado pelo usuário.

Exemplo:

                
{
    "type": null,
    "title": "Erro interno",
    "detail": "Ocorreu um erro inesperado durante a execução da solicitação. Tente novamente.",
    "status": 500,
    "instance": "/facetas/data/a/s"
}