Consuming Slurpy

Deprecation

Endpoint consuming will be deprecated. Use the REST API v1 instead.

Endpoints

Endpoints can be consumed via a REST API, and are protected using JWT based authentication and per-endpoint ACL.

The base URL is /api/collections/<endpoint-name>/.

<endpoint-name> corresponds to the name given to the endpoint at creation, not its id.

API v1

The API v1 allows to query more data (collections, versions, etc). Schema can be found here

Authentication

To query the API, an authentication token is required.

Obtaining a token

To obtain a new token, make a POST request to /api/token/ with the following payload.

{
    "username": "your-username",
    "password": "your-password"
}

The response contains an access and a refresh token.

{
    "refresh": "secret-access-token",
    "access": "secret-refresh-token"
}

Access token can be refreshed using a POST request to /api/token/refresh/ with the following payload.

{
    "refresh": "secret-refresh-token"
}

The response is the same as for /api/token/.

Using the token

Add the access token in the Authorization header of requests made to the Slurpy REST API.

Authorization: Bearer secret-access-token

Pagination

By default, every items of the collection are returned.

But Slurpy has an optional pagination mechanism, which can be activated by including a one or more query parameters

Param	Type	Description
$limit	number	Number of items per page
$page	number	Which page to retrieve
$with_meta	boolean	Wether to add pagination "headers"

Theses query parameters are prefixed with a $ to avoid collision with the filtering parameters.

By default, the root of the response is a list of items.

[
    {
        "name": "Alice",
        "age": "25",
        "address": {
            "city": "La Chaux-de-Fonds",
            "zipcode": "2300",
        }
    },
    {
        "name": "Bob",
        "age": "30",
        "address": {
            "city": "Neuchâtel",
            "zipcode": "2000",
        }
    },
    // ...
]

With the parameter $with_meta set to true, the root of the response is an object with the following attributes.

{
    "page": 1,          // Current page number
    "next": 2,          // Next page number or null if none
    "previous": null,   // Previous page number or null if none
    "last": 7,          // Last page number
    "limit": 3,         // Page size (last page could have less items)
    "count": 20,        // Total number of items
    "items": [          // Items list of this page
        {
            "name": "Alice",
            "age": "25",
            "address": {
                "city": "La Chaux-de-Fonds",
                "zipcode": "2300"
            }
        },
        {
            "name": "Bob",
            "age": "30",
            "address": {
                "city": "Neuchâtel",
                "zipcode": "2000"
            }
        },
        // ...
    ]
}

Streaming response

By default, Slurpy build a response and then sent it to the client. Building the entire response before sending it can take time and load the server memory.

If needed, you can change this behavior by enabling streaming response using the query parameter $streaming=true.

Doing so has the following benefits and limitations.

Benefits

• Reduced Memory Usage: The server does not need to hold the entire response content in memory.
• Lower Latency: Clients start receiving data as soon as it is available.
• Improved User Experience: Users get immediate feedback, especially in long-running processes.

Limitations

• Not Suitable for All Use Cases: Some clients or proxies may not support chunked transfer encoding.

Filtering

Filtering is done via query parameters where key is a field name of the items of the collection.

Along with the field name, a suffix can be provided to change the filtering behavior.

The field name and the suffix are separated by __.

Suffix	Description	Example
-	Equality	name=Bob
gt	Greater than	age__gt=18
gte	Greater than or equal	age__gte=18
lt	Lesser than	age__lt=18
lte	Lesser than or equal	age__lte=18
ne	Not equal	age__ne=18
in	Value in list	name__in=Alice,Bob
nin	Value not in list	name__nin=Alice,Bob
like	Value included in string, case sensitive	name__like=Bob
ilike	Value included in string, case insensitive	name__ilike=bob

Moreover, you can access nested fields with the dot-notation, for example address.zipcode=2300.

Precisions when working with date fields

gt, gte, lt and lte filter also work for date/datetime fields: creation_date__lt=2010-07-02T14:24:00.

Supported formats can be found here, chapter Formats, starting with Year and month. Using Year without month is not supported as it could cause conflicts with other data types.

Info

Using Complete date with the value 1997-01-01 is the same as:

• Using Year and month with the value 1997-01
• Using Year with the value 1997 alone.

Value types

Every value of a filter is cast to number (float) if possible. If the filter value is null, it is cast to None which allows to filter endpoint records on null values. Otherwise, raw string is used. Note that a string and a number are not equal : "2300" != 2300.

To force using raw string, encapsulate the value in singles quotes : address.zipcode='2300' or my_strange_variable='null'

Passing Query Parameters to the Datasource

For certain datasources, such as Oracle Stored Procedures and Oracle Stored Functions, you can pass query parameters directly to the datasource.

Flow

1. Define an in parameter in the datasource configuration and assign it a name (e.g., my_in_param).
2. Create an endpoint that will ultimately utilize this datasource.
3. Call the endpoint with the following query parameter: $ds_param:my_in_param=value-of-param.
4. The datasource will then receive value-of-param as the input for the parameter my_in_param.

This approach allows dynamic values to be seamlessly passed to datasources, enhancing flexibility in data querying and processing.

The query parameter given to endpoint has to be prefixed by $ds_param: so that it does not interfere with filtering parameters.

Expected result

For Oracle Stored Procedure datasources with "out" parameters, the result will be something like

[
  {
    "out_param_name": "value written by procedure"
  }
]

For Oracle Stored Function datasources with return value, the result will be something like

[
  {
    "result": "value returned by procedure"
  }
]