Docs Ordnary Web Services Ordnary Halyard
Flags API
The HTTPS API your app uses: evaluating flags for a context, fetching an environment's configuration to evaluate locally, and errors.
Every request goes to https://halyard.ordnary.com/v1 and carries an environment's SDK key. CORS is open, so browsers can call it directly.
Authentication
Authorization: Bearer ofk_...Find the keys in the console, in your project under SDK keys. Rotating a key there stops the old one at once.
Evaluate flags
/v1/evaluateEvaluates every flag of the environment for one context, or only the ones you list.
contextobjectRequired- Who is asking.
keyis the stable id rollouts use; every other attribute is up to you. flagsarray- Flag keys to evaluate. Leave it out to get every flag.
/v1/evaluate{
"context": { "key": "user-123", "email": "ada@example.com", "country": "NL" },
"flags": ["new-checkout"]
}{
"environment": "production",
"flags": {
"new-checkout": { "value": true, "variation": 0, "reason": "rule_match", "ruleId": "staff" }
}
}-
valueanyThe variation the context gets: a boolean, string, number or JSON value.
-
variationintegerIts position in the flag's variations, starting at 0.
-
reasonstringoff(the flag is off),rule_match(a rule decided) ordefault. -
ruleIdstringThe rule that matched, with
rule_match.
Fetch the configuration
/v1/flagsEvery flag of the environment with its variations, state, rules and default, to evaluate locally.
A server that serves many users can fetch this every few seconds and evaluate in memory instead of making a request per user. Evaluate the way the server does: off variation when off, then rules from top to bottom, then the default.
{
"project": "Web app",
"environment": "production",
"flags": {
"new-checkout": {
"kind": "boolean",
"variations": [true, false],
"enabled": true,
"offVariation": 1,
"default": { "rollout": { "variations": [{ "variation": 0, "weight": 10 }, { "variation": 1, "weight": 90 }] } },
"rules": [
{ "id": "staff", "clauses": [{ "attribute": "email", "operator": "ends_with", "values": ["@yourcompany.com"] }], "serve": { "variation": 0 } }
],
"version": 4
}
}
}Rollout bucketing
To place a context in a rollout, take the SHA-1 of "<flag key>.<context key>", read its first 15 hex digits as a number and divide by 16^15. Multiply by 100 for a percentage, then walk the weights in order until their sum passes it. This is exactly what the server does, so local and server evaluation agree.
Errors
- 400
invalid_body: the request body is not the JSON described above.- 401
invalid_key: the SDK key is missing, wrong or has been rotated.- 404
not_found: an endpoint other thanGET /v1/flagsorPOST /v1/evaluate.