Quickstart

What is AI Declare?

AI Declare is an AI agent for REST API code generation. The way you configure the agent is by using a DSL (Domain Specific Language). The DSL is embedded in the Scala programming language, and it allows to the programmers to create complex secured REST APIs in just a few minutes in different languages / frameworks.

Prerrequisites

• Basic programming skills are a prerequisite..

• IntelliJ IDEA (Community or Ultimate) + Scala plugin

  • Install IntelliJ IDEA.

  • In Settings → Plugins, search Scala and install it.

  • (Recommended) JDK 21+, Scala 3.3+, sbt 1.10+.

• ChatGPT API token (OpenAI API key)

  • Create/get your API key from your OpenAI Platform account.

  • Top up some credit here

• Register as a user here

Your first AI Declare project

1) Setup environment

Register as a user here

Setup your AI Declare credentials

Linux

USERNAME=your_aideclare_username
PASSWORD=your_aideclare_password
install -m700 -d "$HOME/.aideclare" && printf 'username=%s\npassword=%s\n' "$USERNAME" "$PASSWORD" | install -m600 /dev/stdin "$HOME/.aideclare/credentials"

Windows

2) Setup a Scala project

1. Open IntelliJ IDEA

2. New Project → Scala → sbt.

3. Choose your JDK, set Scala 3.x (any recent 3.x).

4. Name the project (e.g., aideclare-sample) → Create.

This generates:

• build.sbt

• project/build.properties

• project/ directory for sbt metadata

1. Add the following code to build.sbt

   
   libraryDependencies ++= Seq(
     // AI Declare SDK
     "com.ai-declare" %% "sdk" % "0.1.1-BETA"
   )

2. Sync the project

3) Implementation

Data model definition

First, define your data model. Create one Scala case class for each table in your database. Mark primary keys with @id and foreign keys with @fk, and have every case class derives EntityMetadata.

If a case class represents an application user, also derive UserInfo. In that case, annotate the username and password fields with @username and @password, respectively.

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

import java.time.LocalDate

case class Student(
                   @id studentId: Int,
                   email: String,
                   name: String,
                   surname: String,
                   birthDate: LocalDate,
                   @fk[StudentGroup] groupId: Int
                  )derives EntityMetadata
                  
case class Professor(
                   @id(autogenerated = true) id: Int,
                   @username email: String,
                   name: String,
                   @password password: String,
                   surname: String
                  )derives EntityMetadata, UserInfo
                 
case class StudentGroup(
                   @id id: Int,
                   name: String,
                   title: String,
                   academicYear: Int,
                   @fk[Professor] professorId: Int
                   )derives EntityMetadata

case class Admin(
                  @id @username username: String,
                  @password password: String,
                  email: String
                )derives EntityMetadata, UserInfo

APIs definition

Next, define your REST APIs. You can expose four kinds of endpoints:

• Public: open to everyone; no authentication required.

• Authenticated: access restricted to specific user types/roles.

• Me: operate on the authenticated user’s own data.

• Sub-APIs: endpoints nested under another API; they inherit the parent’s access controls.

import com.aideclare.entities.dsl.adt.Endpoint
import com.aideclare.entities.dsl.syntax.*

class HighschoolApp[System, Api[_]](using systemDsl: SystemDsl[System, Api], apiDsl: ApiDsl[Api]):

  import apiDsl.*
  import com.aideclare.entities.dsl.syntax.*
  import systemDsl.*

  def highschoolSystem: System =
    // Rest system name declaration
    system("highschool")
      // /api/studentgroup public API. endpoints: GET /api/studentgroup, GET /api/studentgroup/{id}
      .public[StudentGroup](api(Endpoint.ReadResourceEndpoints))
      // /api/professor public API. endpoints: GET /api/professor, GET /api/professor/{id}
      .public[Professor](
        api[Professor](Endpoint.ReadResourceEndpoints)
          // /api/professor/{professorId}/studentgroup public API. endpoints: GET /api/professor/{professorId}/studentgroup,
          // GET /api/professor/{professorId}/studentgroup/{groupId}
          ./[StudentGroup](
            // /api/professor/{professorId}/studentgroup/{groupId}/student public API.
            // endpoints: GET /api/professor/{professorId}/studentgroup/{groupId}/student,
            // GET /api/professor/{professorId}/studentgroup/{groupId}/{groupId}/student/{studentId}
            api[StudentGroup](Endpoint.ReadResourceEndpoints)./[Student](api(Endpoint.ReadResourceEndpoints))
          )
      )
      // /api/student public API. endpoints: GET /api/student, GET /api/student/{id}
      .public[Student](api(Endpoint.ReadResourceEndpoints))
      // The following 4 APIs will allow Admin users to manage Professor, Student, StudentGroup and Admin entities
      // /api/professor public API. endpoints: GET /api/professor, GET /api/professor/{id}, POST /api/professor,
      // PUT /api/professor/{id}, DELETE PUT /api/professor/{id}
      .authenticated[Professor, Admin]
      // /api/student public API. endpoints: GET /api/student, GET /api/student/{id}, POST /api/student,
      // PUT /api/student/{id}, DELETE PUT /api/student/{id}
      .authenticated[Student, Admin]
      // /api/studentgroup public API. endpoints: GET /api/studentgroup, GET /api/studentgroup/{id}, POST /api/studentgroup,
      // PUT /api/studentgroup/{id}, DELETE PUT /api/studentgroup/{id}
      .authenticated[StudentGroup, Admin]
      // /api/admin public API. endpoints: GET /api/admin, GET /api/admin/{id}, POST /api/admin,
      // PUT /api/admin/{id}, DELETE PUT /api/admin/{id}
      .authenticated[Admin, Admin]
      // Declares an API that belongs to Professor users and allow to see modify their data
      // /api/me/professor, endpoints GET and PUT
      .me[Professor](
        api[Professor]
          // Endpoints to manage authenticated professor student groups
          // /api/me/professor/studentgroup, all endpoints are available (create, update, delete, list)
          ./[StudentGroup](
            // Endpoints to manage students that belong to an authenticated professor student group
            // /api/me/professor/studentgroup/{groupId}/student, all endpoints are available (create, update, delete, list)
            api[StudentGroup]./[Student]
          )
      )

4) Create a project in AI Declare site

On the AI-Declare site, create a new project, then select the target language and framework for code generation.

5) Run an execution

Create a main class like the following

import com.aideclare.entities.dsl.adt.RestSystem
import com.aideclare.entities.dsl.syntax.ApiDsl

object HighschoolAppGenerator extends App :

  val sender = ExecutionSender()
  sender.send(
    new HighschoolApp[RestSystem, ApiDsl.Resources].highschoolSystem
  )

When you run the code you will be asked to choose a project:

Available projects:
1. Test Java
2. Test nodeojects
3. My project
3

6) Download the code from Executions screen

That's it, the code will be generated in a few minutes and you will be able to download it from the web site.

Click in the file icon to download generated sources.