API specification

Overview

api is the domain characteristic language of go-zero (below is api language or api description), which is intended to humanize as the most basic description language for generating HTTP services.

The api field feature language contains syntax versions, info blocks, structural statements, service descriptions, etc., where the structure is almost the same as the Golang structural syntax, but only the structure keywords.

Targets

  • Learning sex
  • Readability
  • Expansion Freedom
  • HTTP Service 1 click to generate
  • Write an api file to generate multilingual code services

Syntax Token

api syntax is described using to extend the Bakos style(EBNF) and specified in the extended Bakos style.

  1. Syntax      = { Production } .
  2. Production  = production_name "=" [ Expression ] "." .
  3. Expression  = Term { "|" Term } .
  4. Term        = Factor { Factor } .
  5. Factor      = production_name | token [ "…" token ] | Group | Option | Repetition .
  6. Group       = "(" Expression ")" .
  7. Option      = "[" Expression "]" .
  8. Repetition  = "{" Expression "}" .

Production is composed of Term and the following operators, with the following operators’ priority increasing：

  1. |   alternation
  2. ()  grouping
  3. []  option (0 or 1 times)
  4. {}  repetition (0 to n times)

Form a...b indicates a set of characters from a to b as an alternative, eg. 0...9 represents a valid number from 0 to 9.

`` for ENBF end symbols.

::note
Generate names if lowercase, then end token,camel peak production names are non-terminator token, e.g.：

  1. // 终结 token
  2. number = "0"..."9" .
  3. lower_letter = "a"..."z" .
  5. // 非终结 token
  6. DataType = TypeLit | TypeGroup .
  7. TypeLit  = TypeAlias | TypeStruct .

:::

Source representation

Source code representation is the most basic element used to describe api syntax.

Characters

  1. newline = /* indicates line replacement, Unicode value is U+000A */ .
  2. unicode_char = /* Unicode characters other than newline newline.*/
  3. unicode_letter = /* letter a.z|A..Z Unicode */
  4. unicode_digit = /* value 0...9 Unicode */

Letters and Numbers

Underline character _ (U+005F) is considered to be lowercase.

  1. letter        = "A"..."Z" | "a"..."z" | "_" .
  2. decimal_digit = "0" … "9" .

Abstract syntax tree

Abstract tree (Abstract Syntax Tree, AST), or syntax tree (Syntax tree), is an abstract expression of source syntax structure.It presents the syntax structure of the programming language in a tree and each node on the tree denotes a structure in the source code.The expression is “abstract” because the syntax does not indicate every detail that appears in the true syntax.For example, nested brackets are implicit in the tree structure and are not presented in the form of nodes; and a condition like if-condition-then can be represented by nodes with three branches.

The abstract syntax tree is the tree of the code.They are an essential component of the compiler’s modus operandi.When the compiler converts some code, there are basically the following steps：

  • Lexical Analysis
  • Syntax Analysis
  • Code Generation

AST process

AST Analytics Process

Lexical Analysis

Lexical Analysis is a process in computer science to convert character sequences to token (token) sequences.The procedure or function for the analysis of the word is called the word analyst (lexical analyzer, abbreviation), also known as scanner.The semiconductor is generally in the form of a function, for syntax analyst calls.

In api language, word analysis is a process of converting characters to a dictionary of synonyms, including comments and Token.

Word Element

Note

2 formats in api field feature language：

  1. One line notes start with // and end of line.

    1. // This is an example of a single line comment

  2. Multi-line comment (document note) starts with /* and ends with first */.

    1. /*This is the document annotation */
    2. /*
    3. in multiple lines of document annotation
    4. */
Token

Token is the most basic element of the constituent node consisting of identifier (identifier),keyword (keyword),operator (operator),punctuation),word volume (literal),Whitespace (White space)Generically byspaces (U+0020),Horizontal tabs (U+0009),Car returns (U+000D)and newlines (U+000A)In api language, Token does not contain operator(operator).

The Golang Structure of Token is defined as：

  1. type Token struct {
  2.     Type     Type
  3.     Text     string
  4.     Position Position
  5. }
  7. type Position struct {
  8.     Filename string
  9.     Line     int
  10.     Column   int
  11. }

Example api statement syntax="v1" its word is：

TextDataType
syntaxIdentifiers
=Operator
“v1”String
ID

ID 标识符一般是结构体，变量，类型等的名称实体，ID 标识符一般有 1 到 n 个字母和数字组成，且开头必须为字母（记住上文提到的 _ 也被当做小写字母看待），其 EBNF 表示法为：

  1. identifier = letter { letter | unicode_digit } .

ID Identifier Example：

  1. a
  2. _a1
  3. GoZero

The ID identifier is pre-defined,api follows Golang Predefined ID identifier.

  1. Predefined type:
  2.     any bool byte comparable
  3.     complex64 complex128 error float32 float64
  4.     int int8 int16 int32 int64 rune string
  5.     uint uint8 uint16 uint32 uint64 uintptr
  7. predefined constants:
  8.     true false iota
  10. zero:
  11.     nil
  13. predefined functions:
  14.     append cap close complex copy delete imag len
  15.     make new panic print println real recover
Keywords

The keywords are some special ID identifiers, are system reserved, api keywords follow Golang keyword, and Golang keywords cannot be used as identifiers in the structure.

Golang Keywords

  1. break        default      func         interface    select
  2. case         defer        go           map          struct
  3. chan         else         goto         package      switch
  4. const        fallthrough  if           range        type
  5. continue     for          import       return       var
Punctuation Marks

Punctuation can be used to split token, expressions, groups, and below is punctuation in api language：

  1. -    ,    (    )
  2. *    .    [    ]
  3. /    ;    {    }
  4. =    :    ,    ;
  5. ...
String

String font volume is a constant of a sequence of characters.Golang strings are used in api, with 2 forms： original string (raw string) and normal string (double quote).

The string sequence of the original string is between two dequotation marks, except for a counterquotation number, any character can appear, such as `foo`；

The string sequence of a normal string is between two quotes except two quotes and any characters can appear, like “foo”.

API specification - 图2note

In api language, the double quotation string does not support \" to implement string.

  1. string_lit             = raw_string_lit | interpreted_string_lit .
  2. raw_string_lit         = "`" { unicode_char | newline } "`" .
  3. interpreted_string_lit = `"` { unicode_value | byte_value } `"` .

String Example：

  1. // Original string
  2. ``
  3. `foo`
  4. `bar`
  5. `json:"baz"`
  7. // normal string
  8. ""
  9. "foo"
  10. "bar"

Syntax analysis

Syntax Analysis is also called syntax resolution, which is the process of converting the synonym element into a tree, whereas the syntax tree generally consists of nodes (Node), expression (Expression) and statement (Statement) which, in addition to the translation of terms into trees, require the completion of a semantic analysis.

Node

Node is a variation of token, an interface type, a basic element of an expression and statement, defined as： in a structure in Golang

  1. // Node represents a node in the AST.
  2. type Node interface {
  3.     // Pos returns the position of the first character belonging to the node.
  4.     Pos() token.Position
  5.     // End returns the position of the first character immediately after the node.
  6.     End() token.Position
  7.     // Format returns the node's text after format.
  8.     Format(...string) string
  9.     // HasHeadCommentGroup returns true if the node has head comment group.
  10.     HasHeadCommentGroup() bool
  11.     // HasLeadingCommentGroup returns true if the node has leading comment group.
  12.     HasLeadingCommentGroup() bool
  13.     // CommentGroup returns the node's head comment group and leading comment group.
  14.     CommentGroup() (head, leading CommentGroup)
  15. }

Expression

Expression are the basic element of the constituent statement. They can be understood as “phrases” in a sentence and the expression contained in api language as follows:：

  1. Data Type Expression
  2. Field expression in structure
  3. key-value expression
  4. Service Declaration Expression
  5. HTTP Request/Response Body Expression
  6. HTTP Router Expression

The structure of Golang in api is defined as：

  1. // Expr represents an expression in the AST.
  2. type Expr interface {
  3.     Node
  4.     exprNode()
  5. }

Statement

Statement is the basic element of the abstract syntax tree, which can be understood as an article, and statement is a number of sentences that make up the article, and the api language contains statements as follows:

  1. @doc statement
  2. @handler statement
  3. @server statement
  4. Request / Response Body Statement for HTTP Service
  5. Comment statement
  6. Import statement
  7. info statement
  8. HTTP Router Expression
  9. HTTP service declaration statement
  10. Syntax statement
  11. Structure statement

The structure of Golang in api is defined as：

  1. // Stmt represents a statement in the AST.
  2. type Stmt interface {
  3.     Node
  4.     stmtNode()
  5. }

Code Generation

Once we have an abstract syntax tree, we can use it to print or generate different codes, which can be supported by api abstract syntax when it is done：

  1. Print AST
  2. api file format
  3. Golang HTTP Service Generation
  4. TypeScript Code Generation
  5. Dart code generation
  6. Kotlin Code Generation

In addition to this, extensions can be made based on AST such as plugin：

  1. goctl-go-compact
  2. goctl-swagger
  3. goctl-php

api syntax marker

  1. api = SyntaxStmt | InfoStmt | { ImportStmt } | { TypeStmt } | { ServiceStmt } .

Syntax statement

Syntax statements are used to mark the api language version, different versions may have different syntax structures and are optimized as versions are upgraded, the current version is v1.

EBNF syntax expressed as：

  1. SyntaxStmt = "syntax" "=" "v1" .

syntax example：

  1. syntax = "v1"

info statement

info is meta information in api language that is only used to describe the current api file,Advertisementdoes not participate in code generation, it differs from annotation but notes generally exist with a syntax that is used to describe the entire api message, of course, does not exclude future participation in code generation: EBNF for info is：

  1. InfoStmt         = "info" "(" { InfoKeyValueExpr } ")" .
  2. InfoKeyValueExpr = InfoKeyLit [ interpreted_string_lit ] .
  3. InfoKeyLit       = identifier ":" .

info writing sample：

  1. // Block of info without key-value
  2. info ()
  4. // blocks containing key-value
  5. info (
  6.     foo: "bar"
  7.     bar:
  8. )

Import statement

import statements are syntax blocks to introduce other api files in api, which support relative/absolute path,does not support package design whose EBNF is：

  1. ImportStmt        = ImportLiteralStmt | ImportGroupStmt .
  2. ImportLiteralStmt = "import" interpreted_string_lit .
  3. ImportGroupStmt   = "import" "(" { interpreted_string_lit } ")" .

import statement writing sample：

  1. // Single line import
  2. import "foo"
  3. import "/path/to/file"
  5. // import group
  6. import ()
  7. import (
  8.     "bar"
  9.     "relative/to/file"
  10. )

Data Type

api 中的数据类型基本沿用了 Golang 的数据类型，用于对 rest 服务的请求/响应体结构的描述，其 EBNF 表示为：

  1. TypeStmt          = TypeLiteralStmt | TypeGroupStmt .
  2. TypeLiteralStmt   = "type" TypeExpr .
  3. TypeGroupStmt     = "type" "(" { TypeExpr } ")" .
  4. TypeExpr          = identifier [ "=" ] DataType .
  5. DataType          = AnyDataType | ArrayDataType | BaseDataType |
  6.                     InterfaceDataType | MapDataType | PointerDataType |
  7.                     SliceDataType | StructDataType .
  8. AnyDataType       = "any" .
  9. ArrayDataType     = "[" { decimal_digit } "]" DataType .
  10. BaseDataType      = "bool"    | "uint8"     | "uint16"     | "uint32" | "uint64"  |
  11.                     "int8"    | "int16"     | "int32"      | "int64"  | "float32" |
  12.                     "float64" | "complex64" | "complex128" | "string" | "int"     |
  13.                     "uint"    | "uintptr"   | "byte"       | "rune"   | "any"     | .
  15. InterfaceDataType = "interface{}" .
  16. MapDataType       = "map" "[" DataType "]" DataType .
  17. PointerDataType   = "*" DataType .
  18. SliceDataType     = "[" "]" DataType .
  19. StructDataType    = "{" { ElemExpr } "}" .
  20. ElemExpr          = [ ElemNameExpr ]  DataType [ Tag ].
  21. ElemNameExpr      = identifier { "," identifier } .
  22. Tag               = raw_string_lit .

Sample data type writing：

  1. // Alias [1]
  2. type Int int
  3. type Integer = int
  5. // Empty structure
  6. type Foo {}
  8. // Structrue literal
  9. type Bar {
  10.     Foo int               `json:"foo"`
  11.     Bar bool              `json:"bar"`
  12.     Baz []string          `json:"baz"`
  13.     Qux map[string]string `json:"qux"`
  14. }
  16. type Baz {
  17.     Bar    `json:"baz"`
  18.     // inline [2]
  19.     Qux {
  20.         Foo string `json:"foo"`
  21.         Bar bool   `json:"bar"`
  22.     } `json:"baz"`
  23. }
  25. // Empty type group
  26. type ()
  28. // Type Group
  29. type (
  30.     Int int
  31.     Integer = int
  32.     Bar {
  33.         Foo int               `json:"foo"`
  34.         Bar bool              `json:"bar"`
  35.         Baz []string          `json:"baz"`
  36.         Qux map[string]string `json:"qux"`
  37.     }
  38. )
API specification - 图3takes note of

[1] While aliases are supported in syntax, alias are intercepted during semicolon analysis, or will be liberalized in the future.

[2] While syntax supports inline structures, alias are intercepted when semicolon analyses, this will or will be liberalized in the future.

In addition：

  1. The current api syntax supports an array but blocks an array during semiconductor analysis and is currently proposed to replace it with a slice or be released in the future.
  2. Package design is not supported, e.g. time.Time.

Service statement

The service statement is a visual description of the HTTP service, which contains definitions of requests to handler, request method, request routing, requester, response,jwt switch, intermediate declaration etc.

Its EBNF expression is：

  1. ServiceStmt     = [ AtServerStmt ] "service" ServiceNameExpr "("
  2.                   { ServiceItemStmt } ")" .
  3. ServiceNameExpr = identifier [ "-api" ] .

@server statement

@server is a meta description of a service statement that contains but is not limited to：

  • jwt switch
  • Middleware
  • Route Group
  • Route Prefix

EBNF for @server expressed as：

  1. AtServerStmt     = "@server" "(" {  AtServerKVExpr } ")" .
  2. AtServerKVExpr   = AtServerKeyLit [ AtServerValueLit ] .
  3. AtServerKeyLit   = identifier ":" .
  4. AtServerValueLit = PathLit | identifier { "," identifier } .
  5. PathLit          = `"` { "/" { identifier | "-" identifier} } `"` .

@server write sample：

  1. // Empty content
  2. @server()
  4. // has content
  5. @server (
  6.     // jwt declaration
  7.     // if key is fixed as 'jwt:', On behalf of the jwt credit declaration
  8.     // value for the configuration file structure name
  9.     jwt: Auth
  11.     // Route prefix
  12.     // If the key is fixed to 'prefix:'
  13.     // for routing prefix statement, alue is a specific routing prefix value, The string does not let it start with /
  14.     prefix: /v1
  16.     // routing group
  17.     // if key is fixed to 'group:', Group statements on behalf of routing groups
  18.     // value for specific groupings, Goctl Generates code by grouping folders according to this value
  19.     group: Foo
  21.     // Middle
  22.     // If key is fixed to middle leware:", For intermediate declaration
  23.     //value for specific intermediate function name, Goctl Generates the intermediate function based on this value
  24.     middleware: AuthorInterceptor
  26.     // Timeout control
  27.     // If key is fixed to timeout:", Represents timeout configurations for
  28.     // value for specific duration, and when goctl is generated the timeout for this value
  29.     timeout: 3s
  31.     // other key-value, In addition to these built-in keys, other key-values
  32.     // can also be passed to goctl and its plugins as an annotation message, but for
  33.     // currently, goctl is not used.
  34.     foo: bar
  35. )

ServiceItemStmt

ServiceItemStmt is a description of a HTTP request, including @doc statement, handler statement, routing information, its EBNF expression is：

  1. ServiceItemStmt = [ AtDocStmt ] AtHandlerStmt RouteStmt .
@doc statement

The @doc statement is a meta information description for a single route, generally key-value and can be passed to goctl and its plugins for extension generation, EBNF representation is：

  1. AtDocStmt        = AtDocLiteralStmt | AtDocGroupStmt .
  2. AtDocLiteralStmt = "@doc" interpreted_string_lit .
  3. AtDocGroupStmt   = "@doc" "(" { AtDocKVExpr } ")" .
  4. AtDocKVExpr      = AtServerKeyLit  interpreted_string_lit .
  5. AtServerKeyLit   = identifier ":" .

@doc Example writing：

  1. // doc doc
  2. @doc "foo"
  4. // empty @doc group
  5. @doc ()
  7. // @doc group with content
  8. @doc (
  9.     foo: "bar"
  10.     bar: "baz"
  11. )
@handler statement

@handler is handler information control over a single route, mainly used to generate golang http.HandleFunc, its EBNF expressed as：

  1. AtHandlerStmt = "@handler" identifier .

@handler writing sample：

  1. @handler foo
Routing statement

Routing statements are a specific description of this single HTTP request, including request method, request path, request, response body, EBNF representation as：

  1. RouteStmt = Method PathExpr [ BodyStmt ] [ "returns" ] [ BodyStmt ].
  2. Method    = "get"     | "head"    | "post" | "put" | "patch" | "delete" |
  3.             "connect" | "options" | "trace" .
  4. PathExpr  = "/" identifier { ( "-" identifier ) | ( ":" identifier) } .
  5. BodyStmt  = "(" identifier ")" .

Router statement writing sample：

  1. // There is no request and response policy
  2. get /ping
  4. // / only the requesting body
  5. get /foo (foo)
  7. // Only the responding body
  8. post /foo returns (foo)
  10. // The request and response body
  11. post /foo (foo) returns (bar)

Sample service writing

  1. // with syntax @server
  2. @server (
  3.     prefix: /v1
  4.     group: Login
  5. )
  6. service user {
  7.     @doc "login example"
  8.     @handler login
  9.     post /user/login (LoginReq) returns (LoginResp)
  11.     @handler getUserInfo
  12.     get /user/info/:id (GetUserInfoReq) returns (GetUserInfoResp)
  13. }
  14. @server (
  15.     prefix: /v1
  16.     middleware: AuthInterceptor
  17. )
  18. service user {
  19.     @doc "login example"
  20.     @handler login
  21.     post /user/login (LoginReq) returns (LoginResp)
  23.     @handler getUserInfo
  24.     get /user/info/:id (GetUserInfoReq) returns (GetUserInfoResp)
  25. }
  28. // without syntax @server
  29. service user {
  30.     @doc "login example"
  31.     @handler login
  32.     post /user/login (LoginReq) returns (LoginResp)
  34.     @handler getUserInfo
  35.     get /user/info/:id (GetUserInfoReq) returns (GetUserInfoResp)
  36. }
API specification - 图4Tips

The full api syntax example can be referenced Full Example of API Definitions

References

Wikipedia AST What are they and how to use them