Documentação da API REST e da API Python

Esta página apresenta a documentação de referência da API REST do Requirements Portal. Com a API REST, você pode obter e modificar dados do Requirements Portal ou até mesmo gravar dados de volta no Requirements Portal, atualizando assim as informações. Além disso, ela permite conectar-se ou integrar-se a outras aplicações.

Acessando a API REST no Requirements Portal usando tokens

Para acessar a API REST no Requirements Portal, você pode gerar os tokens na página Settings – User Tokens (acessada clicando no ícone  no canto superior direito, selecionando Settings no menu exibido e, em seguida, selecionando User Tokens na lista do painel à esquerda). Nessa página, você encontrará o API address da sua implantação específica. Esse endereço é necessário para fazer chamadas de API.

Clique no ícone + no canto inferior direito da página Settings – User Tokens para gerar um novo token. Cada token é válido por 3 months e deve ser gerado novamente após expirar.

Para consumir a API usando o access_token, é necessário adicionar um token no formato "Bearer ..." ao cabeçalho Authorization da requisição HTTP, usando o tipo de aplicação "JSON".

curl --location 'http://deployment_name/rest/requirements/versions/search/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer hO2lwhLZsYOgXPNVI' \
--data '{
    "size": 10,
    "query_filters": {
        "object_id": 93
    }
}'

Ou, usando requests, você pode enviar o token de acesso desta forma:

access_token = 'Generated_Access_token'
api_url = 'Api_Address'

# workspace id and component type

workspace_id = 1
component_type_name = "CompA"

# Define headers with the access token
headers = {
    'Authorization': f'Bearer {access_token}',
    'Content-Type': 'application/json',  # Adjust content type as needed
}

# Make a GET request (you can use other HTTP methods like POST, PUT, etc.)
component_types_workspace = requests.get(api_url + "components/types/?workspace="+str(workspace_id), headers=headers)

Documentação da API Python

A API Python permite acessar e atualizar objetos na sua implantação com código Python.

Instale o pacote necessário da API Python com pip:

pip install valispace

Importe o módulo da API em um script Python:

import valispace

E inicialize com:

valispace = valispace.API()

Mais informações sobre os recursos e as funções da API podem ser encontradas aqui. O pacote da API Python é licenciado sob a licença MIT, o que significa que qualquer pessoa pode contribuir com o código clonando o repositório do GitHub.

Endpoints

Os usuários podem acessar os endpoints na página do Swagger. Para acessar a página, adicione swagger/ ao final da URL da API, que pode ser encontrada na página Settings – User Tokens. A página exibe o Django Swagger com todos os endpoints existentes.

Os métodos disponíveis são GET, POST, PUT, PATCH e DELETE.

Cada objeto no Requirements Portal tem seu próprio ID. Você pode usá-lo para pesquisar e recuperar as informações do próprio objeto. O ID do objeto pode ser visualizado diretamente no Requirements Portal ou na URL ao clicar no objeto no Requirements Portal.

Por exemplo, se você usar a função GET para obter informações do histórico de um requisito por meio do Swagger, poderá usar o endpoint a seguir para obter os detalhes desse histórico.

GET /rest/requirements/{requirement-id}/history/

Usando GET para recuperar as informações do histórico de um requisito

Da mesma forma, você pode usar os métodos para recuperar, atualizar ou publicar diferentes objetos, como blocos, tags, valis, textvalis, requisitos, especificações, métodos de verificação etc. Você pode pesquisar os endpoints na página do Swagger.

Filtrando objetos por projeto

Além da autenticação, você pode usar o método GET para recuperar objetos como Valis ou Requisitos na implantação. Se precisar filtrar os resultados com base em um projeto específico, poderá usar os recursos de filtragem, desde que o endpoint esteja configurado para isso. Por exemplo, para recuperar requisitos associados ao projeto 24, você pode usar a seguinte requisição GET:

GET /rest/requirements/?project=24

Essa funcionalidade é demonstrada no vídeo abaixo para facilitar a compreensão.

Funções integradas

No Requirements Portal, sempre que um usuário digita texto no campo de texto, ele é salvo no backend em formato HTML. O formato HTML preserva a formatação e as referências a valis ou outros objetos. Portanto, ao obter as informações dos requisitos, você pode receber texto HTML na importação. Para evitar isso, implementamos duas funções que podem ser úteis para converter os campos HTML em texto simples ou em HTML com formatação, mas com os valis convertidos em texto. As funções são clean_text e clean_html.

Função clean_text

A função clean_text converte toda a formatação HTML e as referências a objetos no campo em texto. No entanto, nesse caso, a formatação também é perdida. Por exemplo, se houver uma lista, tabelas ou cores, essa formatação também será perdida. Você pode usar essa função conforme mostrado abaixo.

Aqui, estou filtrando pelo projeto 24 e solicitando o texto simples do texto e da justificativa do campo. A saída para essa ação específica seria a seguinte.

Requisitos após usar a função clean_text

Função clean_html

A função clean_html mantém as opções de formatação do texto, mas converte as referências e os objetos, como valis, em texto. Se o texto contiver opções de formatação, como listas, cor de fundo, tabelas etc., essas informações serão preservadas.

Requisitos após usar a função clean_html

Perguntas frequentes

Como encontrar o endpoint correto?

Navegar por vários endpoints com nomes semelhantes pode ser confuso. Se você tiver dúvidas sobre um endpoint específico, recomendamos entrar em contato por meio da nossa Página de suporte da Altium para obter esclarecimentos. Como alternativa, você pode usar o recurso "Rede" do navegador para observar quais endpoints são acionados ao executar ações no front-end do software.

Como exemplo, considere o processo de criação de um bloco. Nesse caso, o endpoint associado pode ser identificado como uma requisição "POST" para "/rest/components". Essa informação pode ser facilmente identificada inspecionando a atividade de rede durante a ação. Uma demonstração rápida dessa abordagem é apresentada no breve vídeo abaixo.