API style guide helps everyone to adhere to basic API design patterns and conventions. Apiary Style Guide enables you to check multiple API Blueprints for consistency. The real benefit is the developer experience—consistency means predictability.

Check API's

With Apiary Style Guide, API designers receive real-time feedback during the API design process.

Real-time validation

Inconsistencies are caught very early in the cycle, helping you to avoid boring and expensive code refactor after APIs have been developed, deployed, and consumed.

API Design Assertion Language:

To a define a Design Assertion, two parts are needed: Functions Definition and Rules Definition

Definitions

Functions Definition:

A set of JavaScript functions used for validations.

/*
Validates if JSON body string is a pretty printed JSON. It naively expects
at least one line per key in parsed object.

@targets: Request_Body, Response_Body
 */

function validatePrettyPrintedJson(json) {
  var countKeys, data, e, keyCount, linesCount;
  if ((json == null) || json === "") {
    return true;
  }
  try {
    data = JSON.parse(json);
  } catch (_error) {
    e = _error;
    return true;
  }
  if (typeof data !== 'object') {
    return true;
  }
  keyCount = 0;
  function countKeys(obj) {
    var key, results, value;
    results = [];
    for (key in obj) {
      value = obj[key];
      if (typeof value === 'object') {
        keyCount = keyCount + 1;
        results.push(countKeys(value));
      } else {
        results.push(keyCount = keyCount + 1);
      }
    }
    return results;
  };
  countKeys(data);
  linesCount = json.split("\n").length;
  if (linesCount >= keyCount) {
    return true;
  } else {
    return "JSON is not pretty-printed, expecting one key per line.";
  }
};

Each function has one input parameter - JSON object found on desired path in refract tree. Function is not executed if no object is found. The function must return true if validation passes or a string which describes reason of failure if validation fails. Each function should have a block comment which describes its purpose. Comments can contain a @targets annotations which contain comma-separated lists of allowed targets to which this function can be applied. All supported targets are allowed if @targets annotation is not defined:

Supported targets

root
Metadata
API_Name
Description
Resource_Group
Resource_Group_Name
Resource_Group_Description
Resource
Resource_Name
Resource_Description
Resource_URI_Template
Resource_Parameters
Action
Action_Name
Action_Method
Action_Description
Action_Parameters
Action_Example
Request
Request_Description
Request_Body
Request_Schema
Request_Headers
Request_Header
Response
Response_Status_Code
Response_Description
Response_Body
Response_Schema
Response_Headers
Response_Header
Header

Rules Definition:

A list of rules connecting functions definition to Refract targets.

Each rule has the following attributes:

[
  {
    "intent": "All `id` keys in request JSON body object should be in format of UUID because ...",
    "ruleName": "request UUID id",
    "functionName": "validateUUIDInJsonIdKeys",
    "target": "Request_Body"
  },
  {
    "intent": "All `id` keys in response JSON body object should be in format of UUID because ...",
    "ruleName": "response UUID id",
    "functionName": "validateUUIDInJsonIdKeys",
    "target": "Response_Body"
  }
]
Was this page useful?
Thank you for the feedback!
What went wrong?

Related topics