Page cover

AI Declare SDK

AI-Declare SDK is a Scala toolkit for designing, validating, generating and documenting APIs through a concise, type-safe DSL. Model endpoints, payloads, and policies centrally and produce consistent server/client artifacts. Main features include:

Entity definition

The first thing you need to do is to define your entities, for that you will create Scala case classes that define your tables. All entity classes must derive EntityMetadata type class.

All entities must define their identifier and can define foreign keys using static annotations:

@id

This annotation marks a field as the primary key of a table. This annotation is mandatory in all entities.

Parameters:

  • autogenerated (default false): defines whether the primary key is auto-generated by the database or not

@fk[RefTable]

This annotation creates a foreign key from the field to the referenced case class (RefTable). A compilation error will occur if the type of the foreign key and the @id of the referenced table doesn't match.

package com.aideclare.entities.highschool

import com.aideclare.entities.dsl.syntax.{fk, id}
import com.aideclare.entities.dsl.typeclasses.EntityMetadata

import java.time.LocalDate

case class Professor(@id(autogenerated = true) id: Int,
                     email: String,
                     name: String,
                     surname: String
                  )derives EntityMetadata

// StudentGroup primary key is id (autogenerated)
case class StudentGroup(@id(autogenerated = true) id: Int,
                        name: String,
                        title: String,
                        academicYear: Int,
                        @fk[Professor] professorId: Int
                       )derives EntityMetadata

// Student primary key is studentId (not autogenerated), it has a foreign key from 
// Student.groupId to StudentGroup.id
case class Student(@id studentId: Int,
                   name: String,
                   surname: String,
                   birthDate: LocalDate,
                   @fk[StudentGroup] groupId: Int
                  )derives EntityMetadata

User definitions

Some of the entities of a system should also represent users of it. Entities that are also users must also derive UserInfo type class.

All user entities must define their identifier, a username field, a password field and can define foreign keys using static annotations:

@username

It marks a field as username field. The field must be a String.

@password

It marks a field as password field.

App definition class

Your app definition is going to be defined in a class that has to define the following type parameters and implicits:

  • System type parameter

  • API[_] higher kinded type

  • SystemDsl[System, Api] implicit: loads the API system DSL syntax

  • ApiDsl[Api] implicit: loads the API DSL syntax

System

Once the app class is configured you can create a public function that defines the REST system.

After defining the system you can start adding APIs. For each API we will define:

  • The entity that manages the API

  • The endpoints that are available (list, get, create, update and delete)

  • The access type:

    • Public: Public APIs can be used by anyone, even unauthenticated users

    • Authenticated: Only authenticated users with certain role will be authorized to call the endpoints.

    • Me: API that allows an authenticated user to manage its own user data.

  • Sub-APIs: An API can define sub-APIs that inherit the parent API’s access-type configuration.

API customization

When you create a public, authenticated or me API it is created with all available endpoints by default and it doesn't define sub-APIs. If you want to modify the available endpoints or create sub-APIs, you need to use api() function and its parameters and methods.

Define endpoints

When you define an API it will create all available endpoints by default. The available endpoints are GetAll, GetById, Create, Update and Delete. If you want that a certain user can only access to certain endpoints you must define the List of endpoints and pass it to API method

As it is quite common to define a read-only API there is a constant that stores GetAll and GetById endpoints in a List

Define sub-APIs

Many times, specially for authenticated and me APIs, it is necessary to add sub-APIs to your API. The goal of sub-APIs is to allow authenticated users to access to rows of other entities that are related to them. For example, a professor can manage its own student groups but not those that belong to another professor.

Let's put it all together

PreviousQuickstartNextGenerators

Last updated