Introduction

This is the API documentation for the Polyteia platform.

API Structure

Polyteia platform can be fully interacted with via the API offered by the platform. API follows the RPC style of communication.

Why RPC?

RPC is a protocol that allows a computer program to request a service from a computer program located in another computer on a network without having to understand the network's protocols. Polyteia chose RPC over REST because of the following reasons:

• Simplicity: RPC enables direct method calls between client and server with minimal overhead. Unlike REST which requires mapping operations to HTTP verbs and designing resource hierarchies, RPC allows straightforward procedure calls with natural parameter passing.

• Performance: RPC typically requires fewer round trips than REST by supporting batched operations in a single call. It also has lower overhead since it doesn't require the complex HTTP machinery and can use more efficient binary protocols.

• Strongly-typed Interfaces: With RPC, interfaces are defined through IDL (Interface Definition Language), enabling automatic code generation, type safety, and better documentation through service contracts.

• Flexibility: RPC isn't constrained by REST's resource-oriented model, making it better suited for operation-centric actions that don't map cleanly to CRUD operations on resources.

Commands and Queries

Polyteia platform supports two types of RPC calls:

• Commands: Commands are used to create, update or delete resources. Commands are used to mutate the state of the platform.

• Queries: Queries are used to read resources. Queries are used to read the state of the platform.

Example Command

curl -X POST 'https://app.polyteia.com/api' \
    -header "Content-Type: application/json" \
    -header "Authorization: Bearer <your_access_token>" \
    --data '{
        "command": "create_dataset",
        "params": {
            "name": "Customers List",
            "solution_id": "sol_cv33u4n0i6q45p93i930",
            "description": "Customers list 4",
            "source": "https://example.com/dataset.csv",
            "slug": "customers_list"
        }
    }'

Example Query

curl -X POST 'https://app.polyteia.com/api' \
    -header "Content-Type: application/json" \
    -header "Authorization: Bearer <your_access_token>" \
    --data '{
        "query": "get_dataset",
        "params": {
            "id": "ds_cv4t2cf0i6q1gflvu4m0"
        }
    }'

Endpoint

The endpoint for the API is https://app.polyteia.com/api.

All requests are sent to this endpoint with POST method. No other methods are supported.

Required Headers

• Content-Type: application/json

• Authorization: Bearer <your_access_token>

Request Body Structure

Each request is a JSON object with the following fields:

• command: The command to be executed.

• query: The query to be executed.

• params: The parameters for the command or query. Each command and query has its own parameters. You can find the parameters in the documentation for each command and query.

One of the command or query field is required.

Example Request

{
    "command": "create_dataset",
    "params": {
        "name": "Customers List",
        "solution_id": "sol_cv33u4n0i6q45p93i930",
        "description": "Customers list 4",
        "source": "https://example.com/dataset.csv",
        "slug": "customers_list"
    }
}

Response

Response is always a JSON object. Response is always in the same format for all commands and queries. You can find the response format in the documentation for each command and query. Even if the command or query fails, the response status code is always 200 except unauthorized error where you receive the code 401. Please ensure you check the response body to see if the command or query was successful or if there was an error.

In all responses, whether the command or query succeeds or fails, the response will always include either a data field or an error field. When the command or query executes successfully, the response will contain a data field with the relevant information. Conversely, if the command or query encounters an issue, the response will include an error field detailing the problem. One of these fields will always be present to indicate the outcome of the request.

Successful Response

{
    "data": {
        "id": "ds_123456789",
        "name": "Customers List",
        "created_at": "2023-10-01T12:00:00Z"
    }
}

Error Response

{
    "error": {
        "code": 500,
        "message": "internal error",
        "details": []
    }
}

Error Handling

If the command or query fails, the response body will contain an error message. The error message will be in the following format:

{
    "error": {
        "code": 500,
        "message": "internal error",
        "details": []
    }
}

Error Codes

• 400: Bad Request - The request was malformed or invalid

• 401: Unauthorized - Authentication is required or failed

• 403: Forbidden - The request was understood but refused

• 404: Not Found - The requested resource was not found

• 500: Internal Server Error - An error occurred on the server