API Element Plugin

Introduction

The API Element Plugin extends the functionality of the default API elements available in the API Builder. This plugin type must extend the org.joget.api.model.ApiPluginAbstract abstract class, providing additional capabilities to your Joget application.

Get started

POM file adjustments

Add the following dependency to your project's POM file:

<!-- 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. See Plugin Base Abstract Class and Interface.
• Implemented org.joget.api.model.ApiPlugin.
• A base abstract class to develop a custom API Element Plugin.

Configure API methods

To generate JSON APIs from your implementation, utilize the following annotations:

@Operation

• path (String): Define the API path.
  

  The 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.

  Mandatory variable.
  Example:
   /getUserDetails
/getUserDetails/{username}
• type (enum): Defines the request method type.
  

  Available types:

  • Operation.MethodType.GET
  • Operation.MethodType.POST
  • Operation.MethodType.PUT
  • Operation.MethodType.DELETE

  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. It is recommended that the text 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

• responseCode (int): HTTP response code.
  
  Mandatory variable.
  Example value: 
  200
• description (String): A short description of the response. Default value when undefined is a blank string.
• definition (String): A definition of 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

• value (String): A short name of the parameter.
  Mandatory variable.
  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. Default value when undefined is a blank string.
  Example value:
  ApiResponse
• header (boolean): Defines if this parameter value is in the request header. Default value when undefined is false.

Here’s a sample code snippet from the 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

Returns the icon for this API element in the API Builder palette.

public String getIcon()

getTag

Returns a unique tag for the API document.

public String getTag()

Overridable methods

getTagDesc

Return a tag description for the API Document. By default, it will return the value found in your custom plugin's getLabel() method.

public String getTagDesc();

getResourceBundlePath 

Return a resource bundle path for API document generation. Default value is NULL.

public String getResourceBundlePath();

getExternalDocsDesc

Return a short description for external document for API document. Default value is NULL.

public String getExternalDocsDesc();

getExternalDocsURL 

Return a link for external document for API document generation. Default value is NULL.

public String getExternalDocsURL();

getDefinitions

Return a key & JSON Definition map for API document generation. Default value is NULL.

public Map<String, ApiDefinition> getDefinitions();

isAPIEnabled

Check if an API path is enabled for the API Key. The default behavior checks if a method exists in the specified path, in the property string "ENABLED_PATHS."

public Boolean isAPIEnabled(String method, String path);

getOperationOptions

Return a map of available operations (GET, POST, PUT, DELETE) to populate in the builder.

public Map<String, String> getOperationOptions();

usingSimpleConfig

A flag to indicate using simplified plugin configuration method. Default value is TRUE.

public boolean usingSimpleConfig();

Related documentation

• Plugin Properties Options

Download sample plugins