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
- Data Source Configuration
- Session Management
- LDAP Connection
- 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. The default is 8080. |
| Root path | Default or /Optional. 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. |
| Connection timeout | The number of milliseconds the server will wait after accepting a connection for the request uri line to be presented. The default is 3000. |
Data Source Configuration
Data source setting for this REST API. Multiple data source settings are supported. Please note that the Data Source ID must be in lowercase.
| Properties | Description |
|---|---|
| Obtain connection information from | Disabled - No data source is needed in this API. Data source configuration JNDI - Connect through JNDI. * |
| JNDI name | JNDI Name if JNDI is used. |
| Database | These are 3 types of the database that you can select from: MsSql Oracle MSSQL |
| JDBC URL | JDBC URL Oracle: MySQL: MSSQL: |
| User name | User name for database. |
| Password | Password for the user name. |
| Minimum number of idle connections | The minimum number of idle connections. The default is 5. |
| Maximum pool size | The maximum number of connections allowed in the pool. The default is 15. |
| Connection timeout (ms) | Connection Timeout in milliseconds. The default is 30000ms. |
| Idle timeout (ms) | Idle Timeout in milliseconds. The default is 600000ms |
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 session will expire after how long of inactivity. 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. |
LDAP Connection
LDAP connection settings for this REST project. Multiple LDAP settings can be added and supported. Please note that the LDAP Connection ID must be in lowercase. For example: primary.
| Properties | Description |
|---|---|
| Server URL | LDAP Server URL |
| Base Path | LDAP Base information |
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. False - Subsequence formulas will keep on running even though an error has occurred. |
| 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. |
| Throw exception on formula error | True - return errors on the System Error List as the API response and return Status Code 502. No - errors on the System Error List will not trigger error response. Status Code will still be 200. |
| Throw exception on model error | Yes - return errors on the Model Error List as the API response and return Status Code 502. No - errors on the Model Error List will not trigger error response. Status Code will still be 200. |
| Generate Excel dump file (on Debug Mode) | Yes - Generate an Excel file that represents the workbook in memory. It is like a snapshot of the model after a method is run. It is only effective when Debug Mode is on. No - Do not generate the Excel file. |
| Excel dump file location (on Debug Mode) | 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 use ajCallFunction 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 pare.
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 | Specify the title of the specification. |
| Document Description | Specify the description of the specification. |
| Contact Name | Specify 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 | Specify 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 | Specify 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. |