HTTP Endpoint API

The HTTP Endpoint API lets you create and manage custom HTTP endpoints.

The HTTP Endpoint API lets users create a custom endpoint at URL_BASE/api/v1/http-endpoint/u/<custom-endpoint>. Any incoming request to the endpoint runs a user-defined handler function and return the HTTP response.

A custom HTTP endpoint is useful for integrating Instabase with external systems. For example, you can define a custom HTTP endpoint to implement a webhook handler to integrate with an upstream system like Blend or return the output response to downstream systems in a specific format.

Unless otherwise specified, the HTTP Endpoint API requires an authorization header with the value Bearer XYZ, where XYZ is your access token. See API authorization.

In this document, URL_BASE refers to the root URL of your Instabase instance, such as https://www.instabase.com. API_ROOT defines where to route API requests for HTTP endpoint operations on your Instabase instance. Its value is URL_BASE appended by /api/v1/http-endpoint.

url_base = "https://www.instabase.com"
api_root = url_base + '/api/v1/http-endpoint' 

Create an HTTP endpoint

Description

Create a custom HTTP endpoint by sending a PUT request to URL endpoint shown above. If successful, creates a HTTP endpoint at API_ROOT/u/<path>.

handler_script_path points to a Python file on the filesystem. The Python file must be a script that contains a function named handler. See handler function example section for an example. All HTTP requests sent to this URL are sent to the handler function in this Python file.

Request parameters

Parameters are required unless marked as optional.

Response schema

All keys are returned in the response by default unless marked as optional.

Examples

Handler function

from flask import Request, Response
from typing import Any

def handler(request:Request, *args: Any, **kwargs: Any):
 if request.method == "GET":
   return Response("Hello World", mimetype="text/plain") 
 else:
   return Response(status=404)

Assuming the location of the above file is at /jaydoe/my_repo/fs/Instabase Drive/handlers/hello.py, you can create an HTTP Endpoint entry to the path /helloworld as follows:

Request

import json, requests

# The id should be unique across all HTTP endpoints entries. 
id = "my-endpoint-id"
url = api_root + f'/{id}'

headers = {
  'Authorization': 'Bearer {0}'.format(token)
}

args = {
    'path': "helloworld",
    'handler_script_path': "/jaydoe/my_repo/fs/Instabase Drive/handlers/hello.py",
}
r = requests.put(url, data=json.dumps(args), headers=headers)
resp_data = json.loads(r.content)
print(resp_data)

Response

HTTP STATUS CODE 201

Endpoint handler is created at u/helloworld

# body
{
  "id": "my-endpoint-id"
}

Trigger HTTP endpoint handler

Description

Use this API to trigger the handler function defined in the Python script located on the handler_script_path. The request to this API is forwarded to the handler function, and the response is returned to the caller.

Note: For security reasons, the handler can return only a string object or a Flask response object of mimetype application/json or text/plain. If the handler returns a string, it is returned with mimetype text/plain.

Request parameters

Because the request is forwarded to the handler function, you define the request parameters.

Response schema

Because the response from the handler is returned to the caller, you define the schema.

Examples

Example uses helloworld handler defined at create endpoint example

Request

import json, requests

path = 'helloworld'
url = api_root + f'/u/{path}'

headers = {
  'Authorization': 'Bearer {0}'.format(token)
}

r = requests.get(url, headers=headers)
print(r.content)

Response

"Hello World"

Delete an HTTP endpoint

Description

Use this API to delete a custom HTTP endpoint.

Request parameters

Parameters are required unless marked as optional.

Response schema

There is no request body. A 2XX status code indicated the request was successful.

Examples

Request

import json, requests

url = api_root + f'/{id}'

headers = {
  'Authorization': 'Bearer {0}'.format(token)
}


r = requests.delete(url, headers=headers)
resp_data = json.loads(r.content)

Response

HTTP STATUS CODE 200

Update an HTTP endpoint

Description

Use this API to update the path, handler_script_path, and state of a custom HTTP endpoint.

Request parameters

Parameters are required unless marked as optional. The path and handler_script_path values cannot be empty strings.

Response schema

All keys are returned in the response by default, unless marked as optional.

Examples

Request

import json, requests

id = "my-endpoint-id"
url = api_root + f'/{id}'

headers = {
  'Authorization': 'Bearer {0}'.format(token)
}

args = {
    'id': id,
    'path': "helloworld",
    'handler_script_path': "/jaydoe/my_repo/fs/Instabase Drive/handlers/hello.py",
    'enabled': True,
}

json_data = json.dumps(args)
r = requests.patch(url, data=json_data, headers=headers)
resp_data = json.loads(r.content)
print(resp_data)

Response

HTTP STATUS CODE 200

# body
{
  "id": "my-endpoint-id"
}

Get an HTTP endpoint

Description

Use this API to get the path, handler, state information for a custom HTTP endpoint.

Request parameters

Parameters are required unless marked as optional.

Response schema

All keys are returned in the response by default, unless marked as optional.

Examples

Request

import json, requests

url = api_root + f'/{id}'

headers = {
  'Authorization': 'Bearer {0}'.format(token)
}


r = requests.get(url, headers=headers)
resp_data = json.loads(r.content)
print(resp_data)

Response

HTTP STATUS CODE 200

# body
{
  "id": "my-endpoint-id",
  "path": "helloworld",
  "handler_script_path": "/jaydoe/my_repo/fs/Instabase Drive/handlers/hello.py",
  "state": "ENABLED"
}

List HTTP endpoint

Description

Use this API to get the path, handler and state information based on the filters. If no filters are provided, all entries for the given account are returned.

Request parameters

Parameters are required unless marked as optional.

Response schema

All keys are returned in the response by default, unless marked as optional.

Examples

Request

import json, requests

id = 'my-endpoint-id'
url = api_root + f'/list?id={id}'

headers = {
  'Authorization': 'Bearer {0}'.format(token)
}


r = requests.get(url, headers=headers)
resp_data = json.loads(r.content)
print(resp_data)

Response

HTTP STATUS CODE 200

# body
{
  "id": "my-endpoint-id",
  "endpoints": [
    {
      "id": "my-endpoint-id",
      "path": "helloworld",
      "handler_script_path": "/jaydoe/my_repo/fs/Instabase Drive/handlers/hello.py",
      "state": "ENABLED"
    }
  ]
}