ORDA Data Model Classes and REST

In a previous blog post, you learned about ORDA classes and the possibilities they offer to make your coding experience smoother. In this blog post, you’ll see how to use them with the REST server.

Let’s see it in action!

HDI: Examples to use ORDA classes with REST server

We have a database named LearningSystem which contains the following tables:

This database is exposed as a REST server on localhost (port 8044). All of the defined functions in its classes can be called using REST requests in a POST operation.

Calling a function defined in the datastore class

The datastore object is retrieved using the /rest/$catalog prefix.

A getStatistics() function has been defined in the DataStore datastore class. The function returns a collection with information about the schools.

Class extends DataStoreImplementation

Function getStatistics

 C_COLLECTION($0;$result)
 C_OBJECT($obj;$school)

 $result:=New collection()


For each ($school;This.Schools.all())
 $obj:=New object()
 $obj.name:=$school.name
 $obj.city:=$school.city.name
 $obj.numberOfStudents:=$school.students.length
 $result.push($obj)
End for each

$0:=$result


You can call it with the http://127.0.0.1:8044/rest/$catalog/getStatistics URL.

Here’s the response from the server:

{
 "result": [
    {
    "name": "Old school",
    "city": "Solebury",
    "numberOfStudents": 3
    },
    {
    "name": "History Institute",
    "city": "Solebury",
    "numberOfStudents": 3
    },
    {
    "name": "4D University",
    "city": "Hummelstown",
    "numberOfStudents": 3
    }
  ]
}

 

Calling a function defined in a dataclass class

A dataclass object is accessed via the /rest/dataClassName prefix.

A registerStudent() function has been defined in the Schools dataclass class. The function receives student’s data in an object and checks if the student’s English level meets the school’s required level. If their English level is OK, the function creates and saves the Students entity.

Class extends DataClass

Function registerStudent

 C_OBJECT($1;$data;$student;$school;$result;$0)

 $data:=$1

 $school:=ds.Schools.query("name = :1";$data.schoolName).first()
 $result:=New object("success";True)

If ($data.englishLevel < $school.minAcceptedEnglishLevel)
 $result.success:=False
 $result.statusText:="The english level is not enough"
 $0:=$result
End if

If ($result.success)
 $student:=ds.Students.new()
 $student.fromObject($data)
 $student.finalExam:="To take"
 $student.school:=$school
 $result:=$student.save()
 $0:=$student
End if

It’s accessible through the http://127.0.0.1:8044/rest/Schools/registerStudent URL. 

The parameters must be passed as a collection, in the body of the request:

[
 {
 "firstname": "Mary",
 "lastname": "Smith",
 "englishLevel": 2,
 "schoolName": "Math school"
 }
]

Here’s the response from the server:

{
  "__entityModel": "Students",
  "__DATACLASS": "Students",
  "__KEY": "9",
  "__TIMESTAMP": "2020-06-03T13:08:13.542Z",
  "__STAMP": 1,
  "ID": 9,
  "firstname": "Mary",
  "lastname": "Smith",
  "englishLevel": 2,
  "schoolID": 4,
  "finalExam": "To take",
  "school": {
    "__deferred": {
      "uri": "/rest/Schools(4)",
      "__KEY": "4"
     }
   }
}


Calling a function defined in an entity class

An entity object is accessed via the /rest/dataClassName(key) prefix, where key is the primary key of the entity.

A studyingInSameCity() function has been defined in the StudentsEntity entity class. It returns all other students studying in the same city as the current Student.

Class extends Entity

Function studyingInSameCity
 C_OBJECT($0;$city)

 $city:=This.school.city
 $0:=$city.schools.students.minus(This)

This example is for an entity with primary key = 7. It’s accessed via the http://127.0.0.1:8044/rest/Students(7)/studyingInSameCity/?$attributes=firstname, lastname URL.

We apply the studyingInSameCity() function on this entity and filter the returned attributes to get only firstname and lastname (/?$attributes=firstname, lastname).

Here’s the response from the server:

{
 "__DATACLASS": "Students",
 "__entityModel": "Students",
 "__GlobalStamp": 0,
 "__COUNT": 3,
 "__FIRST": 0,
 "__ENTITIES": [
    {
     "__KEY": "5",
     "__TIMESTAMP": "2020-06-16T13:59:51.095Z",
     "__STAMP": 1,
     "firstname": "Ricky",
     "lastname": "Coyle"
    },
    {
     "__KEY": "6",
     "__TIMESTAMP": "2020-06-16T13:59:51.095Z",
     "__STAMP": 1,
     "firstname": "Alonzo",
     "lastname": "Zapata"
    }
  ],
 "__SENT": 3
}

Calling a function defined in an entity selection class

An entity selection object can be accessed via the filter syntax. For example, /?$filter=”finalExam=’To take'” to get all of the students with a value of “To take” for the finalExam attribute.

An entity selection can be accessed through other ways, too so be sure to check the documentation.

A setFinalExam() function has been defined in the StudentsSelection entity selection class. It updates the finalExam attribute of each student with the given value.

Class extends EntitySelection

Function setFinalExam

 C_TEXT($1;$value)
 C_OBJECT($student;$status;$0)

 $value:=$1


For each ($student;This) Until (Not($status.success))
 $student.finalExam:=$value
 $status:=$student.save()
End for each

$0:=$status

In this example, it’s accessible through the http://127.0.0.1:8044/rest/Students/setFinalExam/?$filter=”finalExam=’To take'” URL.

Here’s the body of the request:

[
"Passed"
]

Here’s the response from the server (all of the concerned students have been properly updated):

{
 "result": {
   "success": true
   }
}


Download the HDI to see all the above in action.

 

Note:
Be sure to check out this post about keywords. Since 4D v18 R5, functions are not exposed by default. Don’t forget to mark the functions you want to expose!