Sending requests

Documentation

April 25, 2019

This tutorial helps you to use our HTTP API with various tools.

Preparation

Using our the API requires:

  • Aito environment. For example https://my-environment.aito.app.
  • API key. It can be a read-only or read-write key depending what you are planning to do.

Concepts

The API is split into two logical parts: Query API and Database API.

Query API

Contains all read query operations, such as search, recommend, predict, etc. You need to populate the environment before you get any meaningful results via Query API.

All query operations use POST http method. The operations are completely read-only, we're using POST method for practical reasons as some clients don't allow GET with a body.

Database API

Contains all operations which controls the database: insert data, modify schema, delete tables, etc.

See the API documentation to see which HTTP method is used in

HTTP Clients

Let's go through the individual tools and how to setup them for using Aito.

Insomnia

Insomnia is a popular desktop application to make HTTP requests.

  1. Follow the install instructions here
  2. See the instructions for defining environment variables. You should define:
    {
      "readOnlyKey": "your_read_only_key",
      "readWriteKey": "your_read_write_key",
      "baseUrl": "your_environment_url"
    }
  3. Start sending requests
    • Choose the correct request method
    • Specific the URL, for example: baseUrl/api/v1/_query
    • Define the headers with:
      • content-type: application/json; charset=utf-8
      • x-api-key: {{readOnlyKey}} or x-api-key: {{readOnlyKey}}
    • Define the query body

Postman

  1. Follow the install instructions here
  2. See the instructions for defining environment variables. You should define:
    {
      "readOnlyKey": "your_read_only_key",
      "readWriteKey": "your_read_write_key",
      "baseUrl": "your_environment_url"
    }
  3. Start sending requests
    • Choose the correct request method
    • Specific the URL, for example: {{baseUrl}}/api/v1/_query
    • Define the headers with:
      • content-type: application/json; charset=utf-8
      • x-api-key: {{readOnlyKey}} or x-api-key: {{readWriteKey}}
    • Define the query body

Curl

Our API reference documentation contains curl examples for all operations. Read queries can be directly copy-pasted to your terminal.

We recommend using jq for prettifying the results!

Python

One good way to send a request using python is by using the requests library.

Here's an example of sending a search request:

import os
import requests

headers = {
  "content-type": "application/json",
  "x-api-key": os.environ['AITO_KEY']
}

body = {
  "from": "products",
  "where": {
    "id": "6411300000494"
  }
}

base_url = "https://aito-grocery-store.aito.app"
endpoint = "/api/v1/_search"

response = requests.post(base_url + endpoint, json=body, headers=headers)
print(response.json())
Back to developer docs