Bienvenido a la referencia de la API REST de Fluid.

Las API REST (Representational State Transfer) son puntos de conexión de servicio que admiten conjuntos de operaciones HTTP (métodos), que proporcionan acceso de creación, recuperación, actualización o eliminación a los recursos del servicio. Este artículo lo guía a través de lo siguiente:

• Los componentes básicos de un par de solicitud/respuesta de una API REST.

• Información general sobre cómo crear y enviar una solicitud REST, y cómo gestionar la respuesta.
  

Puede usar la API de Fluid para compilar scripts y aplicaciones que automaticen procesos, se integren con Fluid y extiendan Fluid. Por ejemplo, podría usar la API para gestionar los estados RAG de Acciones, proyectos y tableros.

Cada endpoint de la API REST está documentado individualmente, y los endpoints se categorizan según el recurso al que afectan principalmente. Por ejemplo, puede encontrar los endpoints relacionados con acciones en la carpeta Acción, en "Endpoint de la API REST para Acciones"

Le recomendamos encarecidamente que pruebe su código o sus scripts en su Entorno de Pruebas y no directamente en producción. Si actualmente no cuenta con un Entorno de Pruebas, comuníquese con su representante de éxito del cliente de Fluid.

La documentación en línea de Open API para desarrolladores se encuentra en https://{organisation}.fluid.work/docs. Reemplace organisation en la URL por su organización específica.

Consulte el final de este artículo para obtener una colección de Postman que se puede importar y usar con fines de prueba o desarrollo.

Un par de solicitud/respuesta de una API REST se puede dividir en cinco componentes:

1. El URI de la solicitud, con el siguiente formato: VERB https://{organisation}.fluid.work/rest/api/{resource}?version={version}

• organisation: su organización o el servidor al que envía la solicitud. Tienen la siguiente estructura:

• resource path: la ruta de recurso es la siguiente: /rest/api/{resource}. Por ejemplo, /rest/api/action.

• version: cada solicitud de API debe incluir una versión para evitar que su aplicación o servicio deje de funcionar a medida que las API evolucionan. Las versiones tienen el siguiente formato: {major}.{minor}[-{stage}[.{resource-version}]], por ejemplo:

  • version=3.0

  • version=3.1-preview

  • version=3.0-preview.1
    

2. Campos de encabezado del mensaje de solicitud HTTP:

• Un método HTTP obligatorio (también conocido como operación o verbo), que indica al servicio qué tipo de operación está solicitando. Las API REST de Fluid admiten los métodos GET, HEAD, PUT, POST y PATCH.

• Campos de encabezado adicionales opcionales, según lo requiera el URI y el método HTTP especificados. Por ejemplo, un encabezado de Autorización que proporciona un token bearer con la información de autorización del cliente para la solicitud.
  

3. Campos opcionales del cuerpo del mensaje de solicitud HTTP, para admitir el URI y la operación HTTP. Por ejemplo, las operaciones POST contienen objetos codificados en MIME que se pasan como parámetros complejos.

• Para las operaciones POST o PUT, el tipo de codificación MIME del cuerpo también debe especificarse en el encabezado de solicitud Content-type. Algunos servicios requieren que use un tipo MIME específico, como application/json.
  

4. Campos de encabezado del mensaje de respuesta HTTP:

• Un código de estado HTTP, que va desde códigos de éxito 2xx hasta códigos de error 4xx o 5xx. Alternativamente, se puede devolver un código de estado definido por el servicio, según se indique en la documentación de la API.

• Campos de encabezado adicionales opcionales, según sea necesario para admitir la respuesta de la solicitud, como un encabezado de respuesta Content-type.
  

5. Campos opcionales del cuerpo del mensaje de respuesta HTTP:

Los objetos de respuesta codificados en MIME pueden devolverse en el cuerpo de la respuesta HTTP, como una respuesta de un método GET que devuelve datos. Normalmente, estos objetos se devuelven en un formato estructurado como JSON, según lo indique el encabezado de respuesta Content-type. Tenga en cuenta que, a efectos de la API REST de Fluid, las respuestas siempre se devuelven en formato JSON, independientemente del Content-type establecido.

Cada solicitud a la API REST incluye un método HTTP y una ruta. Según el endpoint de la API REST, también podría necesitar especificar encabezados de solicitud, información de autenticación, parámetros de consulta o parámetros de cuerpo.

La documentación de referencia de la API REST describe el método HTTP, la ruta y los parámetros de cada endpoint. También muestra ejemplos de solicitudes y respuestas para cada endpoint. Para obtener más información, consulte la documentación de referencia de REST.

El método HTTP de un endpoint define el tipo de acción que realiza sobre un recurso determinado. Algunos métodos HTTP comunes son GET, POST, DELETE y PATCH. La documentación de referencia de la API REST proporciona el método HTTP de cada endpoint.

Por ejemplo, el método HTTP del endpoint "Listar los problemas del repositorio" es GET."

Siempre que sea posible, la API REST de Fluid procura usar el método HTTP adecuado para cada acción.

GET: se usa para recuperar recursos.
POST: se usa para crear recursos.
PUT: se usa para reemplazar recursos o colecciones de recursos.
DELETE: se usa para eliminar recursos.

Cada endpoint tiene una ruta. La documentación de referencia de la API REST indica la ruta de cada endpoint. Por ejemplo, la ruta para obtener una acción específica según un ID específico, el endpoint es http://organisation.fluid.work/rest/api/action/{id}.

Las llaves {} en una ruta indican parámetros de ruta que debe especificar. Los parámetros de ruta modifican la ruta del endpoint y son obligatorios en su solicitud.

Los encabezados proporcionan información adicional sobre la solicitud y la respuesta deseada. A continuación, se presentan algunos ejemplos de encabezados que puede usar en sus solicitudes a la API REST de Fluid. Para ver un ejemplo de solicitud que usa encabezados, consulte "Realizar una solicitud."

Los tipos de contenido especifican el formato de los datos que desea consumir de la API. Los tipos de contenido son específicos de cada recurso, lo que permite que cambien de forma independiente y admitan formatos que otros recursos no admiten. Fluid usa el tipo de contenido application/json.

Todos los endpoints requieren autenticación. 

Muchos métodos de la API requieren o permiten que envíe información adicional en parámetros dentro de su solicitud. Existen varios tipos de parámetros: parámetros de ruta, parámetros de cuerpo y parámetros de consulta.

Los parámetros de ruta modifican la ruta del endpoint. Estos parámetros son obligatorios en su solicitud. Para obtener más información, consulte "Ruta."

Los parámetros de cuerpo le permiten pasar datos adicionales a la API. Estos parámetros pueden ser opcionales u obligatorios, según el endpoint. Por ejemplo, un parámetro de cuerpo puede permitirle especificar un título de incidencia al crear una nueva incidencia, o especificar determinadas configuraciones al habilitar o deshabilitar una función. La documentación de cada endpoint de la API REST de Fluid describirá los parámetros de cuerpo que admite. 

Por ejemplo, el endpoint "Crear una Acción" requiere que especifique un título para la nueva Acción en su solicitud. También le permite especificar opcionalmente otra información, como el texto de la descripción de la Acción, los usuarios que se asignarán a la nueva Acción, etc.

Los parámetros de consulta le permiten controlar qué datos se devuelven para una solicitud. Estos parámetros suelen ser opcionales. La documentación de cada endpoint de la API REST de Fluid describirá los parámetros de consulta que admite. 

La API REST de Fluid actualmente solo admite la autenticación básica con un nombre de usuario y un token PAT. Consulte el artículo de la KB Creando un Token de Acceso Personal para obtener más información sobre cómo generar un token PAT.

Un token de acceso personal contiene sus credenciales de seguridad para Fluid. Un PAT lo identifica a usted, sus organizaciones accesibles y los alcances de acceso. Por ello, son tan críticos como las contraseñas, por lo que debe tratarlos de la misma manera.

Para Fluid, las instancias tienen el formato {organisation}.fluid.work/, por lo que el patrón se ve así:

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

Por ejemplo, así es como se obtiene una lista de mis acciones en Fluid.

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

Si desea proporcionar el token de acceso personal mediante un encabezado HTTP, primero debe convertirlo en una cadena Base64 (el siguiente ejemplo muestra cómo convertir a Base64 usando C#). (Algunas herramientas, como Postman, aplican una codificación Base64 de forma predeterminada. Si está probando la API mediante ese tipo de herramientas, no es necesario codificar el PAT en Base64.) La cadena resultante puede proporcionarse entonces como un encabezado HTTP con el siguiente formato:

Authorization: Basic BASE64PATSTRING

Aquí está en C# usando la [clase 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());
  }
}

Debería recibir una respuesta 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"
    }
]

Algunas llamadas a la API devuelven una lista de objetos JSON de respuesta; las Acciones, por ejemplo, pueden devolver una lista de Acciones. El número máximo de elementos que se devuelven en una respuesta es 50. Para obtener la lista completa de resultados, deberá realizar varias solicitudes a la API REST para obtener la siguiente página de resultados.

Los dos encabezados de respuesta HTTP Item-Count y Total-Count mencionados anteriormente contendrán valores que puede usar para pasar en solicitudes HTTP posteriores como valores de consulta de los parámetros "skip" y "take".

Si, por ejemplo, Total-Count = 150,  y Item-Count = 50, entonces el número total de objetos de respuesta es 150, el número actual de elementos devueltos es 50.

Para obtener la siguiente página de resultados, defina los parámetros de consulta ?skip=50, ?take=50. Esto omitirá los primeros 50 resultados que ya se devolvieron y devolverá el siguiente conjunto de resultados, tomando los siguientes 50 resultados. Si no especifica un valor para el parámetro de consulta take, se aplica internamente el valor máximo predeterminado de 50.

El encabezado de respuesta HTTP Total-Count seguirá mostrando 150, pero Item-Count ahora es 100.

Repita este proceso para obtener la siguiente página de resultados, defina el parámetro de consulta ?skip=100. Esto omitirá los primeros 100 resultados que ya se devolvieron y devolverá el siguiente conjunto de resultados, hasta el valor máximo de 50.

El encabezado de respuesta HTTP Total-Count seguirá mostrando 150, Item-Count ahora es 150. y la lista de la respuesta está vacía. lo que indica que ya se devolvieron todos los resultados.

A continuación se adjunta un archivo de colección de Postman que se puede usar para importar un conjunto de ejemplo de pruebas de solicitud/respuesta que sirven para verificar la API. Descargue el archivo adjunto e impórtelo en Postman.

Deberá actualizar los detalles de Autorización en Postman como se indica a continuación, seleccione el Tipo como Basic Auth, e ingrese el nombre de usuario de la cuenta que usará para acceder a la API, y la contraseña debe ser el token PAT de esa cuenta. Consulte Creando un Token de Acceso Personal para obtener más detalles.

Debe usar los valores de nombre de usuario y token devueltos por el proceso de Creando un Token de Acceso Personal, y no el token en base64.

Para la variable baseUrl, debe actualizarla según la URL de su organización en Fluid

• Prácticas recomendadas de la API REST

• Endpoint de la API REST para Acciones