Query parameters

Each API endpoint supports these options using URL query parameters:

Fields

Ideanote requires the user of the API to specify a comma-separated list of fields to return. This is done in order to ensure performance and to make populating nested entities possible.

Populating direct fields

?fields=id,title,question will return the following JSON structure:

{
    "id": "abc",
    "title": "Title",
    "question": "Question"
}

It's possible to populate fields directly on the entity (see example).

You can find an overview of what fields you can populate for each entity. For example, you can find all fields on the Mission entity here

Populating nested fields (dot-syntax)

?fields=id,title,cover.kind,cover.url.original will return the following JSON structure:

{
    "id": "abc",
    "title": "Title",
    "cover": {
        "kind": "IMAGE",
        "url": {
            "original": "https://...."
        }
    }
}

It's possible to populate nested fields by using dot-syntax such as cover.url.original (see example).

Populating multiple nested fields (curly-bracket-syntax)

?fields=id,title,cover.{url.original,kind,fileName} will return the following JSON structure:

{
    "id": "abc",
    "title": "Title",
    "cover": {
        "kind": "IMAGE",
        "fileName": "my-file.jpg",
        "url": {
            "original": "https://...."
        }
    }
}

In order to more easily populate multiple fields on nested entities it's possible to populate by combining multiple nested fields such as cover.{url.original, kind, fileName} (see example).

Ordering

You can order entities by choosing a field on the model to order by

Ordering by property with implicit ascending order

?orderBy=firstName will return the following JSON structure:

[{ "firstName": "A" }, { "firstName": "B" }, { "firstName": "C" }]

It is possible to order by any property of a model such as createdAt, title, id, etc, simply by providing the name of that property to the orderBy query parameter. Doing so will order the entries in an ascending order (see example)

Ordering by property with explicit ascending order

?orderBy={"key": "firstName", "direction": "DESC"} will return the following JSON structure:

[{ "firstName": "C" }, { "firstName": "B" }, { "firstName": "A" }]

Providing a JSON structure with a key and direction property such as {"key": "createdAt", "direction": "DESC"} gives you maximum control of ordering.

• key: The property to order by. Examples: createdAt, title, id.
• direction: The order to sort the entries. Can be:
  
  
  • DESC: Entries will be ordered in descending order.
  • ASC: Entries will be ordered in ascending order.

Filters

It is possible to build and combine filters to narrow down the received content.

Simple filtering with implicit EQUALS operator

The following filter will select entities for which the title property matches the value "How might we improve our products" exactly:

?filter={"title":"How might we improve our products"}

Simple filtering with explicit operator

The following filter will select entities for which the title property includes the substring "How might we".

?filter={"title":{"op": "INCLUDES", "value": "How might we"}}

Here is a list of all available operators:

Grouped filtering

The following filter selects entities created after 2020-01-01 OR entities for which the id property is either "6b8e6531-cf07-4d1f-be39-68ea22d88c0e" or "99e5d8b8-c477-4ce9-812e-9822d18adb99" by combining two filters separated by an OR operator.

?filter={ "op":"or", "filter":[ { "createdAt": {"op":"GREATER_THAN_OR_EQUALS","value":"2020-01-01T00:00:00.000Z"} }, { "id": { "op":"IN", "value":[ "6b8e6531-cf07-4d1f-be39-68ea22d88c0e", "99e5d8b8-c477-4ce9-812e-9822d18adb99" ] } } ] }

Combined, deep filtering

The following filter combines an outer AND with an inner OR. It selects entities for which the question includes "How might we", AND (either the status is "OPEN" OR the title is "My Mission")

?filter={"op":"and","filter":[{"question":{ "op":"INCLUDES","value":"How might we"}},{"op":"or","filter":[{"status":"OPEN" },{"title":"My Mission"}]}]}