API Reference

Overview

Zenmanage provides a simple JSON-based API to retrieve your project and environment feature flags. The standard endpoint for requests is https://api.zenmanage.com. Make sure you set the HTTP Content-Type header to be application/json.

OpenAPI v3 Specification

Zenmanage provides an Open API specification for the API here:

https://api.zenmanage.com/v1/api-docs

Authentication

All requests to the API require an environment key to be present in the request header. The environment key for the specific environment can be found in the Admin section of Zenmanage. Remember to treat keep these keys secure. Any request with your specific environment key will allow access to your feature flags.

The standard header for the key is X-API-KEY. If this header is not compatible with your application you can alternately use the X-ZENMANAGE-KEY header.

Example

X-API-KEY: sample-token

Limitations

Requests to the API are rate limited. Your application may make up to 60 requests per minute to the API. If you require more than this limit, please contact hello@zenmanage.com.

Context

Context allows you to provide Zenmanage with information about who or what is calling the API. This is especially useful when you want to target specific values to a context or group of contexts (called segments) in your application. Contexts are optional and not required to use Zenmanage.

You can think of contexts as being an entity requesting flags from Zenmanage. This could be a user, a service, or any other thing you need it to be.

Context is passed to the API through a header on the request. The standard header for the context is X-ZENMANAGE-CONTEXT. If this header is not compatible with your application you can alternately use the C header. The header should be formatted as a JSON string.

By default, the context requires a type and an identifier. You may also include a name which will be used by Zenmanage to provide a friendly reference to the context. Optionally, you can provide attributes which should be denoted as an array of key/value pairs where the value can also be an array.

Example

X-ZENMANAGE-CONTEXT: { "type": "user", "name": "John Doe", "identifier": "5ca10e14-f587-4805-9d48-e00c76f9e780", "attributes": { "company_id": 12456, "region": "west", "licenses": [ "AB2912", "TD2102" ] } }

Default Values

Default values are a way to notify Zenmanage of what your app will serve if Zenmanage is not available. By notifying Zenmanage, you will be able to see how a flag will respond and be notified if a default value is missing allowing you application to function as you expect. Sending default values is option but highly recommended.

Default values are passed to the API through a header on the request. The standard header for the value is X-DEFAULT-VAUE. The header should be formatted as a JSON string.

Example

X-DEFAULT-VALUE: [ { "key": "example-boolean", "type": "boolean", "value": false }, { "key": "example-string", "type": "STRING", "value": "" } ]

Endpoints

Flags

The endpoint for retrieving feature flags from Zenmanage.

All Flags

GET https://api.zenmanage.com/v1/flags

Attributes

None. This endpoint does not require any attributes other than the headers specified above for authentication, and optionally, context.

Response

HTTP 200 OK

The results of evaluating all of the rules for the feature flags for the project/environment.

BODY

{
  "status": "success",
  "data": [
      {
          "flag": {
              "key": "sample-flag-1",
              "name": "Sample Flag 1",
              "type": "boolean",
              "value": {
                  "boolean": false
              }
          }
      },
      {
          "flag": {
              "key": "sample-flag-2",
              "name": "Sample Flag 2",
              "type": "boolean",
              "value": {
                  "boolean": true
              }
          }
      },
  ]
}
      

HTTP 400 Bad Request

The context supplied to the API is not formatted properly and cannot be decoded. Context is not required and so if it will only occur if there is a context supplied and it is invalid.

BODY

{
  "status": "error",
  "message": "Context was supplied but is invalid."
}
      

HTTP 401 Unauthorized

The public token for the environment is not valid or was not provided and no flags were evaluated.

BODY

{
  "status": "error",
  "message": "Invalid API key provided."
}
      

Single Flag

GET https://api.zenmanage.com/v1/flags/{flag-key}

Attributes

Response

HTTP 200 OK

The results of evaluating all the rules for a single feature flag for the project/environment.

BODY

{
  "status": "success",
  "data": {
    "flag": {
      "key": "sample-flag-1",
      "name": "Sample Flag 1",
      "type": "boolean",
      "value": {
          "boolean": false
      }
    }
  }
}
      

HTTP 401 Unauthorized

The public token for the environment is not valid or was not provided and no flags were evaluated.

BODY

{
  "status": "error",
  "message": "Invalid API key provided."
}
      

HTTP 404 Not Found

The feature flag could not be found in the environment.

BODY

{
  "status": "error",
  "message": "Feature flag not found."
}
      

Reporting Usage

POST https://api.zenmanage.com/v1/flags/{flag-key}/usage

Attributes

Response

HTTP 200 OK

Indicates successful recording of the usage of the flag.

BODY

{
  "status": "success",
}
      

HTTP 401 Unauthorized

The public token for the environment is not valid or was not provided and no flags were reported.

BODY

{
  "status": "error",
  "message": "Invalid API key provided."
}
      

HTTP 404 Not Found

The feature flag could not be found in the environment.

BODY

{
  "status": "error",
  "message": "Feature flag not found."
}