Skip to main content

API basics

This section contains everything you should know to use the Onna Platform API. You can find requirements, standards, and other technical details.

Requirements​

To use the API, you must meet the following requirements:

REST API​

Our API follows REST principles and adheres to the OpenAPI 3.0.1 Specification (OAS). This documentation assumes you're familiar with this standard.

API server​

All endpoints of the API are relative to the base URL https://api.onna.com/v1, which also includes the version number.

For example, the workspaces endpoint refers to https://api.onna.com/v1.

https://api.onna.com/v1/workspaces
\__________________/\_/\_________/
      server URL  version endpoint
                            path

The URL also includes the API version. For more information, see Versioning.

Security​

All requests to the API must be made using HTTPS.

Additionally, all requests require you to be authenticated, except for the endpoints to ping the API and to obtain the authentication token. For more information, check the authentication article.

Versioning​

This API uses semantic versioning to ensure that your client doesn't break. The version is declared in the URL so that you can lock to a specific one by prefix the URL.

For example, you can make a request to /v1/ping to use the version 1 of the /ping endpoint.

When the version declared in the URL is not supported, you will receive a 400 response.

Date and time format​

This API supports dates and times in ISO 8601 format.

HTTP Methods​

MethodUsage
GETFor retrieval of information about your account, workspaces, or folders and resources.
DELETETo delete a resource, the DELETE method should be used.
PUTTo update the information about a resource.
PATCHSome resources support partial modification. In these cases, the PATCH method is available.
POSTTo create a new object, your request should specify the POST method.
HEADTo retrieve metadata information, you should use the HEAD method to get the headers.

Pagination​

This API uses cursoring to divide large sets of results in multiple pages.

When a cursor value is returned in a response, you can append it as a query parameter to the following request to retrieve the remaining results.

For example:

{
    "items": [
        {
            "@name": "myworkspace1234",
            "title": "Acmecorp's workspace 1",
            "@uid": "ceba1ee161374fcab030e3dce148920c",
        },
        {
            "@name": "myworkspace5678",
            "title": "Acmecorp's workspace 2",
            "@uid": "ceba1ee161374fcab030e3dce148920c",
        }
    ],
    "cursor": "2022-02-22 11:11:11.12345//d3m0d3m0d3m0d3m0d3m0d3m0d3m0d3m0"
}

You can use the cursor value to request the remaining results. For example:

curl --location --request GET "https://api.onna.com/v1/workspaces/?cursor=2022-02-22 11:11:11.12345//d3m0d3m0d3m0d3m0d3m0d3m0d3m0d3m0" \

The cursor can also return a value of null. That happens in two scenarios:

  • When you see null in the first response, it means that all the results fit into one page
  • When you see null in a later response, it means that you got to the end of the results

Parameters​

When interacting with the API, there are 4 ways to pass parameters in your requests.

Header parameters​

Header parameters are passed JSON-object key-value pairs in requests to create or update objects, to ensure that requests are interpreted correctly.

curl -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d "{"name": "My workspace"}" \
    -X POST "https://api.onna.com/v1/workspaces"

Some notable header parameters in your header requests are:

Content-Type​

Use this parameter to declare your content type. Depending on the object, use the following values:

  • application/json when you're creating resources from non-raw data. For more information, see Resource types
  • application-octet-stream when you're creating resources from raw data. We use the [TUS] upload protocol, which requires this content type. For more information, see Raw files

Authorization​

All requests to our API must be authenticated with a bearer token. Use this parameter to pass your bearer token and ensure your requests are authorized correctly.

For more information, see Authentication.

Query parameters​

Query parameters are often used to filter the results of a GET request and are passed as standard query attributes. For example, cursor is a common query parameter. When passing query parameters:

  • Include them to your request's URI with question mark (?) at the end of the URI
  • Set each attribute with an equal sign (=)
  • Separate multiple attributes with an ampersand (&)
curl -H "Authorization: Bearer YOUR_TOKEN" \
    -X GET \
    "https://api.onna.com/v1/workspaces/?cursor=2022-02-22 11:11:11.12345//d3m0d3m0d3m0d3m0d3m0d3m0d3m0d3m0"
tip

Alternatively, you can use tools like curl to simplify the creation of your URI or use the -F flag to pass the key and value as an argument. If you use the latter, ensure the argument is a quoted string and the attribute is set to a value with an equal sign (=).

Path parameters​

Path parameters are used to read resources with variable IDs. For example, if you want to read a folder, you can send a GET request to /folders/{id}, where {id} is the unique ID of the folder.

Body parameters​

Bodies are reserved for data, metadata, and other attributes. Body parameters are passed as JSON objects when creating or updating your resources. Each resource has its own set of attributes and its own structure.

For more information, see our API reference.

Supported file formats​

You can ingest many types of resources, including raw files.

We support the most common file types and our UI is capable of rendering most of them. Other non-raw resources are also rendered in the UI.

For more information, see Resource types.

Last updated on