jsight-server-api.jst

JSIGHT 0.3

INFO
  Title "JSight Server API"
  Version "2.0.0"
  Description
  (
    # Introduction

    The file describes the JSight Server API, which is used in [JSight Online Editor](https://editor.jsight.io/).

    # Requirements to this API

    Schema must be:

    - compact (will be transmitted over network),
    - comfortable for document rendering algorithm,
    - easy for reading by man (will be used for functional automatically tests).

    # Format size optimization options (for the future)
    
    1. Discard fields that are easily calculated, for example, the json Type field is easily calculated from the content.
    2. Frequent fields should be named with one letter, for example, 't' instead of 'type'.
    3. Abandon structures that are easily calculated, for example, 'allOf'.
  )

POST /parse-jsight
  Description
    You should send JSight code in request.

  Request
    Headers
        {
            "X-Browser-UUID": "123e4567-e89b-12d3-a456-426614174000"
        }
    Body any # JSight code

  200 @jdocExchange // Successfully parsed response.
    Headers
        {
            "X-Jdoc-Exchange-Version": "2.0.0"
        }

  409 @error // Any parsing error.
    
TYPE @error
{
    "Status": "Error", // {const: true}
    "Message": "Error message",
    "Line": 10, // {optional: true, min: 0}
    "Index": 20 // {optional: true, min: 0}
}

TYPE @jdocExchange
{
  "jdocExchangeVersion": "2.0.0",                             // {const: true}
  "jsight": "0.3",                                            // {const: true}
  "info": {                                                   // {optional: true}
    "title": "Catsbook API.",                                 // {optional: true}
    "version": "0.1",                                         // {optional: true}
    "description": "Catsbook social network public REST API." // {optional: true}
  },
  "servers": { // {additionalProperties: "@server", optional: true}
    @serverName: @server // { optional: true }
  },
  "tags": { // {additionalProperties: "@tag"}
    @tagName: @tag // {optional: true}
  },
  "interactions": { // {additionalProperties: "@interaction"}
    @interactionId : @interaction // { optional: true }
  },
  "userTypes": { // {additionalProperties: "@userType", optional: true}
    @userTypeName: @userType // {optional: true}
  },
  "userEnums": { // {additionalProperties: "@userRule", optional: true}
    @userRuleName : @userRule // {optional: true}
  }
}

TYPE @interaction
  @httpInteraction | @jsonRpcInteraction

TYPE @interactionId
  @httpInteractionId | @jsonRpcInteractionId

TYPE @httpInteractionId
  "http GET /cats/{id}" // {regex: "^http (?:GET|POST|PUT|PATCH|DELETE) \/.*"}

TYPE @jsonRpcInteractionId
  "json-rpc-2.0 /cats foo" // {regex: "^json-rpc-2.0 \/.* .+"}

#---------------------------------------------- TAG -----------------------------------------------

TYPE @tagName regex
  /@[A-Za-z0-1_]/

TYPE @tag
{
  "name"           : "@cats",
  "title"          : "/cats",
  "annotation"     : "Brief description of the tag",
  "description"    : "Tag description", // {optional: true}
  "interactionGroups" : [
    @tagInteractionGroup,
    @tagInteractionGroup
  ],
  "children" : {  // {additionalProperties: "@tagName", optional: true}
    @tagName : @tag // {optional: true}
  }
}

TYPE @tagInteractionGroup
  @tagHttpInteractionGroup | @tagJsonRpcInteractionGroup

TYPE @tagJsonRpcInteractionGroup
{
  "protocol": "json-rpc-2.0", // {const: true}
  "interactions": [
    @jsonRpcInteractionId,
    @jsonRpcInteractionId
  ]
}

TYPE @tagHttpInteractionGroup
{
  "protocol": "http", // {const: true}
  "interactions": [
    @httpInteractionId,
    @httpInteractionId
  ]
}

#--------------------------------------------- JSON RPC -------------------------------------------
  
TYPE @jsonRpcInteraction
{
  "id"           : "json-rpc-2.0 /cats foo", // {type: "@jsonRpcInteractionId"}
  "protocol"     : "json-rpc-2.0",           // {const: true}
  "path"         : "/cats",                  // {type: "@path"}
  "method"       : "foo",
  "pathVariables": { // {optional: true}
    "schema": @schema
  },
  "tags": [
    @tagName
  ],
  "annotation" : "Method annotation.",  // {optional: true}
  "description": "Method description.", // {optional: true}
#  "query" : @query,  // {optional: true}
  "params": @schema, // {optional: true}
  "result": @schema  // {optional: true} 
}

#----------------------------------------------- HTTP ---------------------------------------------

TYPE @httpMethodName
  "GET" // {enum: ["GET", "POST", "PUT", "PATCH", "DELETE"]}

TYPE @httpInteraction
{
  "id"           : "http GET /cats", // {type: "@httpInteractionId"}
  "protocol"     : "http",           // {const: true}
  "httpMethod"   : "GET",            // {type: "@httpMethodName"}
  "path"         : "/cats",          // {type: "@path"}
  "pathVariables": {                 // {optional: true}
    "schema": @schema
  },
  "tags": [
    "@cats",       // {type: "@tagName"}
    "@pets",       // {type: "@tagName"}
    "@readMethods" // {type: "@tagName"}
  ],
  "annotation" : "Retrieve cats' list.",                   // {optional: true}
  "description": "Allows to retrieve all the cats' list.", // {optional: true}
  // Request
  "query"  : @query,        // {optional: true}
  "request": @httpRequest,  // {optional: true}
  // Answers
  "responses": [ /* {optional: true} 
                  - An array is used because there can be multiple responses with the same code. */
    @httpResponse
  ]
}

#--------------------------------------------- QUERY ---------------------------------------------

TYPE @query
{
  "example": "fields=id,name,size&access_token=qwequhpijdfhhwehuuhsdf", // {optional: true}
  "format" : "htmlFormEncoded", // {type: "@serializeFormat"}
  "schema" : @schema
}

#--------------------------------------------- REQUEST -------------------------------------------

TYPE @httpRequest
{
    "headers": {         // {optional: true}
      "schema": @schema
    },
    "body": {
      "format": "json", // {type: "@serializeFormat"}
      "schema": @schema
    }
}

#--------------------------------------------- RESPONSE -------------------------------------------

TYPE @httpResponseCode
  "200" // {regex: "\\d\\d\\d"}

TYPE @httpResponse
{
  "code"      : @httpResponseCode,
  "annotation": "Description of the successful response.", // {optional: true}
  "headers": {
    "schema": @schema
  },
  "body": {
    "format": "json", // {type: "@serializeFormat"}
    "schema": @schema
  }
}

#---------------------------------------------- PATH ----------------------------------------------

TYPE @path
  "/cats/{id}/friends/{friend:id}"

#---------------------------------------------- USER TYPE -----------------------------------------

TYPE @userTypeName
  "@cat" // {regex: "@[A-Za-z0-9_]+"}


TYPE @userType
{
  "annotation" : "A brief description of the type.",     // {optional: true}
  "description": "A lengthy description of the type.", // {optional: true}
  "schema"     : @schema
#  "links"      : [
#    @link,
#    @link
#  ]
}

#---------------------------------------------- USER RULE -----------------------------------------

TYPE @userRuleName
  "@cat" // {regex: "@[A-Za-z0-9_]+"}

TYPE @userRule
{
  "annotation" : "A brief description of the named rule",
  "description": "Description of the named rule",
  "value"      : @rule
#  "links"      : [
#    @link,
#    @link
#  ]
}

#---------------------------------------------- LINK ----------------------------------------------

#TYPE @link
#{
#  "type": "response.body", // {type: "@linkTypeEnum"}
#  "address": @interactionAddress | @serverAddress
#}

#---------------------------------------------- SERVER --------------------------------------------

TYPE @serverName regex
  /@[A-Za-z0-9_]+/

TYPE @server
{
  "annotation": "Test server", // {optional: true}
  "baseUrl": "https://{env}.catsbook.com/api/{version}/{locale}/"
#  "baseUrlVariables": { // {optional: true}
#    "schema": @schema
#  }
}

#---------------------------------------------- SCHEMA --------------------------------------------

TYPE @schema
{
  "notation": "jsight",                            // {type: "@schemaNotation"}
  "content" : @jsightSchemaElement | @regexSchema, // {optional: true} - May not be specified for the `any` and `empty` notations.
  "usedUserTypes": [ // {optional: true}
    "@cat",          // {type: "@userTypeName"}
    "@dog"           // {type: "@userTypeName"}
  ],
  "usedUserEnums": [ // {optional: true}
    "@catSizeEnum"   // {type: "@userRuleName"}
  ],
  "example": "{\n  \"id\": 123\n}" // {optional: true}
}

TYPE @jsightSchemaElement
{
#   "parentJsonType"  : "array",      // {enum: [null, "object", "array"]}
  "key"              : "cat",        // {optional: true, type: "string"} - Specified only if parent tokenType: "object".
  "isKeyUserTypeRef" : true,         // {optional: true, const: true} - Specified if reference is located in the key.
#   "index"           : 0,            // {optional: true} - Specified only if "parentType": "array".
  "tokenType"        : "object",     // {type: "@tokenTypeEnum"}
  "type"             : "@cat",       /* Calculated or explicitly specified element type (for an element card or a tabular
                                     description of data). */
  "optional"         : true,         // The calculated or explicitly specified value of the optional rule. By default, false.
  "scalarValue"      : "123",        /* {optional: true, type: "string"} - Specified only if the "tokenType" is specified
                                                  "string", "number", "boolean", "annotation", "reference" or "null". */
  "inheritedFrom"    : "@austronaut",/* {type: "@userTypeName", optional: true} - The source of the object property is
                                                            specified if it is inherited through the 'allOf' rule. */
  "note"             : "Note to the \n element of the example.", // {optional: true} - May contain line breaks.
  "rules": [                      // {optional: true}
    @rule
  ],
  "children": [                   // {optional: true} - specified only if tokenType: "array" or "object".
    @jsightSchemaElement
  ]
}

TYPE @rule
{
  "key"        : @ruleNameEnum,
  "tokenType"  : "object", // {type: "@tokenTypeEnum"}
  "scalarValue": "@cat",   /* {optional: true} - Specified only if "tokenType" specifies "string", "number", "boolean",
                                               "annotation" or "null". */
  # "note"       : "Note to the \n rule.", // {optional: true} - May contain line breaks.
  "children"   : [         // {optional: true} - specified only if tokenType: "array" or "object". 
    @rule
  ]
}

TYPE @ruleNameEnum
  "minLength" /* {enum: [
                    "type",
                    "optional",
                    "nullable",
                    "min",
                    "max",
                    "exclusiveMinimum",
                    "exclusiveMaximum",
                    "precision",
                    "minLength",
                    "maxLength",
                    "regexp",
                    "minItems",
                    "maxItems",
                    "or",
                    "additionalProperties",
                    "const",
                    "serializeFormat",
                    "serializedType",
                    "enum",
                    "allOf"
                  ]} */

TYPE @tokenTypeEnum
"object" /* [
            "object", 
            "array", 
            "string", 
            "number", 
            "boolean", 
            "null",
            "annotation", // This means an interline annotation.
            "reference"   // It is used when a reference is inserted into the example, for example,
                             a type name instead of a value
          ]
          */

TYPE @schemaNotation
  "jsight" // {enum: ["jsight", "regex", "any", "empty"]}

TYPE @serializeFormat
  "json" // {enum: ["json", "plainString", "binary", "htmlFormEncoded", "noFormat"]}

TYPE @regexSchema
  "/Hello, World!/" // {regex: "/.*/"}