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": "on",
      "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.
On This Page: