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.
- Understand the Role and Permissions of Your Account.
- How You Can Use a Studio.
- Create a Studio.
- Studio Visibility.
Step 1. Create the Plugin Structure
- Create a folder to hold the Plugins and then access it. In your terminal, run the following commands:
mkdir Flask-API
cd Flask-API
- To create the flask-api-plugin, run the "stk create plugin" command and answer the questions:
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.
- 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
-
Open the
flask-api-plugin
folder and access the 'templates' folder. -
In the 'templates' folder, create the
main.py
file. Copy the following code and paste it into this file:
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.
- 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 insidemethods=[ ]
with{{ methods }}
. - In
def get_users( ):
, replace it with{{ method | lower }}_{{ subdirectory }}():
.
Your code should look like the following example.
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.
- In the IDE, open the
plugin.yaml
file for theflask-api-plugin
and remove the entire input block as shown in the example below:
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)'
- Replace the deleted section by copying and pasting the inputs precisely as in the example:
The names of each input correspond to the variables of the JINJA expressions you added earlier in your Plugin code.
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.
- 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
<!--
******************************************
- 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.
-->
Test the Plugin (Recommended)
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.
-
Access the
add-endpoint-to-flask-application
Plugin folder and create a folder named 'snippets'. -
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:
@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
- In your IDE, open the
plugin.yaml
file of theadd-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)'
- 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:
- 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
- Run the
stk publish plugin
command:
stk publish plugin
- 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: