HTTP API
What is the HTTP API?
Our front-facing API is a simple JSON HTTP API that can be used from browsers and backend services.
Authentication
Authentication happens by way of either a publishable key or a secret key. Publishable keys and secret keys are unique for each Bucket environment. You can find the keys in the Settings
tab under Environments
.
Publishable keys are meant to be used in clients where your code is public in some form, for example browser or mobile applications. The secret key should stay secret and only be used on your backend services.
Secret keys can be provided to the API in the Authorization
header as:
Authorization: Bearer <key>
Publishable keys can be either provided in the Authorization
header similar to secret keys or simply as a query parameter:
GET /features/enabled?publishableKey=<key>
Global infrastructure
The HTTP API resides at: https://front.bucket.co/
Request to the front-facing API are automatically routed to a datacenter near you and should thus have a relative low latency regardless of where your customers are. Get in touch if you have many customers who are experiencing >100ms latency and we'd be happy to look into setting up a point of presence closer to you.
Use https://front-eu.bucket.co
if you want to avoid your requests being served by a non-EU server due to regulatory concerns.
API Endpoints
Endpoint | Publishable Key | Secret key | Description |
---|---|---|---|
| Retrieve all features with their respective targeting rules | ||
| Retrieve features that are enabled for the provided user/company | ||
| Send events related to feature targeting | ||
| Update user in Bucket | ||
| Update company in Bucket | ||
| Send events related to feature usage or user actions | ||
| Send multiple calls in bulk. |
Note: For POST requests, the API only accepts JSON. The Content-Type header must be set to application/json
.
GET /features
GET /features
This endpoint lets you get the full list of features along with their targeting rules. The endpoint is useful for backend SDKs to pull the targeting rules and evaluate them locally to determine which features should be enabled for a giver user/company instead of using the features/enabled
endpoint for each user/company.
GET /features/enabled
GET /features/enabled
The flags/evaluate
method lets you get a list of flags that are enabled given a specific context.
The features/enabled
endpoint lets you get a list of features that are enabled for a specific user/company.
Example
The flags/evaluate
HTTP endpoint is a GET
request to ensure that request can be completed without the need for a CORS Preflight request. The context must be flattened and provided as query parameters. In this case: context.company.id=42&context.user.id=99
The feature/enabled
HTTP endpoint is a GET
request to ensure that the request can be completed without a CORS Preflight
request to reduce latency.
The context must be flattened and provided as query parameters.
Example
context.company.id=42&context.user.id=99
Second Example
This is a more realistic example of context
that lets you write advanced feature targeting rules.
Note: The Bucket UI uses the attributes provided in the company
endpoint to determine which companies have which flags enabled. Make sure that any company
attributes you use in the context are also provided through the company
endpoint.
Note: The Bucket UI uses the attributes provided in the company
endpoint to determine which companies have which features enabled. Ensure any company
attributes used in the context
are also provided through the company
endpoint.
POST /features/events
POST /features/events
The /features/events
endpoint is used to send "evaluate" and "check" events. These events are used for various purposes in the Bucket UI. An evaluation event should be emitted when a targeting rule is evaluated. This happens automatically for the /features/enabled
endpoint. A "check" event should be generated whenever code checks for whether a specific feature is enabled.
POST /user
POST /user
The User method is used to track individual users in your application. This method will create a user, if it doesn't exist already. For existing users, it will update it. Use a unique identifier that won't change for userId
, e.g. the database ID.
The user
endpoint is used to track individual users in your application. This method will create a user if it doesn't exist already. For existing users, it will update it.
userId
should use a unique identifier that won't change, like a database ID.
You can pass along attributes which will be set for the given user. Attributes on users are not useful in Bucket yet.
You can pass along attributes that will be set for the given user. User attributes are not useful in Bucket at this time.
Here's an example:
Example
field | required | Type |
---|---|---|
userId | Required | String |
attributes | Optional | Object |
timestamp | Optional | ISO 8601 |
Field | Required | Type |
---|---|---|
userId | Required | String |
attributes | Optional | Object |
timestamp | Optional | ISO 8601 |
Company
POST /company
POST /company
The Company method is used to track companies (organizations) in your B2B application. Use a unique identifier that won't change for companyId
, e.g. the database ID.
The Company
method is used to track companies (organizations) in your B2B application.
companyId
should use a unique identifier that won't change, like a database ID.
You can associate a user to a company by providing userId
. This is important as most features in Bucket will look at company-level data. In other words, if a user isn't associated with a company, the users' events will not be included in most of the results. The "Tracking" tab in the Bucket UI will let you know if you have unassociated events.
You can associate a user with a company by providing the userId
. This is important as features in Bucket look at company-level data.
In other words, if a user isn't associated with a company, their events will not be included.
The Tracking
tab will let you know if you have unassociated events.
Just as with the user
call, you can send attributes to be associated with that company. In addition to traditional user tracking based on events sent, you can also track feature usage based on attributes with Bucket. For example, if you set hasSlackEnabled: true
on specific companies, you can create an "attribute based Feature" in the Bucket UI to track which companies have slack enabled.
You can send attributes to be associated with a company. In addition to traditional event-based user tracking, you can track feature usage based on attributes.
Example
If you set hasSlackEnabled: true
for specific companies, you can create an Attribute-based feature
in Bucket to track which companies have Slack enabled.
You're also likely to call this method when a user signs in to ensure that the user is associated with a company.
You're also likely to call this method when a user signs in to ensure they are associated with a company.
field | required | Type |
---|---|---|
companyId | Required | String |
attributes | Optional | Object |
timestamp | Optional | ISO 8601 String |
userId | Optional | String |
field | required | Type |
---|---|---|
companyId | Required | String |
attributes | Optional | Object |
timestamp | Optional | ISO 8601 String |
userId | Optional | String |
Event
POST /event
POST /event
Events are used to track user interactions within your application. We recommend tracking a handful of key features and features you're currently working on.
Events are used to track user interactions within your application. We recommend tracking a handful of key features and features being currently worked on.
To track an event, call this method when users interact with a feature.
To track an event
, call this method when users interact with a feature.
field | required | Type |
---|---|---|
event | Required | String |
userId | Required | String |
attributes | Optional | Object |
timestamp | Optional | ISO 8601 |
field | required | Type |
---|---|---|
event | Required | String |
userId | Required | String |
attributes | Optional | Object |
timestamp | Optional | ISO 8601 |
Feedback
Feedback
You can submit qualitative feedback related to a specific feature in order to pair your quantitative metrics with qualitative insigths. You can collect either a 1-5 satisfaction score or a comment or both.
You can submit qualitative feedback related to a specific feature to pair your quantitative metrics with qualitative insights.
You can collect a 1-5 satisfaction score, qualitative feedback, or both.
At least one of the optional fields score
or comment
must be submitted
At least one of the optional fields, score
or comment
, must be submitted.
field | required | Type |
---|---|---|
featureId | Required | String |
userId | Required | String |
companyId | Optional | String |
score | Optional | Number (1-5) |
comment | Optional | String |
field | required | Type |
---|---|---|
featureId | Required | String |
userId | Required | String |
companyId | Optional | String |
score | Optional | Number (1-5) |
comment | Optional | String |
What is the HTTP API?
Our front-facing API is a simple JSON HTTP API that can be used from browsers and backend services.
Authentication
Authentication happens by way of either a publishable key or a secret key. Publishable keys and secret keys are unique for each Bucket environment. You can find the keys in the Settings
tab under Environments
.
Publishable keys are meant to be used in clients where your code is public in some form, for example, browser or mobile applications. The secret key should stay secret and only be used on your backend services.
Secret keys can be provided to the API in the Authorization
header as:
Authorization: Bearer <key>
Publishable keys can be either provided in the Authorization
header similar to secret keys or simply as a query parameter:
GET /features/enabled?publishableKey=<key>
Global infrastructure
The HTTP API resides at: https://front.bucket.co/
Requests to the front-facing API are automatically routed to a data center near you and should have a relatively low latency regardless of where customers are. If you have many customers experiencing >100ms latency, get in touch and we'd be happy to look into setting up a point of presence closer to you.
Use https://front-eu.bucket.co
if you want to avoid your requests being served by a non-EU server due to regulatory concerns.
API Endpoints
Endpoint | Publishable Key | Secret key | Description |
---|---|---|---|
| Retrieve all features with their respective targeting rules | ||
| Retrieve features that are enabled for the provided user/company | ||
| Send events related to feature targeting | ||
| Update user in Bucket | ||
| Update company in Bucket | ||
| Send events related to feature usage or user actions | ||
| Send multiple calls in bulk. |
For POST requests, the API only accepts JSON. The Content-Type header must be set to application/json
.
GET /features
GET /features
This endpoint lets you get the full list of features along with their targeting rules. The endpoint is useful for backend SDKs to pull the targeting rules and evaluate them locally to determine which features should be enabled for a giver user/company instead of using the features/enabled
endpoint for each user/company.
GET /features/enabled
GET /features/enabled
The features/enabled
endpoint lets you get a list of features enabled for a specific user/company.
Example
The feature/enabled
HTTP endpoint is a GET
request to ensure that the request can be completed without a CORS Preflight
request to reduce latency.
The context must be flattened and provided as query parameters.
Example
context.company.id=42&context.user.id=99
Other example
This is a more realistic example of context
that lets you write advanced feature targeting rules.
Note: The Bucket UI uses the attributes provided in the company
endpoint to determine which companies have which features enabled. Ensure any company
attributes used in the context
are also provided through the company
endpoint.
POST /features/events
POST /features/events
The /features/events
endpoint is used to send "evaluate" and "check" events. These events are used for various purposes in the Bucket UI. An evaluation event should be emitted when a targeting rule is evaluated. This happens automatically for the /features/enabled
endpoint. A "check" event should be generated whenever code checks for whether a specific feature is enabled.
POST /user
POST /user
The user
endpoint is used to track individual users in your application. This method will create a user if it doesn't exist already. For existing users, it will update it.
userId
should use a unique identifier that won't change, like a database ID.
You can pass along attributes that will be set for the given user. User attributes are not useful in Bucket at this time.
You'll likely call this method when a user signs into your app.
Example
Field | Required | Type |
---|---|---|
userId | Required | String |
attributes | Optional | Object |
timestamp | Optional | ISO 8601 |
POST /company
POST /company
The Company
method is used to track companies (organizations) in your B2B application.
companyId
should use a unique identifier that won't change, like a database ID.
You can associate a user with a company by providing the userId
. This is important as features in Bucket look at company-level data.
In other words, if a user isn't associated with a company, their events will not be included.
The Tracking
tab will let you know if you have unassociated events.
You can send attributes to be associated with a company. In addition to traditional event-based user tracking, you can track feature usage based on attributes.
Example
If you set hasSlackEnabled: true
for specific companies, you can create an Attribute-based feature
in Bucket to track which companies have Slack enabled.
You're also likely to call this method when a user signs in to ensure they are associated with a company.
field | required | Type |
---|---|---|
companyId | Required | String |
attributes | Optional | Object |
timestamp | Optional | ISO 8601 String |
userId | Optional | String |
POST /event
POST /event
Events are used to track user interactions within your application. We recommend tracking a handful of key features and features being currently worked on.
To track an event
, call this method when users interact with a feature.
field | required | Type |
---|---|---|
event | Required | String |
userId | Required | String |
attributes | Optional | Object |
timestamp | Optional | ISO 8601 |
Feedback
You can submit qualitative feedback related to a specific feature to pair your quantitative metrics with qualitative insights.
You can collect a 1-5 satisfaction score, qualitative feedback, or both.
At least one of the optional fields, score
or comment
, must be submitted.
field | required | Type |
---|---|---|
featureId | Required | String |
userId | Required | String |
companyId | Optional | String |
score | Optional | Number (1-5) |
comment | Optional | String |
Note: You can find the featureId
in the URL when viewing a feature.
Responses
The API will return a 200
status code when calls are successful and a 400
if there are errors, including an invalid request body.
The response body will contain detailed information on the invalid request which can be used to debug. If you receive a 400 response code, there's no point in retrying without first debugging.
You may receive a 500
status code. If so, you can retry the request. If you send events to Bucket, this can technically result in duplicate entries but this is increasingly rare.
Note: You can find the featureId
in the URL when viewing a feature.
Responses
The API will return a 200
status code when calls are successful and a 400
if there are errors, including an invalid request body.
The response body will contain detailed information on the invalid request which can be used to debug. If you receive a 400 response code, there's no point in retrying without first debugging.
You may receive a 500
status code. If so, you can retry the request. If you send events to Bucket, this can technically result in duplicate entries but it is increasingly rare.
Last updated