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.

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 "http://localhost:8880/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.