Implement REST APIs

Operations

In API namespaces only operations are needed to be implemented. The implementation of an operation is similar to the implementation of a service. An example of the structure of the operation is shown below:

// Get path parameter
const pathParameter =  this.request.path.pathParamName;

// Get query parameter
const queryParameter =  this.request.query.queryParamName;

// Get the request body 
const body = this.request.body;

// If body is of primitive type schema
const primitiveSchemaBody = body;

// If body is of complex type schema
const complexSchemaBody1 = body.property1;
const complexSchemaBody2 = body.property2;

// Call a service
// Initialize the input entity of a service
const input =  this.factory.entity.ServiceIdentifier_Input();
 
// Initialize the value of the input property
input.property1 = complexSchemaBody1; 

// Call service and pass as input the input entity created above
const serviceOutput = await this.services.order.ServiceIdentifier(input); 

// Set the response status to 200. The status can take only the values modelled in the Designer
this.response.status = 200;

// Set the response body 

// If the body is complex
// Initialize the response body type
this.response.body  = this.factory.schema.SchemaIdentifier();

// Initialize the response body properties
this.response.body.property1 = serviceOutput.output.property1;
this.response.body.property2 = serviceOutput.output.property2;
this.response.body.property3 = serviceOutput.output.property3;
this.response.body.property4 = serviceOutput.output.property4;
this.response.body. property5 = serviceOutput.output.property5;

// If the body is primitive
// Initialize the response body 
this.response.body = serviceOutput.output.property1;

General error handler

For each API namespace there is a script called errorHandler.ts. This is used as a fallback error handler in case an error is not explicitly handled in an operation script. Additionally, it provides a general place where all general errors can be handled.

The input to the error handler is an error. If the implementation of an operation is executed and an error occurs, then the general error handler will be executed for this specific error.

Note: If the error is handled within the script of the operation, the error handler will not be executed. In case a specific error is not handled at all, then an automatic system error with error code 500 will be thrown.

Example implementation of the general error handler

The initial script will look like this:

export class ErrorMiddleware extends apitest_ErrorMiddleware{

   // This is the general error handler for API namespace 'xxx'   
   // This script gets executed if any error happens that is not yet handled in an operation 
   public handleError(error: Error) {

      // Handle the general errors that may occur throughout the implementation

   }
}

Implementation of the error handler

export class ErrorMiddleware extends apitest_ErrorMiddleware{

   // This is the general error handler for API namespace 'xxx'   
   // This script gets executed if any error happens that is not yet handled in an operation 
   public handleError(error: Error) {

      if (this.isInstanceOf.error.BusinessError(error)) {      

             this.response.status = 400;      
             const e = this.factory.schema.v1.SchemaIdentifier1();     
             e.propertyIdentifier1 = "some value";      
             this.response.body = e;    

        } else {

             this.response.status = 500;      
             this.response.body = this.factory.schema.v1.SchemaIdentifier2();   
             this.response.body.propertyIdentifier2 = true;
       }

   }
}

Note: Only the responses that are modelled in all operations can be accessed in the general error handler.