Package Project Structure

Your main implementation lives in the src/api.py file of your project. This file will have been created for you by the template you selected when starting your project.

• If you are developing a package, you will find a class that derives from the PackageService base class
• If you are developing a plugin, you will find a class that derives from a base class specific to the plugin type.

From the implementation perspective, think of a package as a Flask app. It looks and feels like a regular Python class, but its methods are decorated with decorators bind them to HTTP endpoints. You can call instances of your package over HTTP, or you can use a Steamship client library wrapper.

Consider the following package:

class MyPackage(PackageService):
    @get("say_hello")
    def _method_name_need_not_match(self, name: str = None) -> InvocableResponse:
        return InvocableResponse(string=f"Hello, {name}")
 
    @post("do_something")
    def do_something(self, number: int = None) -> InvocableResponse:
        return InvocableResponse(json={"number": number})

Once deployed to Steamship, every new instance of this package would be associated with two HTTP endpoints:

• Expose an HTTP GET endpoint at /say_hello that accepts a URL Querystring argument named name and returns a string response
• Expose an HTTP POST endpoint at /do_something that accepts a random number and returns it in a JSON object

These per-instance endpoints could also be called using convenience functions in the Steamship Python client:

# Create or reuse an instance of the package
instance = Steamship.use("my-package", "instance-id")
 
# Invoke the methods
hello_resp = instance.invoke("say_hello", verb="GET", name="Ted")
do_resp = instance.invoke("do_something", number=5)

A few rules about writing package methods:

• The @get and @post decorators declare HTTP GET and POST endpoints, respectively
• All method arguments must be kwargs with defaults
• The method’s kwargs will be supplied by merging URL query parameters, form-encoded POST data, and JSON-encoded POST data.
• Binary input isn’t yet supported. (Email us at hello@steamship.com for workarounds if you need one).
• All methods must return a Response object

For more examples of writing package endpoints, see the example app (opens in a new tab) from our unit testing suite.

You can also define configuration parameters for your package.