name	route
Defining your schema	/schema

Defining your schema

To generate client targets and server schema, sdkgen provides an expressive language, in which you declare your interfaces, API calls and error treatment, all of this, with automatic type validation. You can also add annotations to generate documentation and REST endpoints to your exposed functions!

Primitive types

In addition to having string, int, float and bool (which are exactly what you expect), it also has:

uint - an unsigned integer
uuid - a universally unique identifier
void - the absence of any value
date - a simple type referencing a date in calendar, timezone-agnostic
datetime - full date type, with time included, always converted to UTC
bytes - a byte buffer, commonly used when uploading files
money - an integer for representing money in cents
bigint - a way to represent integers bigger than 2^53
email - an email address valid value
hex - an hexadecimal number
base64 - encoding format for transferring data via text
url - URL
xml - XML
json - JSON

Brazilian utility types:

cpf - personal document number
cnpj - company document number

Compound types

To compose types into more complex ones, sdkgen provides a TypesScript-like syntax:

type UserInfo {
  firstName: string
  lastName: string
  additionalNeeds: string
  socialName: string
  cpf: cpf
  email: string
  phoneNumber: string
}

Spreading compound types

Complex types can also be spread and used by other types:

type User {
    id: uuid
    ...UserInfo
}

In this case, User is transformed into:

type User {
    id: uuid
    firstName: string
    lastName: string
    additionalNeeds: string
    socialName: string
    cpf: cpf
    email: string
    phoneNumber: string
}

Enums

In sdkgen, enums are types that consist in a fixed set of strings, behaving very similarly to the other languages and being defined this way:

type State enum {
    Bahia
    RioDeJaneiro
    SaoPaulo
}

You can also define enums inline on compound types:

type User {
    username: string
    password: string
    type: enum { Teacher Student Director }
}

When receiving or sending enum-typed strings, the sdkgen server will validate if the value matches the provided set.

Lists

To define a list of any type, you can just put [] at the of its definition. In this case, foo is a list of strings:

type Game {
    winner: string
    players: string[]
}

Your compound type can also be a list:

type Car {
    brand: string
    model: string
    owners: string[]
}[]

Optional types

To turn your types optional, add ? after its definition. sdkgen won't complain if an optional type is not present in any context.

type BlogPost {
    title: string
    description: string?
    text: string
}

Any sdkgen type can be set as optional:

type Comment {
    owner: User
    text: string
    reactions: Reaction[]?
}

type Direction enum {
    Up
    Down
    Left
    Right
}

type Car {
    brand: string
    direction: Direction?
}

Functions

To define what your clients will get and put into the server, you should describe the functions, their arguments and return types:

fn createUser(info: UserInfo): User
fn updateUser(info: UserInfo): User

fn removeUser(id: string)

fn getUserHistory(id: string, since: date, until: date): History[]

Errors

By default, sdkgen provides the Fatal error type, but, you can create your own to make a more specific error throwing to the clients, as you can see:

error InvalidArgument
error NotFound

Annotations

@rest

It is possible to add a @rest annotation to any sdkgen function to have it exposed as a REST endpoint. Arguments can be received as path fragments, as query parameters, as headers and on the body. Parsing and strict type validation is all done for you:

// Simple get call
@rest GET /status
fn getStatus(): string

// Passing argument on body
@rest POST /users [body {user}]
fn createNewUser(user: NewUser): User

// Sending custom headers
@rest GET /posts [header user-agent: {userAgent}] [header accept-language: {lang}] [header x-token: {token}]
fn getPosts(userAgent: string, lang: string, token: base64): User

// Sending arguments on path and querystring.
@rest GET /chats/{chatId}/messages?{since}&{until} [header x-token: {token}]
fn getMessages(token: base64, chatId: uuid, since: datetime?, until: datetime?): Message[]

// Provide the @description to be displayed in the swagger
@description Get the list of company users
fn getUsers(companyId: uuid, since: datetime?, until: datetime?, token: base64): User?

// Provide the @args to be displayed a text for argument in the swagger
@arg companyId ID from company
fn getUsers(companyId: uuid, since: datetime?, until: datetime?, token: base64): User?

// You can use both at the same time
@description Get the list of company users
@arg companyId ID from company
@arg since provide a date for the start of the search
@arg until provide a date for the end of the search
@arg token provide a token in base64
fn getUsers(companyId: uuid, since: datetime?, until: datetime?, token: base64): User?

// Sending enum like as an argument
type TypeTransfer enum {
    internal
    external
}

@rest GET /transfer/account?{type}&{account}
fn getTransfersTypeFromAccount(type: TypeTransfer, account: string)