Getting started with the REST API

Modified on Thu, 13 Jun at 11:39 AM

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.

You can use Fluids API to build scripts and applications that automate processes, integrate with Fluid, and extend Fluid. For example, you could use the API to triage Action RAG statuses, projects and boards.

Each REST API endpoint is documented individually, and the endpoints are categorized by the resource that they primarily affect. For example, you can find endpoints relating to action under the Action folder in "REST Api endpoint for Actions"

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.

Developer online Open API documentation can be found at https://organisation.fluid.work/docs

See the end of this article for a Postman collection that can be imported and used for test/development purposes.

TABLE OF CONTENTS

Components of a REST API request/response pair
Elements of a REST API Request
HTTP method
Path
Headers
Content types
Authentication
Parameters
Create the request
Assemble the request
Process the response
Response Headers
Paging Responses
Postman Request/Response
- Authentication
- Variables
Further Reading

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.

Every request to the REST API includes an HTTP method and a path. Depending on the REST API endpoint, you might also need to specify request headers, authentication information, query parameters, or body parameters.

The REST API reference documentation describes the HTTP method, path, and parameters for every endpoint. It also displays example requests and responses for each endpoint. For more information, see the REST reference documentation.

HTTP method

The HTTP method of an endpoint defines the type of action it performs on a given resource. Some common HTTP methods are GET, POST, DELETE, and PATCH. The REST API reference documentation provides the HTTP method for every endpoint.

For example, the HTTP method for the "List repository issues" endpoint is GET."

Where possible, the Fluid REST API strives to use an appropriate HTTP method for each action.

GET: Used for retrieving resources.

POST: Used for creating resources.

PUT: Used for replacing resources or collections of resources.

DELETE: Used for deleting resources.

Path

Each endpoint has a path. The REST API reference documentation gives the path for every endpoint. For example, the path to get a specific action for a specific ID, the endpoint is http://organisation.fluid.work/rest/api/action/{id}.

The curly brackets {} in a path denote path parameters that you need to specify. Path parameters modify the endpoint path and are required in your request.

Headers

Headers provide extra information about the request and the desired response. Following are some examples of headers that you can use in your requests to the Fluid REST API. For an example of a request that uses headers, see "Making a request."

Content types

Content types specify the format of the data you want to consume from the API. Content types are specific to resources, allowing them to change independently and support formats that other resources don't. Fluid uses content type application/json.

Authentication

All endpoints require authentication.

Parameters

Many API methods require or allow you to send additional information in parameters in your request. There are a few different types of parameters: Path parameters, body parameters, and query parameters.

Path parameters

Path parameters modify the endpoint path. These parameters are required in your request. For more information, see "Path."

Body parameters

Body parameters allow you to pass additional data to the API. These parameters can be optional or required, depending on the endpoint. For example, a body parameter may allow you to specify an issue title when creating a new issue, or specify certain settings when enabling or disabling a feature. The documentation for each Fluid REST API endpoint will describe the body parameters that it supports.

For example, the "Create an Action" endpoint requires that you specify a title for the new Action in your request. It also allows you to optionally specify other information, such as text to put in the Action description, users to assign to the new Action etc.

Query parameters

Query parameters allow you to control what data is returned for a request. These parameters are usually optional. The documentation for each Fluid REST API endpoint will describe any query parameters that it supports.

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.

Paging Responses

Some API calls will return a list of response JSON objects, Actions for example can return a list of Actions. The maximum number of items to return in a response is 50. To get the full list of response you will need to make multiple REST API requests to get the next page of results.

The two HTTP response headers Item-Count and Total-Count mentioned above will contain values that you can use to pass in to subsequent HTTP requests as query values for parameters "skip" and "take".

If for example if Total-Count = 150, and Item-Count = 50, then the total number of response objects is 150, current number of items returned is 50.

To get the next page of results, set query parameters ?skip=50, ?take=50. This will skip the first 50 results that have already been returned and will return the next set of results, and take the next 50 results. If you do not specify a value a take query parameter, the default max value of 50 is applied internally..

The Http response header Total-Count will still show 150, but Item-Count is now 100.

Repeat this process to get the next page of results, set query parameters ?skip=100. This will skip the first 100 results that have already been returned and will return the next set of results, up to the max value of 50.

The Http response header Total-Count will still show 150, Item-Count is now 150. and the response list response is empty. indicating all results have now been returned.

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.

You should use the username and token values as returned by the Creating a Personal Access Token process and not the base64 token.

Variables

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

Getting started with the REST API

Components of a REST API request/response pair

Elements of a REST API Request

HTTP method

Path

Headers

Content types

Authentication

Parameters

Path parameters

Body parameters

Query parameters

Create the request

Assemble the request

Process the response

Response Headers

Paging Responses

Postman Request/Response

Authentication

Variables

Further Reading