Create Application Plugin with STK CLI

In this guide, you will learn how to create two Application Plugins in StackSpot EDP using the STK CLI. The practical example demonstrates a Python API built with the Flask microframework.

Overview of the Application Plugin

Creating an Application Plugin in StackSpot EDP means developing your Application code, or part of it, within the StackSpot Application Plugin structure. The Plugin can represent either a minimally functional base Application or a code snippet that adds new features to an existing Application.

By structuring your code as a Plugin, you make it easier to reuse and share solutions in a standardized and controlled way across teams or organizations.

Use the following components in your Application Plugin structure:

Plugin Documentation: Store usage information in the docs folder. Documentation can be provided in both English (en-us) and Portuguese (pt-br).
Application Code: Place all files and source code that compose the Application, or part of it, in the templates folder. This content is generated when the Plugin is executed.
Test Cases: Store Plugin test scenarios in the tests folder. This is especially useful for Plugins with many inputs or that generate multiple files.
Plugin Configuration: The plugin.yaml file centralizes Plugin settings, including input types, Declarative Hooks, and Connection Interfaces, making the Plugin more dynamic and intelligent.

Prerequisites and Permissions

Before getting started, ensure you have access and permission to create or use a Studio in StackSpot EDP. Refer to the resources below for more information:

Step 1. Create the Plugin Structure

Create a folder for your Plugins and access it via the terminal:
```
mkdir Flask-API
cd Flask-API
```
Run the following command to start creating the flask-api-plugin. Respond to the prompts about name, type, description, version, and other configurations:
```
stk create plugin
```
note
The prompts cover mandatory Plugin metadata such as name, type, description, and version. Some prompts allow you to preconfigure features like Connection Interfaces or initialize a Git repository.
Run the command again to create the add-endpoint-to-flask-application Plugin:
```
stk create plugin
```
Provide the necessary information for the new Plugin as prompted.

Step 2. Implement the `flask-api-plugin` Code

In the flask-api-plugin directory, access the templates folder.

Create the main.py file and add the following code:

main.py
from flask import Flask, jsonify, request

app = Flask(__name__)

# Sample data
users = [
    {"id": 1, "name": "John Doe"},
    {"id": 2, "name": "Jane Doe"}
]

@app.route('/')
def home():
    return "Welcome to the Flask API!"

@app.route('/api/users', methods=['GET'])
def get_users():
    return jsonify(users)

if __name__ == '__main__':
    app.run(debug=True)

Step 3. Make the Code Dynamic with Jinja Expressions

Now, use Jinja expressions to make your code dynamic and customizable via Plugin inputs.

In the main.py file, make the following replacements:
- Replace the users list with {{ sample_data }}
- Replace the route '/api/users' with '/{{ subdirectory }}/{{ path }}'
- Replace the method 'GET' in methods=[ ] with {{ method }}
- Rename the function def get_users() to def {{ method | lower }}_{{ subdirectory }}():

The updated code should look like this:

main.py
from flask import Flask, jsonify, request

app = Flask(__name__)

# Sample data
users = {{ sample_data }}

@app.route('/')
def home():
    return "Welcome to the Flask API!"

@app.route('/{{ subdirectory }}/{{ path }}', methods=['{{method}}'])
def {{ method | lower }}_{{ subdirectory }}():
    return jsonify(users)

if __name__ == '__main__':
    app.run(debug=True)

Step 4. Configure the `plugin.yaml` File for `flask-api-plugin`

In the plugin.yaml file, remove the default inputs block.

Insert the following inputs block, matching variable names to the Jinja expressions in your code:

tip

The input names correspond to the Jinja variables used in your Plugin code.

Inputs for plugin.yaml
inputs:
  - label: Type the subdirectory of your URL
    name: subdirectory
    type: text
    required: true
    default: users
    pattern: '([a-z]+)+'
  - label: Type the path of your URL
    name: path
    type: text
    required: true
    default: id
    pattern: '([a-z]+)+'
  - label: Sample Data
    name: sample_data
    type: list
    add-question: Add one more user?
    input:
      label: User Sample data
      type: object
      inputs:
        - name: id
          type: int
          label: User ID
        - name: user_name
          type: text
          label: User Name
  - label: Choose the http method of the new endpoint
    name: method
    type: select
    items:
      - GET
      - POST
      - PUT
      - DELETE
      - PATCH
    default: GET
    required: true

Step 5. Create Plugin Documentation

Clear and complete documentation improves the experience for anyone using your Plugin. Use the example below to start your Plugin documentation:

In the docs folder, choose the desired language and edit the docs.md file. Include the Plugin requirements:

docs.md
## Plugin Name

Provide a concise description of your Plugin's purpose.

## Requirements

- Flask==3.0.3
- jsonify==0.5
- requests==2.32.3

## Usage

Provide instructions on how to use your Plugin, including:
- Input parameters
- Supported methods
- Created resources
- Plugin directory file structure
- Any additional dependencies

## Release Notes

This section is optional and should be used to record changes or improvements in new Plugin versions.

Test the Plugin (Recommended)

Test your Plugin's behavior using test cases. For more details, see the Plugin Testing Guide.

Step 6. Implement the `add-endpoint-to-flask-application` Plugin

This Plugin complements the previous one by allowing you to add endpoints to Applications created with flask-api-plugin using a Declarative Hook.

In the add-endpoint-to-flask-application directory, create the snippets folder.

Inside snippets, create the flask-endpoint.txt file with the following content:

flask-endpoint.txt
@app.route('/{{ subdirectory }}/{{ path }}', methods=['{{method}}'])
def {{ method | lower }}_{{ subdirectory }}():
    return jsonify(users)

Step 7. Configure the `plugin.yaml` File for `add-endpoint-to-flask-application`

In the plugin.yaml file, remove the initial inputs block.

Insert the following block, including the Declarative Hook to edit the main.py file:

inputs:
  - label: Type the subdirectory of your URL
    name: subdirectory
    type: text
    required: true
    default: users
    pattern: '([a-z]+)+'
  - label: Type the path of your URL
    name: path
    type: text
    required: true
    default: id
    pattern: '([a-z]+)+'
  - label: Choose the http method of the new endpoint
    name: method
    type: select
    items:
      - GET
      - POST
      - PUT
      - DELETE
      - PATCH
    default: GET
    required: true
hooks:
  - type: edit
    trigger: after-render
    path: main.py
    changes:
      - search:
          string: "if __name__ == '__main__':"
          insert-before:
            snippet: snippets/flask-endpoint.txt

Step 8. Publish the Plugins

Publishing a Plugin in StackSpot means storing and making it available on the platform. For each Plugin:

Make sure you are authenticated in StackSpot. Run:
```
stk login your-email@stackspot.com
```
In the Plugin directory, run:
```
stk publish plugin
```
Select a Studio from your account and wait for the publication to complete.

After completing this guide, you will have created a Plugin that generates a simple Python API using Flask and another Plugin that adds endpoints to Applications created with the first Plugin.

To deepen your understanding, check out:

Overview of the Application Plugin

Prerequisites and Permissions

Step 1. Create the Plugin Structure

Step 2. Implement the flask-api-plugin Code

Step 3. Make the Code Dynamic with Jinja Expressions

Step 4. Configure the plugin.yaml File for flask-api-plugin