Flipper Cloud

Flipper::Api

API for the Flipper gem.

Installation

Add this line to your application's Gemfile:

gem 'flipper-api'

And then execute:

$ bundle

Or install it yourself as:

$ gem install flipper-api

Usage

Flipper::Api is a mountable application that can be included in your Rails/Ruby apps. In a Rails application, you can mount Flipper::Api to a route of your choice:

# config/routes.rb
YourRailsApp::Application.routes.draw do
  mount Flipper::Api.app(Flipper) => '/flipper/api'
end

Mount Priority - important if using Flipper::UI

There can be more than one router in your application. Make sure if you choose a path that begins with the same pattern as where Flipper::UI is mounted that the app with the longer pattern is mounted first.

bad:

YourRailsApp::Application.routes.draw do
  mount Flipper::UI.app(Flipper) => '/flipper'
  mount Flipper::Api.app(Flipper) => '/flipper/api'
end

In this case any requests to /flipper* will be routed to Flipper::UI - including /flipper/api* requests. Simply swap these two to make sure that any requests that don't match /flipper/api* will be routed to Flipper::UI.

good:

YourRailsApp::Application.routes.draw do
  mount Flipper::Api.app(Flipper) => '/flipper/api'
  mount Flipper::UI.app(Flipper) => '/flipper'
end

For more advanced mounting techniques and for suggestions on how to mount in a non-Rails application, it is recommend that you review the Flipper::UI usage documentation as the same approaches apply to Flipper::Api.

Endpoints

Note: Example CURL requests below assume a mount point of /flipper/api.

Get all features

URL

GET /features

Request

curl http://example.com/flipper/api/features

Response

Returns an array of feature objects:

{
  "features": [
    {
      "key": "search",
      "state": "off",
      "gates": [
        {
          "key": "boolean",
          "name": "boolean",
          "value": false
        },
        {
          "key": "groups",
          "name": "group",
          "value": []
        },
        {
          "key": "actors",
          "name": "actor",
          "value": []
        },
        {
          "key": "percentage_of_actors",
          "name": "percentage_of_actors",
          "value": 0
        },
        {
          "key": "percentage_of_time",
          "name": "percentage_of_time",
          "value": 0
        },
      ]
    },
    {
      "key": "history",
      "state": "off",
      "gates": [
        {
          "key": "boolean",
          "name": "boolean",
          "value": false
        },
        {
          "key": "groups",
          "name": "group",
          "value": []
        },
        {
          "key": "actors",
          "name": "actor",
          "value": []
        },
        {
          "key": "percentage_of_actors",
          "name": "percentage_of_actors",
          "value": 0
        },
        {
          "key": "percentage_of_time",
          "name": "percentage_of_time",
          "value": 0
        }
      ]
    }
  ]
}

Create a new feature

URL

POST /features

Parameters

  • name - The name of the feature (Recommended naming conventions: lower case, snake case, underscores over dashes. Good: foo_bar, foo. Bad: FooBar, Foo Bar, foo bar, foo-bar.)

Request

curl -X POST -d "name=reports" http://example.com/flipper/api/features

Response

On successful creation, the API will respond with an empty JSON response.

Retrieve a feature

URL

GET /features/{feature_name}

Parameters

  • feature_name - The name of the feature to retrieve

Request

curl http://example.com/flipper/api/features/reports

Response

Returns an individual feature object:

{
  "key": "search",
  "state": "off",
  "gates": [
    {
      "key": "boolean",
      "name": "boolean",
      "value": false
    },
    {
      "key": "groups",
      "name": "group",
      "value": []
    },
    {
      "key": "actors",
      "name": "actor",
      "value": []
    },
    {
      "key": "percentage_of_actors",
      "name": "percentage_of_actors",
      "value": 0
    },
    {
      "key": "percentage_of_time",
      "name": "percentage_of_time",
      "value": 0
    }
  ]
}

Delete a feature

URL

DELETE /features/{feature_name}

Parameters

  • feature_name - The name of the feature to delete

Request

curl -X DELETE http://example.com/flipper/api/features/reports

Response

Successful deletion of a feature will return a 204 No Content response.

Clear a feature

URL

DELETE /features/{feature_name}/clear

Parameters

  • feature_name - The name of the feature to clear

Request

curl -X DELETE http://example.com/flipper/api/features/reports/clear

Response

Successful clearing (removing of all gate values) of a feature will return a 204 No Content response.

Gates

The API supports enabling / disabling any of the Flipper features. Gate endpoints follow the url convention:

enable

POST /{feature_name}/{gate_name}

disable

DELETE /{feature_name}/{gate_name}

and on a succesful request return a 200 HTTP status and the feature object as the response body.

Boolean enable a feature

URL

POST /features/{feature_name}/boolean

Parameters

  • feature_name - The name of the feature to enable

Request

curl -X POST http://example.com/flipper/api/features/reports/boolean

Response

Successful enabling of the boolean gate will return a 200 HTTP status and the feature object as the response body.

{
  "key": "reports",
  "state": "on",
  "gates": [
    {
      "key": "boolean",
      "name": "boolean",
      "value": true
    },
    {
      "key": "groups",
      "name": "group",
      "value": []
    },
    {
      "key": "actors",
      "name": "actor",
      "value": []
    },
    {
      "key": "percentage_of_actors",
      "name": "percentage_of_actors",
      "value": 0
    },
    {
      "key": "percentage_of_time",
      "name": "percentage_of_time",
      "value": 0
    }
  ]
}

Boolean disable a feature

URL

DELETE /features/{feature_name}/boolean

Parameters

  • feature_name - The name of the feature to disable

Request

curl -X DELETE http://example.com/flipper/api/features/reports/boolean

Response

Successful disabling of the boolean gate will return a 200 HTTP status and the feature object.

{
  "key": "reports",
  "state": "off",
  "gates": [
    {
      "key": "boolean",
      "name": "boolean",
      "value": false
    },
    {
      "key": "groups",
      "name": "group",
      "value": []
    },
    {
      "key": "actors",
      "name": "actor",
      "value": []
    },
    {
      "key": "percentage_of_actors",
      "name": "percentage_of_actors",
      "value": 0
    },
    {
      "key": "percentage_of_time",
      "name": "percentage_of_time",
      "value": 0
    }
  ]
}

Enable Group

URL

POST /features/{feature_name}/groups

Parameters

  • feature_name - The name of the feature

  • name - The name of a registered group to enable

Request

curl -X POST -d "name=admins" http://example.com/flipper/api/features/reports/groups

Response

Successful enabling of the group will return a 200 HTTP status and the feature object as the response body.

{
  "key": "reports",
  "state": "conditional",
  "gates": [
    {
      "key": "boolean",
      "name": "boolean",
      "value": false
    },
    {
      "key": "groups",
      "name": "group",
      "value": ["admins"]
    },
    {
      "key": "actors",
      "name": "actor",
      "value": []
    },
    {
      "key": "percentage_of_actors",
      "name": "percentage_of_actors",
      "value": 0
    },
    {
      "key": "percentage_of_time",
      "name": "percentage_of_time",
      "value": 0
    }
  ]
}

Disable Group

URL

DELETE /features/{feature_name}/groups

Parameters

  • feature_name - The name of the feature

  • name - The name of a registered group to disable

Request

curl -X DELETE -d "name=admins" http://example.com/flipper/api/features/reports/groups

Response

Successful disabling of the group will return a 200 HTTP status and the feature object as the response body.

{
  "key": "reports",
  "state": "off",
  "gates": [
    {
      "key": "boolean",
      "name": "boolean",
      "value": false
    },
    {
      "key": "groups",
      "name": "group",
      "value": []
    },
    {
      "key": "actors",
      "name": "actor",
      "value": []
    },
    {
      "key": "percentage_of_actors",
      "name": "percentage_of_actors",
      "value": 0
    },
    {
      "key": "percentage_of_time",
      "name": "percentage_of_time",
      "value": 0
    }
  ]
}

Enable Actor

URL

POST /features/{feature_name}/actors

Parameters

  • feature_name - The name of the feature

  • flipper_id - The flipper_id of actor to enable

Request

curl -X POST -d "flipper_id=User;1" http://example.com/flipper/api/features/reports/actors

Response

Successful enabling of the actor will return a 200 HTTP status and the feature object as the response body.

{
  "key": "reports",
  "state": "conditional",
  "gates": [
    {
      "key": "boolean",
      "name": "boolean",
      "value": false
    },
    {
      "key": "groups",
      "name": "group",
      "value": []
    },
    {
      "key": "actors",
      "name": "actor",
      "value": ["User;1"]
    },
    {
      "key": "percentage_of_actors",
      "name": "percentage_of_actors",
      "value": 0
    },
    {
      "key": "percentage_of_time",
      "name": "percentage_of_time",
      "value": 0
    }
  ]
}

Disable Actor

URL

DELETE /features/{feature_name}/actors

Parameters

  • feature_name - The name of the feature

  • flipper_id - The flipper_id of actor to disable

Request

curl -X DELETE -d "flipper_id=User;1" http://example.com/flipper/api/features/reports/actors

Response

Successful disabling of the actor will return a 200 HTTP status and the feature object as the response body.

{
  "key": "reports",
  "state": "off",
  "gates": [
    {
      "key": "boolean",
      "name": "boolean",
      "value": false
    },
    {
      "key": "groups",
      "name": "group",
      "value": []
    },
    {
      "key": "actors",
      "name": "actor",
      "value": []
    },
    {
      "key": "percentage_of_actors",
      "name": "percentage_of_actors",
      "value": 0
    },
    {
      "key": "percentage_of_time",
      "name": "percentage_of_time",
      "value": 0
    }
  ]
}

Enable Percentage of Actors

URL

POST /features/{feature_name}/percentage_of_actors

Parameters

  • feature_name - The name of the feature

  • percentage - The percentage of actors to enable

Request

curl -X POST -d "percentage=20" http://example.com/flipper/api/features/reports/percentage_of_actors

Response

Successful enabling of a percentage of actors will return a 200 HTTP status and the feature object as the response body.

{
  "key": "reports",
  "state": "conditional",
  "gates": [
    {
      "key": "boolean",
      "name": "boolean",
      "value": false
    },
    {
      "key": "groups",
      "name": "group",
      "value": []
    },
    {
      "key": "actors",
      "name": "actor",
      "value": []
    },
    {
      "key": "percentage_of_actors",
      "name": "percentage_of_actors",
      "value": 20
    },
    {
      "key": "percentage_of_time",
      "name": "percentage_of_time",
      "value": 0
    }
  ]
}

Disable Percentage of Actors

URL

DELETE /features/{feature_name}/percentage_of_actors

Parameters

  • feature_name - The name of the feature

Request

curl -X DELETE http://example.com/flipper/api/features/reports/percentage_of_actors

Response

Successful disabling of a percentage of actors will set the percentage to 0 and return a 200 HTTP status and the feature object as the response body.

{
  "key": "reports",
  "state": "off",
  "gates": [
    {
      "key": "boolean",
      "name": "boolean",
      "value": false
    },
    {
      "key": "groups",
      "name": "group",
      "value": []
    },
    {
      "key": "actors",
      "name": "actor",
      "value": []
    },
    {
      "key": "percentage_of_actors",
      "name": "percentage_of_actors",
      "value": 0
    },
    {
      "key": "percentage_of_time",
      "name": "percentage_of_time",
      "value": 0
    }
  ]
}

Enable Percentage of Time

URL

POST /features/{feature_name}/percentage_of_time

Parameters

  • feature_name - The name of the feature

  • percentage - The percentage of time to enable

Request

curl -X POST -d "percentage=20" http://example.com/flipper/api/features/reports/percentage_of_time

Response

Successful enabling of a percentage of time will return a 200 HTTP status and the feature object as the response body.

{
  "key": "reports",
  "state": "conditional",
  "gates": [
    {
      "key": "boolean",
      "name": "boolean",
      "value": false
    },
    {
      "key": "groups",
      "name": "group",
      "value": []
    },
    {
      "key": "actors",
      "name": "actor",
      "value": []
    },
    {
      "key": "percentage_of_actors",
      "name": "percentage_of_actors",
      "value": 0
    },
    {
      "key": "percentage_of_time",
      "name": "percentage_of_time",
      "value": 20
    }
  ]
}

Disable Percentage of Time

URL

DELETE /features/{feature_name}/percentage_of_time

Parameters

  • feature_name - The name of the feature

Request

curl -X DELETE http://example.com/flipper/api/features/reports/percentage_of_time

Response

Successful disabling of a percentage of time will set the percentage to 0 and return a 200 HTTP status and the feature object as the response body.

{
  "key": "reports",
  "state": "off",
  "gates": [
    {
      "key": "boolean",
      "name": "boolean",
      "value": false
    },
    {
      "key": "groups",
      "name": "group",
      "value": []
    },
    {
      "key": "actors",
      "name": "actor",
      "value": []
    },
    {
      "key": "percentage_of_actors",
      "name": "percentage_of_actors",
      "value": 0
    },
    {
      "key": "percentage_of_time",
      "name": "percentage_of_time",
      "value": 0
    }
  ]
}

Check if features are enabled for an actor

URL

GET /actors/{flipper_id}

Parameters

  • keys - comma-separated list of features to check

Request

curl -X GET http://example.com/flipper/api/actors/User;1?keys=my_feature_1,my_feature_2

Response

Returns whether the actor with the provided flipper_id is enabled for the specififed feature keys.
If no keys are specified all features are returned.

{
  "flipper_id": "User;1",
    "features": {
      "my_feature_1": {
        "enabled": true,
      },
      "my_feature_2": {
        "enabled": false,
      }
    }
}

Errors

In the event of an error the Flipper API will return an error object. The error object will contain a Flipper-specific error code, an error message, and a link to documentation providing more information about the error.

example error object

{
    "code": 1,
    "message": "Feature not found",
    "more_info": "https://flippercloud.io/docs/api#error-code-reference",
}

Error Code Reference

1: Feature Not Found

The requested feature does not exist. Make sure the feature name is spelled correctly and exists in your application's database.

2: Group Not Registered

The requested group specified by the name parameter is not registered. Information on registering groups can be found in the features documentation.

3: Percentage Invalid

The percentage parameter is invalid or missing. percentage must be an integer between 0-100 inclusive and cannot be blank.

4: Flipper ID Invalid

The flipper_id parameter is invalid or missing. flipper_id cannot be empty.

5: Name Invalid

The name parameter is missing. Make sure your request's body contains a name parameter.

Start flipping features with Flipper Cloud to get support, audit history, finer-grained permissions, multi-environment sync, and all of your projects in one place.
Start Your Trial
Prefer our open source Cloudless option? You can also choose from several tiers to sponsor Flipper on GitHub.
Become a Sponsor
On This Page: