Design and API Definition

In any software engineering project, the work starts at the design board. In this section, we shall we shall dive deeper into the creation of JSON blueprints based on the design-phase documents and explore all the configuration options provided to us by the platform.

Sample Use Case

As an exercise in creating JSON blueprints, we shall be building an application which tracks the movement of students in and out of the college campus. Each student will be associated with a specific batch and will have attributes such as their name, email, and current status (e.g., on campus, off campus, on leave). The application will allow for the tracking and updating of these statuses in real-time.

To manage and monitor these movements, the application will include an admin interface where authorized personnel can log in using their email ID and a secure password. These admins will have the ability to create and update entries for student movements, ensuring that the status of each student is accurately reflected in the system.

In addition to tracking individual student movements, the application will also generate and display statistical data for each batch. This data will include the number of students currently on campus, the number of students who are off campus, and those on leave. These statistics will provide a clear overview of student distribution and aid in administrative decision-making.

This application will be crucial for maintaining accurate records of student movements and ensuring smooth campus operations.

Design Document - UML Class Diagram

We can perform a requirements parsing of the above English-language description of the application and arrive at the following UML Class Diagram :

UML

For the time being, the class diagram should be all we need when creating the blueprints.

Structure of the JSON object

We need to create separate JSON files for each class that we want to add in our application. The basic structure of the blueprint is as follows :

{
	"{resource}" : {
		"purpose" : "...",
		"cluster" : "...",
		"api" : "...",
		"ui" : "...",
		"display_name" : "...",
		"fields" : [
			{...},
			{...}
		]
	}
}

Let us go over the semantics of each of these fields

{resource} : Here we are expected to specify the name of the resource or the class we are creating. For instance, the blueprint for the Student class shall look like :

{
	"student" : {
		...
	}
}

purpose : As the name suggests, the value of this field specifies the purpose of the JSON file. It can be set to one of three possible values :
1. RESOURCE : This is the default value for the field. It means the JSON blueprint defines a resource to be store in the database.
2. POSSIBLE_VALUE : The blueprint defines Enums and possible values.
3. CUSTOM_DATATYPE : The blueprint defines a composite type for which resources will not be generated.
cluster : This is used to specify where this resource will be stored. Here will be specify the cluster name.
api : This is used to specify whether the code for API end-points needs to be generated. This field expects a boolean value : true or false.
ui : This is used to specify whether front-end JSON specifications should be generated based on which the UI can be built by a front-end engine. This field expects a boolean value.
display_name : A descriptive name for the resource
fields : Here, we shall list and describe the various attributes of the resource.

Attributes and Data types

Let's begin by defining the data attributes for various fields. Each attribute will have specific parameters related to API generation. The parameters for each attribute are as follows:

"fields": {
	  "attribute1": {
		"index": true,
		"name": "attribute1",
		"length": 16,
		"required": true,
		"type": "String"
	  },
	  "attribute2": {
		...
	  },
	  ...
}

Here,

name : The name of the field
type : The data type of the field. The possible values include long, Long, double, Double, boolean, Boolean, char, byte, float, int, Int, timestamp, String, Array and Map. The user can also specify a customized data type. In this case, the user has to provide the Java qualified name of the class representing the data type.
min_length, max_length and length : These specify the minimum, maximum and exact expected lengths for String type data fields.
required : This is to specify whether this field is required or not. The corresponding check is applied both in the UI and in the back-end.
index : This is to specify whether the database needs to create an index for this field
transient_field : A boolean value is expected. If it is set to true, the platform will not store the value of this field in the database.

The first draft

Based on the above information, let us try to create the Student, Batch and StudentMovement classes. We shall be leaving out some derived fields and specifications related to the UI as we shall be covering them later. For the same reason, we leave out the creation of the EntryType enum.

Let us specify student.json :

{
  "student": {
    "cluster": "DB_PROFILE",
    "ui": true,
    "api": true,
    "display_name": "Student Details",
    "fields": {
      "id": {
        "index": true, "name": "id", "length": 16, "required": true, "type": "String"
      },
      "student_batch_id": {
        "name": "student_batch_id", "length": 128, "type": "String"
      },
      "student_email_id": {
        "name": "student_email_id", "length": 128, "type": "String",
      },
      "student_name": {
        "name": "student_name", "length": 128, "type": "String",
      },
      "student_status": {
        "name": "student_status", "length": 1, "type": "String",
      },
      "student_in_status": {
        "name": "student_inout_status", "type": "boolean",
      },
      "student_inHome": {
	    "name": "student_inHome", "type": "boolean",
      }
    }
  }
}

Similarly, we can create the blueprint batch.json :

{
  "batch": {
    "cluster": "DB_PROFILE",
    "ui": true,
    "api": true,
    "display_name": "",
    "fields": {
      "id": {
        "index": true, "name": "id", "length": 16, "required": true, "type": "String"
      },
      "name": {
        "name": "name", "length": 128, "type": "String", "required" : true
      },
      "total_students" : {
	    "type" : "long", "transient_field" : true 
      },
      "in_students" : {
	    "type" : "long", "transient_field" : true 
      },
      "out_students" : {
	    "type" : "long", "transient_field" : true 
      },
      "in_home" : {
	    "type" : "long", "transient_field" : true 
      },
      "is_Active" : {
	    "type" : "String", length : 1
      }
    }
  }
}

Transient Fields

Note that some fields like in_students in the batch blueprint are set as transient. This is because we won't be storing their values in the DB. The values will be dynamically calculated when a query is fired requesting the same.

student_movement.json is not that different from student.json and its creation is left as an exercise to the reader. Note that the entryType field shall be handled later.

Design and API Definition

Sample Use Case​

Design Document - UML Class Diagram​

Structure of the JSON object​

Attributes and Data types​

The first draft​

Sample Use Case

Design Document - UML Class Diagram

Structure of the JSON object

Attributes and Data types

The first draft