Documentation

Welcome to the documentation page. Here you'll find all the relevant information about setting up, integrating, and using the API Gateway and its related components.

Important Notice

Your route domain is your username followed by ".thread4.eu". Example "username.thread4.eu".

Tutorial: Hello World!

This is a simple tutorial to get you started with the API Gateway. In this tutorial, we will create a simple "Hello World!" API using the API Gateway.

Step 1: Create a function | To create a function, go to the Functions page and click on the "Save Function" button. | Enter a name for your function and enter this code:

This function will return a simple "Hello World!" message when called. Save the function, click on Edit and then Deploy to deploy the function.

Step 2: Create a route | All users have a default gateway with the prefix "/". | Go to Gateways and click on the "New Route" button. | Enter the path "hello" for the route and select the method "GET". | Select the function you just created from the dropdown list. | Click on the "Save Route" button to create the route.

Now you can test your API by going to the URL "https://your-username.thread4.eu/hello". You should see the "Hello World!" message returned by your function.

Section 1: Gateway Overview

A Gateway acts as the entry point for your routes, defined by a prefix that all associated routes automatically inherit. Each user has one Gateway, created by default with the prefix "/". While a Gateway can have many routes, its prefix must be unique and cannot conflict with existing route paths. Valid prefixes may only include letters, numbers, and slashes ("/"). Every Gateway also requires a unique name for easy identification.

Section 2: Route Overview

A Route defines a single endpoint within a Gateway. It determines how requests are handled and routed to their underlying logic. Each Route belongs to a specific Gateway and User, and can optionally be linked to a Function that executes when the route is triggered. Routes are cached for 60 seconds, meaning that if a route is not accessed within that time frame, it will be removed from the cache and changes will not be reflected until the cache is refreshed.

Every Route must specify an HTTP method, such as GET or POST, and a path that uniquely identifies the endpoint within its Gateway. The path must be made up of only letters and numbers—it cannot include slashes or special characters, and it must not start with a "/". To ensure clarity and manageability, path names are limited to 64 characters.

Special routes with parameters in path

Routes can also include parameters in the path, allowing for dynamic routing based on user input.For example, a route with the path "user/<id>" would match requests to "/user/123" and "/user/456", where "123" and "456" are the values of the "id" parameter. The parameter value can be accessed in the function using the event object, which contains the request data.

Planned Feature: API Keys

API Keys are a planned feature that will allow users to authenticate and authorize requests to their API.Each API Key will be associated with specific permissions, enabling fine-grained control over access to resources and endpoints.

This feature will help ensure that only authorized users and applications can interact with the API, enhancing security and control.

Example

Suppose you have a gateway with the prefix "/api" and you want to create a route for adding a new user.You could define a route with the path "add-user" and the method POST.This would create an endpoint at "/api/add-user" that accepts POST requests.If you also wanted to create a route for retrieving user information, you could define another route with the path "get-user" and the method GET.This would create an endpoint at "/api/get-user" that accepts GET requests.

Section 3: Functions

Functions are dynamic Python functions that can be associated with a route. They are powered by a custom Python engine running on FastAPI, allowing for real-time updates without server restarts. Functions are cached for 60 seconds, meaning that if a function is not accessed within that time frame, it will be removed from the cache and changes will not be reflected until the cache is refreshed.

Functions need to define a function named "handler" that takes a event and context as arguments. Same interface as AWS Lambda. The event parameter contains the request data, while the context parameter contains metadata about the request. The function can either return a body directly, either string, dict. The other option is to return a response dictionary with headers, status_code, and body.

Allowed response headers

• Content-Type
• Access-Control-Allow-Origin
• Access-Control-Allow-Methods
• Access-Control-Allow-Headers
• X-Custom-Header

Allowed Modules and Integrations

The following modules are allowed in your functions:

• json
• datetime
• math
• pickle
• More modules will be added in the future.

Potential integrations include:

• PostgresSQL
• Slack
• Redis
• More to come!

Examples

Example of a Python function that returns HTML

Example of a function which returns HTML, with content type and status code

Example of a function which returns JSON:

Example of a function which returns JSON, with content type and status code

Example function using Thread4 module to retrieve HTML file.

Example function using Thread4 Template module (Jinja2) to render HTML file.

Why is my function not working?

If your function is not working, it may be due to one of the following reasons:

• The function is not deployed. Make sure to deploy your function after making changes.
• The function is not associated with a route. Make sure to associate your function with a route.
• The function is not returning a valid response. Make sure to return a valid response from your function.
• The function is not using the correct event and context parameters. Make sure to use the correct parameters in your function.

Thread4 Module

The Thread4 module is a custom module that provides additional functionality for your functions.It includes models to retrieve documents and render HTML templates (Jinja2).

Thread4 Document Model

The Thread4 Document model allows you to retrieve documents from your API. The model provides methods to retrieve documents by their name.

Important Notice

The Document model requires the handler to be async.

Example of retrieving a document using the Thread4 Document Model:

from Thread4 import Documents
docs = Documents()
await docs.get("index.html")

Thread4 Template Model

The Thread4 Template model allows you to render HTML templates using Jinja2. The model provides methods to render templates with context data.

Example of rendering a template using the Thread4 Template Model:

from Thread4 import Template
template = Template("<h1>{{ title }} - {{ name }}</h1>")
await template.render(tile="Hello World", name="Thread4")

Or you can use the Template class to render a template from a string:

from Thread4 import Template
template = Template()
await template.render(template_str="<h1>{{ title }} - {{ name }}</h1>", tile="Hello World", name="Thread4")

Section 4: Documents

Documents are rich text files or HTML files that can be served from your API. They can be fetched through a custom Python Module that can be imported into your functions. Allowing users to create HTML web pages and serve them from their API. Documents are not cached and are served directly from the API.

Documents can be used to store and manage content, such as user guides, API documentation, or any other type of information that needs to be served over the web.

Section 5: Integrations

Integrations are a planned feature that will allow users to connect their applications with external services and APIs.

This will enable users to easily integrate their applications with third-party services, such as databases, authentication providers, and other APIs.

• PostgresSQL / SQLite3
• Redis
• Slack
• More to come!

This will help users to easily connect their applications with external services and APIs, making it easier to build and deploy complex applications.

Storage (Planned)

Storage is a planned feature that will allow users to manage JSON blobs and key-value stores.

This will enable users to store and retrieve data in a structured format, making it easier to manage and manipulate information within their applications.

Queues (Planned)

Queues are a planned feature that will allow users to manage tasks and jobs within their applications.

This will enable users to create and manage background jobs, allowing for better performance and scalability within their applications.

Secrets (Planned)

Secrets are a planned feature that will allow users to manage sensitive data and secrets within their applications.

This will enable users to securely store and manage sensitive information, such as API keys, passwords, and other confidential data.

This will help ensure that sensitive information is kept secure and is not exposed to unauthorized users.