Usages
- API Element Plugin is used as an extension of functions on top of the default API elements available in the API Builder.
- This plugin type must extend org.joget.api.model.ApiPluginAbstract abstract class.
POM file adjustments
Add the project dependency below:
<!-- Add apibuilder_api dependency --> <dependency> <groupId>org.joget.api</groupId> <artifactId>apibuilder_api</artifactId> <version>${project.version}</version> <scope>provided</scope> </dependency>
Abstract Class
org.joget.api.model.ApiPluginAbstract
- Under apibuilder_api module
- Extended org.joget.plugin.base.ExtDefaultPlugin. Please refer to Plugin Base Abstract Class and Interface.
- Implemented org.joget.api.model.ApiPlugin.
- A base abstract class to develop a custom API Element Plugin.
API Methods
To generate JSON APIs from your implementation, see the available Java annotations with samples below:
@Operation
Variable | Data Type | Mandatory | Description |
|---|---|---|---|
| path | String |
| API path name to call the method. Always start with a forward slash ( / ). To include path parameters, after annotating @Param with the method parameter (see doc below), you can add the variable enclosed within curly braces into the path. Example: /getUserDetails /getUserDetails/{username} |
| type | enum | Defines the request method type. Available types:
Default value when undefined is Operation.MethodType.POST. | |
| summary | String | Provides a brief description of this operation. This is the value to display as the method name in the API Builder. Recommended to be 120 characters or less for proper visibility when previewing API. Default value when undefined is a blank string. | |
| description | String | A verbose description of the operation. Default value when undefined is a blank string. | |
| deprecated | boolean | Allows an operation to be marked as deprecated. Default value when undefined is false. |
@Responses
Consists of @Response annotation(s). Information in table here:
Variable | Data Type | Mandatory | Description |
|---|---|---|---|
| responseCode | int |
| The HTTP response code. Example value: 200 |
| description | String | A short description of the response. Default value when undefined is a blank string. | |
| definition | String | A definition to the data schema in response. Default value when undefined is a blank string. | |
| dataClass | String | A class to the data in response. Default value when undefined is a blank string. | |
| contentType | String | A content type of the data in response. Default value when undefined is "application/json". | |
| array | boolean | Defines if this response value is an array. Default value when undefined is false. |
@Param
Variable | Data Type | Mandatory | Description |
|---|---|---|---|
| value | String |
| A short name of the parameter. Example value: username |
| required | boolean | Defines if this parameter value is mandatory. Default value when undefined is true. | |
| description | String | A verbose description of the parameter. Default value when undefined is a blank string. | |
| definition | String | The key of definition provided by ApiPlugin. Example value: ApiResponse Default value when undefined is a blank string. | |
| header | boolean | Defines if this parameter value is in the request header. Default value when undefined is false. |
For detailed examples, do check out the Sample Plugins attached in this page.
Here is a sample code snippet from the sample Basic Current User API plugin:
@Operation(
path = "/getUserDetails",
type = Operation.MethodType.GET,
summary = "Get user details",
description = "Get user details via username, else get current user."
)
@Responses({
@Response(responseCode = 200, description = "Success", definition = "User"),
@Response(responseCode = 404, description = "User data not found", definition = "ApiResponse")
})
public ApiResponse getUserDetails(
@Param(value = "username", required = false, description = "Username of user.") String username) {
ExtDirectoryManager dm = (ExtDirectoryManager) AppUtil.getApplicationContext().getBean("directoryManager");
User user = dm.getUserByUsername(username);
WorkflowUserManager wum = (WorkflowUserManager) AppUtil.getApplicationContext().getBean("workflowUserManager");
User currentUser = wum.getCurrentUser();
if (user != null) {
return new ApiResponse(200, user, getFields());
} else if (user == null && currentUser != null) {
return new ApiResponse(200, currentUser, getFields());
} else {
return new ApiResponse(404, AppPluginUtil.getMessage("BasicCurrentUserAPI.resp.404", getClassName(), getResourceBundlePath()));
}
}
Abstract Methods
getIcon
public String getIcon()
Return the icon to show for this API Element in the API Builder palette.
getTag
public String getTag()
Return a unique tag for the API Document.
Overridable Methods
getTagDesc
public String getTagDesc();
Return a tag description for API Document.
Default will return the value found in getLabel() method in your custom plugin.
getResourceBundlePath
public String getResourceBundlePath();
Return a resource bundle path for API document generation.
Default value is NULL.
getExternalDocsDesc
public String getExternalDocsDesc();
Return a short description for external document for API document.
Default value is NULL.
getExternalDocsURL
public String getExternalDocsURL();
Return a link for external document for API document generation.
Default value is NULL.
getDefinitions
public Map<String, ApiDefinition> getDefinitions();
Return a key & JSON Definition map for API document generation.
Default value is NULL.
isAPIEnabled
public Boolean isAPIEnabled(String method, String path);
Check if an API path is enabled for the API Key.
Default behavior will check if method exist in the specified path, in the property string "ENABLED_PATHS".
getOperationOptions
public Map<String, String> getOperationOptions();
Return a map of available operations (GET, POST, PUT, DELETE) to populate in builder.
usingSimpleConfig
public boolean usingSimpleConfig();
A flag to indicate using simplified plugin configuration method.
Default value is TRUE.
Plugin Properties Options
Please refer to Plugin Properties Options for more information.
Sample Plugins
Basic Current User API
Sample API with property options