Bem-vindo à Referência da API REST do Fluid.

As APIs REST (Representational State Transfer) são endpoints de serviço que suportam conjuntos de operações HTTP (métodos), que fornecem acesso de criação, recuperação, atualização ou exclusão aos recursos do serviço. Este artigo apresenta:

• Os componentes básicos de um par de solicitação/resposta de uma API REST.

• Visões gerais sobre como criar e enviar uma solicitação REST e como lidar com a resposta.
  

Você pode usar a API do Fluid para criar scripts e aplicativos que automatizam processos, integram com o Fluid e estendem o Fluid. Por exemplo, você pode usar a API para gerenciar status de RAG de Ações, projetos e quadros.

Cada endpoint da API REST é documentado individualmente, e os endpoints são categorizados pelo recurso que afetam principalmente. Por exemplo, você pode encontrar endpoints relacionados a ações na pasta Ação em "Endpoint da API REST para Ações"

Recomendamos fortemente que você teste seu código/scripts no ambiente Sandbox e não diretamente em Produção. Se você não possui atualmente um ambiente Sandbox, entre em contato com seu representante de sucesso do cliente Fluid.

A documentação online da Open API para desenvolvedores pode ser encontrada em https://{organisation}.fluid.work/docs. Substitua organisation na URL pela sua organização específica.

Consulte o final deste artigo para obter uma coleção do Postman que pode ser importada e usada para fins de teste/desenvolvimento.

Um par de solicitação/resposta de uma API REST pode ser separado em cinco componentes:

1. O URI da solicitação, no seguinte formato: VERB https://{organisation}.fluid.work/rest/api/{resource}?version={version}

• organisation: Sua organização ou servidor para o qual você está enviando a solicitação. Eles são estruturados da seguinte forma:

• resource path: O caminho do recurso é o seguinte: /rest/api/{resource}. Por exemplo /rest/api/action.

• version: Cada solicitação de API deve incluir uma versão para evitar que seu aplicativo ou serviço seja interrompido à medida que as APIs evoluem. As versões estão no seguinte formato: {major}.{minor}[-{stage}[.{resource-version}]], por exemplo:

  • version=3.0

  • version=3.1-preview

  • version=3.0-preview.1
    

2. Campos do cabeçalho da mensagem de solicitação HTTP:

• Um método HTTP obrigatório (também conhecido como operação ou verbo), que informa ao serviço que tipo de operação você está solicitando. As APIs REST do Fluid suportam os métodos GET, HEAD, PUT, POST e PATCH.

• Campos de cabeçalho adicionais opcionais, conforme exigido pelo URI e método HTTP especificados. Por exemplo, um cabeçalho de Autorização que fornece um token bearer contendo informações de autorização do cliente para a solicitação.
  

3. Campos opcionais do corpo da mensagem de solicitação HTTP, para suportar o URI e a operação HTTP. Por exemplo, operações POST contêm objetos codificados em MIME que são passados como parâmetros complexos.

• Para operações POST ou PUT, o tipo de codificação MIME para o corpo deve ser especificado no cabeçalho de solicitação Content-type também. Alguns serviços exigem que você use um tipo MIME específico, como application/json.
  

4. Campos do cabeçalho da mensagem de resposta HTTP:

• Um código de status HTTP, variando de códigos de sucesso 2xx a códigos de erro 4xx ou 5xx. Alternativamente, um código de status definido pelo serviço pode ser retornado, conforme indicado na documentação da API.

• Campos de cabeçalho adicionais opcionais, conforme necessário para suportar a resposta da solicitação, como um cabeçalho de resposta Content-type.
  

5. Campos opcionais do corpo da mensagem de resposta HTTP:

Objetos de resposta codificados em MIME podem ser retornados no corpo da resposta HTTP, como uma resposta de um método GET que está retornando dados. Normalmente, esses objetos são retornados em um formato estruturado como JSON, conforme indicado pelo cabeçalho de resposta Content-type. Observe que, para fins da API REST do Fluid, as respostas são sempre retornadas no formato JSON, independentemente do Content-type definido.

Cada solicitação à API REST inclui um método HTTP e um caminho. Dependendo do endpoint da API REST, você também pode precisar especificar cabeçalhos de solicitação, informações de autenticação, parâmetros de consulta ou parâmetros de corpo.

A documentação de referência da API REST descreve o método HTTP, o caminho e os parâmetros para cada endpoint. Ela também exibe exemplos de solicitações e respostas para cada endpoint. Para mais informações, consulte a documentação de referência REST.

O método HTTP de um endpoint define o tipo de ação que ele executa em um determinado recurso. Alguns métodos HTTP comuns são GET, POST, DELETE e PATCH. A documentação de referência da API REST fornece o método HTTP para cada endpoint.

Por exemplo, o método HTTP para o endpoint "Listar problemas do repositório" é GET."

Sempre que possível, a API REST do Fluid se esforça para usar um método HTTP apropriado para cada ação.

GET: Usado para recuperar recursos.
POST: Usado para criar recursos.
PUT: Usado para substituir recursos ou coleções de recursos.
DELETE: Usado para excluir recursos.

Cada endpoint tem um caminho. A documentação de referência da API REST fornece o caminho para cada endpoint. Por exemplo, o caminho para obter uma ação específica para um ID específico, o endpoint é http://organisation.fluid.work/rest/api/action/{id}.

As chaves {} em um caminho indicam parâmetros de caminho que você precisa especificar. Os parâmetros de caminho modificam o caminho do endpoint e são obrigatórios em sua solicitação.

Os cabeçalhos fornecem informações extras sobre a solicitação e a resposta desejada. A seguir estão alguns exemplos de cabeçalhos que você pode usar em suas solicitações à API REST do Fluid. Para um exemplo de solicitação que usa cabeçalhos, consulte "Fazendo uma solicitação."

Os tipos de conteúdo especificam o formato dos dados que você deseja consumir da API. Os tipos de conteúdo são específicos para recursos, permitindo que eles mudem de forma independente e suportem formatos que outros recursos não suportam. O Fluid usa o tipo de conteúdo application/json.

Todos os endpoints requerem autenticação. 

Muitos métodos de API exigem ou permitem que você envie informações adicionais em parâmetros em sua solicitação. Existem alguns tipos diferentes de parâmetros: Parâmetros de caminho, parâmetros de corpo e parâmetros de consulta.

Os parâmetros de caminho modificam o caminho do endpoint. Esses parâmetros são obrigatórios em sua solicitação. Para mais informações, consulte "Caminho."

Os parâmetros de corpo permitem que você passe dados adicionais para a API. Esses parâmetros podem ser opcionais ou obrigatórios, dependendo do endpoint. Por exemplo, um parâmetro de corpo pode permitir que você especifique um título de problema ao criar um novo problema, ou especifique determinadas configurações ao habilitar ou desabilitar um recurso. A documentação de cada endpoint da API REST do Fluid descreverá os parâmetros de corpo que ele suporta. 

Por exemplo, o endpoint "Criar uma Ação" exige que você especifique um título para a nova Ação em sua solicitação. Ele também permite que você especifique opcionalmente outras informações, como texto para colocar na descrição da Ação, usuários para atribuir à nova Ação etc.

Os parâmetros de consulta permitem que você controle quais dados são retornados para uma solicitação. Esses parâmetros geralmente são opcionais. A documentação de cada endpoint da API REST do Fluid descreverá quaisquer parâmetros de consulta que ele suporta. 

A API REST do Fluid atualmente suporta apenas autenticação básica com nome de usuário e token PAT. Consulte o artigo da KB Criando um Token de Acesso Pessoal para mais informações sobre como gerar um token PAT.

Um token de acesso pessoal contém suas credenciais de segurança para o Fluid. Um PAT identifica você, suas organizações acessíveis e escopos de acesso. Como tal, eles são tão críticos quanto senhas, portanto você deve tratá-los da mesma forma.

Para o Fluid, as instâncias estão no formato {organisation}.fluid.work/, portanto o padrão é assim:

VERB https://organisation.fluid.work/rest/api/{resource}?version={version}

Por exemplo, veja como obter uma lista das minhas ações no Fluid.

curl --user username:pattoken --location 'http://organisation.fluid.work/rest/api/action?version=3.0' 

Se você deseja fornecer o token de acesso pessoal por meio de um cabeçalho HTTP, você deve primeiro convertê-lo em uma string Base64 (o exemplo a seguir mostra como converter para Base64 usando C#). (Certas ferramentas como o Postman aplicam uma codificação Base64 por padrão. Se você estiver testando a API por meio de tais ferramentas, a codificação Base64 do PAT não é necessária.) A string resultante pode então ser fornecida como um cabeçalho HTTP no formato:

Authorization: Basic BASE64PATSTRING

Aqui está em C# usando a [classe HttpClient](/previous-versions/visualstudio/hh193681(v=vs.118).

public static async void GetActions()
{
  try
  {
    var personalaccesstoken = "PAT_FROM_WEBSITE";

    using (HttpClient client = new HttpClient())
    {
      client.DefaultRequestHeaders.Accept.Add(
        new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));

      client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic",
        Convert.ToBase64String(
          System.Text.ASCIIEncoding.ASCII.GetBytes(
            string.Format("{0}:{1}", "", personalaccesstoken))));

      using (HttpResponseMessage response = await client.GetAsync(
            "https://client.fluid.work/rest/api/action"))
      {
        response.EnsureSuccessStatusCode();
        string responseBody = await response.Content.ReadAsStringAsync();
        Console.WriteLine(responseBody);
      }
    }
  }
  catch (Exception ex)
  {
    Console.WriteLine(ex.ToString());
  }
}

Você deve receber uma resposta como esta.

[
    {
        "fields": {
            "assignee": [
                {
                    "id": 603,
                    "guid": "f1cb6467-0262-4539-9148-7b869defd817",
                    "name": "David Burt",
                    "userName": "david.burt",
                    "email": "dump18@fluidbsg.com"
                }
            ],
            "attachmentCount": 0,
            "author": {
                "id": 603,
                "guid": "f1cb6467-0262-4539-9148-7b869defd817",
                "name": "David Burt",
                "userName": "david.burt",
                "email": "dump18@fluidbsg.com"
            },
            "businessValue": 0,
            "chatCount": 0,
            "createDate": "2024-01-19T11:57:15.0000000",
            "description": "Description 1",
            "dueDate": null,
            "endDate": null,
            "impediment": 0,
            "isOwner": true,
            "modifiedBy": {
                "id": 603,
                "guid": "f1cb6467-0262-4539-9148-7b869defd817",
                "name": "David Burt",
                "userName": "david.burt",
                "email": "dump18@fluidbsg.com"
            },
            "modifiedDate": "2024-01-19T11:57:15.0000000",
            "owners": [
                {
                    "id": 603,
                    "guid": "f1cb6467-0262-4539-9148-7b869defd817",
                    "name": "David Burt",
                    "userName": "david.burt",
                    "email": "dump18@fluidbsg.com"
                }
            ],
            "priority": "Medium",
            "principalGuid": "f1cb6467-0262-4539-9148-7b869defd817",
            "ragStatus": "Green",
            "startDate": null,
            "status": "Request",
            "statusCode": 4,
            "taskType": "Task",
            "title": "Title 1"
        },
        "id": 4317,
        "guid": "00d8b850-6b78-4c1f-95c1-7818606d0bb2",
        "url": "https://organisation.fluid.work/rest/api/action/4317"
    },
    {
        "fields": {
            "assignee": [
                {
                    "id": 603,
                    "guid": "f1cb6467-0262-4539-9148-7b869defd817",
                    "name": "David Burt",
                    "userName": "david.burt",
                    "email": "dump18@fluidbsg.com"
                }
            ],
            "attachmentCount": 0,
            "author": {
                "id": 603,
                "guid": "f1cb6467-0262-4539-9148-7b869defd817",
                "name": "David Burt",
                "userName": "david.burt",
                "email": "dump18@fluidbsg.com"
            },
            "businessValue": 0,
            "chatCount": 0,
            "createDate": "2023-10-13T18:50:01.0000000",
            "description": "Description 2",
            "dueDate": null,
            "endDate": null,
            "impediment": 0,
            "isOwner": true,
            "modifiedBy": {
                "id": 603,
                "guid": "f1cb6467-0262-4539-9148-7b869defd817",
                "name": "David Burt",
                "userName": "david.burt",
                "email": "dump18@fluidbsg.com"
            },
            "modifiedDate": "2023-10-13T18:50:01.0000000",
            "owners": [
                {
                    "id": 603,
                    "guid": "f1cb6467-0262-4539-9148-7b869defd817",
                    "name": "David Burt",
                    "userName": "david.burt",
                    "email": "dump18@fluidbsg.com"
                }
            ],
            "priority": "Medium",
            "principalGuid": "f1cb6467-0262-4539-9148-7b869defd817",
            "ragStatus": "Green",
            "startDate": "2023-10-04T00:00:00.0000000",
            "status": "Request",
            "statusCode": 4,
            "taskType": "Task",
            "title": "Title 2"
        },
        "id": 4206,
        "guid": "0d0fcfb6-b1d9-41b0-8264-b29ace60df63",
        "url": "https://organisation.fluid.work/rest/api/action/4206"
    }
]

Algumas chamadas de API retornarão uma lista de objetos JSON de resposta; Ações, por exemplo, podem retornar uma lista de Ações. O número máximo de itens a retornar em uma resposta é 50. Para obter a lista completa de respostas, será necessário fazer múltiplas requisições à API REST para obter a próxima página de resultados.

Os dois cabeçalhos de resposta HTTP Item-Count e Total-Count mencionados acima conterão valores que você pode usar para passar em requisições HTTP subsequentes como valores de consulta para os parâmetros "skip" e "take".

Se, por exemplo, Total-Count = 150 e Item-Count = 50, então o número total de objetos de resposta é 150 e o número atual de itens retornados é 50.

Para obter a próxima página de resultados, defina os parâmetros de consulta ?skip=50, ?take=50. Isso ignorará os primeiros 50 resultados que já foram retornados e retornará o próximo conjunto de resultados, obtendo os próximos 50 resultados. Se você não especificar um valor para o parâmetro de consulta take, o valor máximo padrão de 50 será aplicado internamente.

O cabeçalho de resposta HTTP Total-Count ainda mostrará 150, mas Item-Count agora é 100.

Repita este processo para obter a próxima página de resultados, defina os parâmetros de consulta ?skip=100. Isso ignorará os primeiros 100 resultados que já foram retornados e retornará o próximo conjunto de resultados, até o valor máximo de 50.

O cabeçalho de resposta HTTP Total-Count ainda mostrará 150, Item-Count agora é 150 e a lista de resposta está vazia, indicando que todos os resultados já foram retornados.

Abaixo está anexado um arquivo de coleção do Postman que pode ser usado para importar um conjunto de testes de requisição/resposta de exemplo que podem ser utilizados para verificar a API. Baixe o arquivo anexado e importe no Postman.

Você precisará atualizar os detalhes de Autorização conforme indicado abaixo no Postman: selecione o Tipo como Basic Auth e insira o nome de usuário da conta que você usará para acessar a API; a senha deve ser o token PAT dessa conta. Consulte Criando um Token de Acesso Pessoal para mais detalhes.

Você deve usar os valores de nome de usuário e token retornados pelo processo de Criação de Token de Acesso Pessoal, e não o token em base64.

Para a variável baseUrl, você deve atualizá-la de acordo com a URL da sua organização no Fluid

• Melhores práticas da API REST

• Endpoint da API REST para Ações