Fluid REST API Reference

Modified on Fri, 23 Feb 2024 at 07:36 PM

Welcome to the Fluid REST API Reference.

Representational State Transfer (REST) APIs are service endpoints that support sets of HTTP operations (methods), which provide create, retrieve, update, or delete access to the service's resources. This article walks you through:

The basic components of a REST API request/response pair.
Overviews of creating and sending a REST request, and handling the response.

Most REST APIs are accessible through our client libraries, which can be used to greatly simplify your client code.

We strongly encourage testing your code/scripts against your Sandbox environment and not directly against Production. If you don't currently have a Sandbox environment please contact your Fluid client success representative.

TABLE OF CONTENTS

Components of a REST API request/response pair
Create the request
Assemble the request
Process the response
Response Headers
Postman Request/Response
- Authentication
- Variables

Components of a REST API request/response pair

A REST API request/response pair can be separated into five components:

1. The request URI, in the following form: VERB https://{organisation}.fluid.work/rest/api/{resource}?version={version}

organisation: Your organization or server you're sending the request to. They are structured as follows:
resource path: The resource path is as follows: /rest/api/{resource}. For example /rest/api/action.
version: Every API request should include a version to avoid having your app or service break as APIs evolve. versions are in the following format: {major}.{minor}[-{stage}[.{resource-version}]], for example:
- version=3.0
- version=3.1-preview
- version=3.0-preview.1

2. HTTP request message header fields:

A required HTTP method (also known as an operation or verb), which tells the service what type of operation you are requesting. Fluid REST APIs support GET, HEAD, PUT, POST, and PATCH methods.
Optional additional header fields, as required by the specified URI and HTTP method. For example, an Authorization header that provides a bearer token containing client authorization information for the request.

3. Optional HTTP request message body fields, to support the URI and HTTP operation. For example, POST operations contain MIME-encoded objects that are passed as complex parameters.

For POST or PUT operations, the MIME-encoding type for the body should be specified in the Content-type request header as well. Some services require you to use a specific MIME type, such as application/json.

4. HTTP response message header fields:

An HTTP status code, ranging from 2xx success codes to 4xx or 5xx error codes. Alternatively, a service-defined status code may be returned, as indicated in the API documentation.
Optional additional header fields, as required to support the request's response, such as a Content-type response header.

5. Optional HTTP response message body fields:

MIME-encoded response objects may be returned in the HTTP response body, such as a response from a GET method that is returning data. Typically, these objects are returned in a structured format such as JSON, as indicated by the Content-type response header. Note for the purposes of the Fluid REST API responses are always returned in JSON format, irrespective of the Content-type set.

Create the request

Authenticate

The Fluid REST API currently only supports basic authentication with a username and PAT token. See the KB article Creating a Personal Access Token for more information on how to generate a PAT token.

About PATs

A personal access token contains your security credentials for Fluid. A PAT identifies you, your accessible organizations, and scopes of access. As such, they're as critical as passwords, so you should treat them the same way.

Assemble the request

For Fluid, instances are of the format {organisation}.fluid.work/, so the pattern looks like this:

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

For example, here's how to get a list of my actions in Fluid.

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

If you wish to provide the personal access token through an HTTP header, you must first convert it to a Base64 string (the following example shows how to convert to Base64 using C#). (Certain tools like Postman applies a Base64 encoding by default. If you are trying the API via such tools, Base64 encoding of the PAT is not required) The resulting string can then be provided as an HTTP header in the format:

Authorization: Basic BASE64PATSTRING

Here it is in C# using the [HttpClient class](/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());
  }
}

Process the response

You should get a response like this.

[
    {
        "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"
    }
]

Response Headers

Name	Type	Description
RateLimit-Limit	int	Max rate limit of requests allowed
RateLimit-Remaining	int	Remaining capacity of requests allowed
RateLimit-Reset	string	Next date time for refresh of capacity
Item-Count	int	Current number of items returned in this API response.
Total-Count	int	Total count of items that form this API response, for calls that return more than the max value of 50 items, this count is the total number of items that are apart of this response.

Postman Request/Response

Attached below is a Postman collection file that can be used to import a sample set of request/response tests that can be used to verify the API. Download the attached file and import into Postman.

Authentication

You will need to update the Authorization details as per below in Postman, select Type as Basic Auth, and enter the username of the account you will be using to access the API, and the password should be the PAT token for that account. See Creating a Personal Access Token for more details.

Variables

For the baseUrl variable, you should update this as per your Fluid organisation URL

Attachments (1)

json

Fluid REST A....json
118 KB