REST API Best practices

TABLE OF CONTENTS

• Avoid polling
• Avoid concurrent requests
• Pause between mutative requests
• Handle rate limit errors appropriately
• Follow redirects
• Do not manually parse URLs
• Do not ignore errors

Avoid polling

You should subscribe to webhook events instead of polling the API for data. This will help your integration stay within the API rate limit. For more information, see How to configure Webooks to Fluid Boards integration

Avoid concurrent requests

To avoid exceeding secondary rate limits, you should make requests serially instead of concurrently. To achieve this, you can implement a queue system for requests.

Pause between mutative requests

If you are making a large number of POST, PATCH, PUT, or DELETE requests, wait at least one second between each request. This will help you avoid secondary rate limits.

Handle rate limit errors appropriately

If you receive a rate limit error, you should stop making requests temporarily according to these guidelines:

• If the x-ratelimit-reset response header is present, you should not retry your request until after timestamp.

• If the x-ratelimit-remaining header is 0, you should not make another request until after the time specified by the x-ratelimit-reset header. The x-ratelimit-reset header is in standard ISO 8601 for date time.

• Otherwise, wait for at least one minute before retrying. If your request continues to fail due to a secondary rate limit, wait for an exponentially increasing amount of time between retries, and throw an error after a specific number of retries.

Follow redirects

The Fluid REST API uses HTTP redirection where appropriate. You should assume that any request may result in a redirection. Receiving an HTTP redirection is not an error, and you should follow the redirect.

A 301 status code indicates permanent redirection. You should repeat your request to the URL specified by the location header. Additionally, you should update your code to use this URL for future requests.

A 302 or 307 status code indicates temporary redirection. You should repeat your request to the URL specified by the location header. However, you should not update your code to use this URL for future requests.

Other redirection status codes may be used in accordance with HTTP specifications.

Do not manually parse URLs

Many API endpoints return URL values for fields in the response body. You should not try to parse these URLs or to predict the structure of future URLs. This can cause your integration to break if Fluid changes the structure of the URL in the future.

Instead, you should look for a field that contains the information that you need. For example, the endpoint to create an Action returns an url field with a value like https://organisation.fluid.work/rest/api/action/1347 and a id field with a value like 1347. If you need to know the id of the issue, use this field instead of parsing the url field.

{
    "fields": {
        "createDate": "2023-10-13T18:50:01.0000000",
        "description": "Description 1",
        "modifiedDate": "2023-10-13T18:50:01.0000000",
        "priority": "Medium",
        "status": "Request",
        "taskType": "Task",
        "title": "Title 1"
    },
    "id": 4206,
    "guid": "0d0fcfb6-b1d9-41b0-8264-b29ace60df63",
    "url": "https://client.fluid.work/rest/api/action/4206"
}

Do not ignore errors

You should not ignore repeated 4xx and 5xx error codes. Instead, you should ensure that you are correctly interacting with the API. For example, if an endpoint requests a string and you are passing it a numeric value, you will receive a validation error. Similarly, attempting to access an unauthorized or nonexistent endpoint will result in a 4xx error.