REST API Worksheet
Introduction
A REST API Worksheet describes how AlchemyJ Compiler should generate a REST API package. It defines the properties of the API and the worksheets that it should refer to for additional configurations.
It contains the following sections:
- Basic Settings
- Endpoint groups
- Runtime Configuration
- Build-and-Run Web Server Configuration
- Session Management
- Advance Settings
- Maven Dependency
- Additional External Configuration
- OpenAPI Specification Settings
- OpenAPI Response Code Configuration
Basic Settings
Basic settings of the REST API.
Property | Description |
---|---|
API Name | Defines the name of the API. |
Package Name | Define the name of this Java Package. For example, com.company.myfirstjavaproject. Please take note that the package name can only be in lowercase. |
Version | Version number of this Java Project. The user of this API can use version number to specify which version of the API to import from a Maven Repository. |
Endpoint groups
It defines the REST API Endpoint Group Sheet(s) name that is included in this REST API Package.
Runtime Configuration
Properties | Description |
---|---|
Log file location | The log file path. |
Log Level | Options are Error, Warn, Info Debug, Trace |
Time-zone | Time zone used when formatting dates. For instance, "America/Los_Angeles" or "GMT+8" |
Build-and-Run Web Server Configuration
These are the properties used by the embedded web application server in the Jar when it is run.
Properties | Description |
---|---|
Port | Server port used by the embedded web server. The default is 8080. |
Root path | This is used to construct the URL. If the value is /stockorder, the url will be localhost:port/stockorder/endpoint id. Otherwise, the URL will be localhost:port/endpoint id. |
Session Management
Properties | Description |
---|---|
Session storage | Where session information should be stored. Application Server – Store the session information on the web application server. Database – Stored the Session information in the database. |
Timeout (s) | The duration of inactivity before the session expires. The setting is only for Database Session Storage. If a duration suffix is not specified, seconds will be used. 15m means 15 minutes. The default value is 1800. |
Expired session clean up cron (for the session in DB) | Schedule for cleaning up expired session if JDBC is used as a storage type. The value should be a cron expression. |
Data source ID | Identifier for JDBC data source when Session storage is Database. |
Advance Settings
Property | Description |
---|---|
Jar/War File Name | The name of the Jar file or the War file. |
Application Name | Define the name of this Java Package. For example, com.company.myfirstjavaproject. |
Maven Group ID | Define a Group ID for this package. It should follow Java's package name rules. You can use the same value as the package name. |
Maven Artifact ID | Define a unique Artifact ID for this project. The Group ID and Artifact ID together should uniquely identify this project across all projects. |
Application Configuration File Location | This defines where the AlchemyJ API should look for the application configuration file (yml). This property will be ignored if the ‘Application Configuration File Environment Variable’ is set. |
Application Configuration File Environment Variable | This defines the environment variable name the generated AlchemyJ API will use to look for the application configuration file path. Using this property is more flexible as the path can be changed after the API has been generated by modifying the environment variable. |
Log Configuration File Location | This defines where the AlchemyJ API should look for the log configuration file (yml). This property will be ignored if the ‘Application Configuration File Environment Variable’ is set. |
Log Configuration File Location Environment Variable | This defines the environment variable name the generated AlchemyJ API will use to look for the log configuration file path. Using this property is more flexible as the path can be changed after the API has been generated by modifying the environment variable. |
Stop on Formula Error | Yes - No more formula should run when an AlchemyJ Excel Standard Function returns an error. No - Subsequence formulas will keep on running even though an error has occurred. Default is No. |
Stop on Model Error | Yes - No more AlchemyJ Extended Functions should run when an error is raised to the Model Error List. No - Subsequence AlchemyJ Extended Functions will keep on running even though an error has occurred. Default is Yes. |
Throw exception on formula error | Yes - Return errors on the System Error List as the API response and return Status Code 500. No - errors on the System Error List will not trigger error response. Status Code will still be 200. Default is Yes. |
Throw exception on model error | Yes - Return errors on the Model Error List as the API response and return Status Code 500. No - errors on the Model Error List will not trigger error response. Status Code will still be 200. Default is Yes. |
Throw exception on input array overflow | Yes - Return an error when the size of the input is larger than the defined input range of the function point. No - Only the data that fit the input range will be accepted. The rest of the data will be neglected. Default is No. |
Generate Excel dump file | Yes - Generate an Excel file that represents the workbook in memory. It is like a snapshot of the model after a method is run. The dump file not applicable for High Performance Mode No - Do not generate the Excel file.Default is No. |
Excel dump file location | Define the file path of the debug Excel file when Generate Excel dump file is Yes |
Upload folder path | The temporary folder for file upload. |
Maven Dependency
If your model uses ajCustomFunction to call other Java packages, you should define them in Maven Dependency section. When AlchemyJ generates the API, it will include the related packages into the project. Each row in the table refers to one package.
Item | Description |
---|---|
Maven Group ID | The group ID of the Java package. |
Maven Artifact ID | The artifact ID of the Java package. |
Maven Version | The version number of the Java package your model needs |
Scope | compile - The dependency is required for compilation and execution. runtime - The dependency is not required for compilation but required for execution. provided - The dependency will be provided by the application server. Default is compile. |
Additional External Configuration
For any additional configurations that you want to externalize, you can put them in this section as property value pairs. They will be appended to the application.yml file.
OpenAPI Specification Settings
Besides generating the API program, you can also generate the OpenAPI specification.
Property | Value |
---|---|
Enable OpenAPI Specification Generation | Yes - Generate the OpenAPI specification for the API when generating the API. No - Do not generate. |
Document Title | The title of the specification. |
Document Description | The description of the specification. |
Contact Name | The contact name that displaying on the specification. |
Contact URL | On the specification, the contact name would be displayed as a hyper link. This specify the URL that it will go to when clicking on the contact name. |
Contact Email | On the specification, the contact email would be displayed as a hyper link. This specify the URL that it will go to when clicking on the contact email. |
API License | The license of the API. |
API License URL | On the specification, the license would be displayed as a hyper link. This specify the URL that it will go to when clicking on the license. |
Web Protocol | The protocol that the API supports. Three options are available for selection: HTTP - The API only supports calling through HTTP protocol. HTTPS - The API only supports calling through HTTPS protocol. HTTP and HTTPS - The API supports calling through both HTTP and HTTPS protocol. |
OpenAPI Response Code Configuration
From this section, you can describe the error message of the response code for the OpenAPI specification.
Item | Description |
---|---|
HTTP Response Status Code | The HTTP response status code that would be returned. It could be 200, 400, 404, 500, 401, 403 and so on. |
Message | The message that would be returned for the corresponding HTTP response status code. A default message is predefined by the worksheet template. You can customize the message if needed. |