Skip to main content

Create Application Plugin with STK CLI

In this tutorial, you will learn how to create two Application Plugins. The example used is a Python API using the Flask microframework.

About the Application Plugin

Creating an Application Plugin in StackSpot EDP involves writing the application code or part of it within the StackSpot App Plugin structure. Its transforms the code of a minimally functional or complete Application into "base code" or a piece of code that adds new capabilities to an existing Application.

Writing your code as a Plugin facilitates the reuse and sharing of this code in a more structured and controlled way within large teams or companies.

In the Application Plugin structure, use the following resources:

  • Plugin Documentation: Write information about how to use your plugin in the 'docs' folder with markdown files. It supports two languages (pt-br and en_us).
  • Application Code: Use the 'templates' folder to add all the files and source code that make up an Application or part of it. The content of this folder represents the code that the Plugin will generate to create the Application.
  • Plugin Test Cases: Use the 'tests' folder to create test cases for your Plugin. Creating test cases becomes useful when the Plugin has many inputs or generates many files that, without tests, could frustrate the development of Applications.
  • Edit the Plugin Configuration File: Edit the 'plugin.yaml' file. Use features like various input types, Declarative Hooks, and Connection Interfaces to add more intelligence and dynamics for those using your Plugin.

Before you begin

To create content for StackSpot EDP, you need access and permission to use a Studio for publishing your content. Be sure to check the following pages before starting the tutorial.

Step 1. Create the Plugin Structure

  1. Create a folder to hold the Plugins and then access it. In your terminal, run the following commands:
Create and access the folder for the Plugins named 'Flask-API'.
mkdir Flask-API
cd Flask-API
  1. To create the flask-api-plugin, run the "stk create plugin" command and answer the questions:
note

The questions you answer when creating any Plugin correspond to the mandatory metadata, such as the Plugin name and type. Some metadata have suggestions in parentheses, like the description text and Plugin version number.
Other questions serve to pre-configure features like using Connection Interfaces or initializing a GIT repository in the Plugin folder.

  1. To create the add-endpoint-to-flask-application Plugin, run the "stk create plugin" command and answer the questions in the terminal:

Step 2. Write the flask-api-plugin Code in the Templates Folder

  1. Open the flask-api-plugin folder and access the 'templates' folder.

  2. In the 'templates' folder, create the main.py file. Copy the following code and paste it into this file:

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. Edit the flask-api-plugin Code with JINJA Expressions

Now, insert the expressions that should receive the input values to render the Plugin template.

  1. In the main.py file, replace the following values with JINJA expressions or copy the example:
  • Replace the Python dictionary list users with the expression {{ sample_data }}.
  • Replace the route value /api/users with /{{ subdirectory }}/{{ path }}.
  • Replace the GET value inside methods=[ ] with {{ methods }}.
  • In def get_users( ):, replace it with {{ method | lower }}_{{ subdirectory }}():.

Your code should look like the following example.

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. Edit the plugin.yaml file of the flask-api-plugin

Your Plugin already comes with example inputs pre-filled which should be removed or edited as necessary.

  1. In the IDE, open the plugin.yaml file for the flask-api-plugin and remove the entire input block as shown in the example below:
plugin.yaml
schema-version: v3
kind: plugin
metadata:
name: flask-api-plugin
display-name: flask-api-plugin
description: Create an API in flask
version: 1.0.0
spec:
type: app
compatibility:
- python
docs:
pt-br: docs/pt-br/docs.md
en-us: docs/en-us/docs.md
single-use: False
technologies: # Ref: https://docs.stackspot.com/create-use/create-content/yaml-files/plugin-yaml/#technologies-1
- Api
stk-projects-only: false
inputs:
- label: Type the name of your resource
name: resource
type: text
required: true
default: Client
pattern: '([A-Z][a-z]+)+'
help: 'Inform your resource name (e.g.: Client)'
- label: Choose the http method of the new endpoint
name: method
type: select
items:
- GET
- POST
- PUT
- DELETE
- PATCH
default: GET
required: true
help: 'Inform the method of the endpoint (e.g.: post or delete)'
  1. Replace the deleted section by copying and pasting the inputs precisely as in the example:
tip

The names of each input correspond to the variables of the JINJA expressions you added earlier in your Plugin code.

Inputs do arquivo 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 Your Plugin Documentation

In order for the example in this tutorial to function properly, it has specific requirements that are crucial for building your Plugin. Therefore, make sure to include all relevant information in the 'docs' folder of the Plugin. The more comprehensive the documentation, the better the developer experience will be when using your Plugin.

  1. In the 'docs' folder, open the language folder of your choice and edit the docs.md file. For example, only edit and add the requirements in the documentation:
  • Flask==3.0.3
  • jsonify==0.5
  • requests==2.32.3
docs.md
<!-- 
******************************************

- THIS IS AN EXAMPLE OF HOW TO FILL OUT YOUR DOCUMENTATION OF CONTENT.

- FILL OUT THE TEMPLATE BELOW WITH YOUR INFORMATION SO OTHER PEOPLE CAN USE IT. THIS DOCUMENTATION WILL APPEAR ON THE SECTION OF THE STACKSPOT PORTAL.

******************************************
-->
## Plugin Name

<!-- Write concisely describing your Plugin. -->

## Requirements

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

<!--
[This is a guideline; delete this content and write your information outside this markup. <!-- ]

- Describe the requirements that the user needs to know before using the Plugin.
-->

## Usage

<!--
[This is a guideline; delete this content and write your information outside this markup. <!-- ]

Provide instructions on how to use your Plugin, including:

- What are the input parameters/inputs?
- Which methods to use?
- What are the resources?
- What is the file structure of the Plugin directory?
- And if necessary, add the dependencies of your Plugin.
-->

## Release Notes

<!--
[This is a guideline; delete this content and write your information outside this markup. <!-- ]

This section is only necessary if you publish a new Plugin version. Add what you modified, resolved issues, or latest enhancements.
-->

To test the behavior of your Plugin, StackSpot offers a way to create test cases to test some scenarios in your Plugin. For more information, access the Plugin testing guide.

Step 6. Edit the add-endpoint-to-flask-application Plugin

This Plugin will complement what you created earlier. In this example, you will use a Declarative Hook to edit the existing code of an Application created with the flask-api-plugin Plugin.

  1. Access the add-endpoint-to-flask-application Plugin folder and create a folder named 'snippets'.

  2. Inside the 'snippets' folder, create a file named 'flask-endpoint.txt' and add the following example to leverage the logic used in the Plugin with JINJA expressions:

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

Step 7. Edit the plugin.yaml file of the add-endpoint-to-flask-application Plugin

  1. In your IDE, open the plugin.yaml file of the add-endpoint-to-flask-application Plugin and remove the input block as highlighted in the following example:
schema-version: v3
kind: plugin
metadata:
name: add-endpoint-to-flask-application
display-name: add-endpoint-to-flask-application
description: Adds a new endpoint to a flask application
version: 1.0.0
spec:
type: app
compatibility:
- python
docs:
pt-br: docs/pt-br/docs.md
en-us: docs/en-us/docs.md
single-use: False
technologies: # Ref: https://docs.stackspot.com/create-use/create-content/yaml-files/plugin-yaml/#technologies-1
- Api
stk-projects-only: false
inputs:
- label: Type the name of your resource
name: resource
type: text
required: true
default: Client
pattern: '([A-Z][a-z]+)+'
help: 'Inform your resource name (e.g.: Client)'
- label: Choose the http method of the new endpoint
name: method
type: select
items:
- GET
- POST
- PUT
- DELETE
- PATCH
default: GET
required: true
help: 'Inform the method of the endpoint (e.g.: post or delete)'
  1. Replace the deleted section by copying and pasting the inputs as shown in the following example:
schema-version: v3
kind: plugin
metadata:
name: add-endpoint-to-flask-application
display-name: add-endpoint-to-flask-application
description: Adds a new endpoint to a flask application
version: 1.0.0
spec:
type: app
compatibility:
- python
docs:
pt-br: docs/pt-br/docs.md
en-us: docs/en-us/docs.md
single-use: False
technologies: # Ref: https://docs.stackspot.com/create-use/create-content/yaml-files/plugin-yaml/#technologies-1
- Api
stk-projects-only: false
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. Publishing the Plugins

Publishing on StackSpot means storing and making Stacks, Plugins, and Actions available on the platform. To publish each Plugin, access the Plugin folder and run the following command:

  1. Make sure you are logged into your account. To log in, run the stk login command and enter your email:
stk login tw-team@stackspot.com
  1. Run the stk publish plugin command:
stk publish plugin
  1. Select a Studio from your account and wait until the Plugin is fully published.

At the end of this tutorial, you will create a Plugin that generates a simple Python API using Flask and another Plugin that adds endpoints to applications developed with the first Plugin. To dive deeper into the concepts used in this tutorial, check out the following pages: