Decks ๐Ÿ”—

Decks allow you to store analyses for future reference or for export. Decks correspond to a single dataset, and they are personal to each user unless they have been set as โ€œpublicโ€. Each deck contains a list of slides, and each slide contains analyses.

Catalog ๐Ÿ”—

/datasets/{id}/decks/

GET ๐Ÿ”—

A GET request on the catalog endpoint will return all the decks available for this dataset for the current user. This includes decks created by the user, as well as public decks shared with all users of the dataset.

{
    "element": "shoji:catalog",
    "self": "https://app.crunch.io/api/datasets/223fd4/decks/",
    "index": {
        "https://app.crunch.io/api/datasets/cc9161/decks/4fa25/": {
          "name": "my new deck",
          "creation_time": "1986-11-26T12:05:00",
          "id": "4fa25",
          "is_public": false,
          "owner_id": "https://app.crunch.io/api/users/abcd3/",
          "owner_name": "Real Person",
          "team": null
        },
        "https://app.crunch.io/api/datasets/cc9161/decks/2b53e/": {
          "name": "Default deck",
          "creation_time": "1987-10-15T11:45:00",
          "id": "2b53e",
          "is_public": true,
          "owner_id": "https://app.crunch.io/api/users/4cba5/",
          "owner_name": "Other Person",
          "team": "https://app.crunch.io/api/teams/58acf7/"
        }
    },
    "order": "https://app.crunch.io/api/datasets/223fd4/decks/order/"
}

The decks catalog tuples contain the following keys:

Name Type Description
name string Human-friendly string identifier
creation_time timestamp Time when this deck was created
id string Global unique identifier for this deck
is_public boolean Indicates whether this is a public deck or not
owner_id url Points to the owner of this deck
owner_name string Name of the owner of the deck (referred by owner_id)
team url If the deck is shared through a team, it will point to it. null by default

To determine if a deck belongs to the current user, check the owner_id attribute.

POST ๐Ÿ”—

POST a shoji:entity to create a new deck for this dataset. The only required body attribute is โ€œnameโ€; other attributes are optional.

{
    "element": "shoji:entity",
    "self": "https://app.crunch.io/api/datasets/223fd4/decks/",
    "body": {
        "name": "my new deck",
        "description": "This deck will contain analyses for a variable",
        "is_public": false,
        "team": "https://app.crunch.io/api/teams/58acf7/"
    }
}
HTTP/1.1 201 Created
Location: https://app.crunch.io/api/datasets/223fd4/decks/2b3c5e/

The shoji:entity POSTed accepts the following keys

Name Type required
name string Yes
description string No
is_public boolean No
team url No

PATCH ๐Ÿ”—

It is possible to bulk-edit many decks at once by PATCHing a shoji:catalog to the decksโ€™ catalog.

{
    "element": "shoji:catalog",
    "index": {
        "https://app.crunch.io/api/datasets/cc9161/decks/4fa25/": {
          "name": "Renamed deck",
          "is_public": true
        }
    },
    "order": "https://app.crunch.io/api/datasets/223fd4/decks/order/"
}

The following attributes are editable via PATCHing this resource:

  • name
  • description
  • is_public

For decks that the current user owns, โ€œnameโ€, โ€œdescriptionโ€ and โ€œis_publicโ€ are editable. Only the deck owner can edit the mentioned attributes on a deck even if the deck is public. Other deck attributes are not editable and will respond with 400 status if the request tries to change them.

On success, the server will reply with a 204 response.

Entity ๐Ÿ”—

/datasets/{id}/decks/{id}/

GET ๐Ÿ”—

GET a deck entity resource to return a shoji:entity with all of its attributes:

{
    "element": "shoji:entity",
    "self": "https://app.crunch.io/api/datasets/223fd4/decks/223fd4/",
    "body": {
        "name": "Presentation deck",
        "id": "223fd4",
        "creation_time": "1987-10-15T11:45:00",
        "description": "Explanation about the deck",
        "is_public": false,
        "owner_id": "https://app.crunch.io/api/users/abcd3/",
        "owner_name": "Real Person",
        "team": "https://app.crunch.io/api/teams/58acf7/"
    }
}
Name Type Description
name string Human-friendly string identifier
id string Global unique identifier for this deck
creation_time timestamp Time when this deck was created
description string Longer annotations for this deck
is_public boolean Indicates whether this is a public deck or not
owner_id url Points to the owner of this deck
owner_name string Name of the owner of the deck (referred by owner_id)
team url If the deck is shared through a team, it will point to it. null by default

PATCH ๐Ÿ”—

To edit a deck, PATCH it with a shoji:entity. The server will return a 204 response on success or 400 if the request is invalid.

{
    "element": "shoji:entity",
    "self": "https://app.crunch.io/api/datasets/223fd4/decks/223fd4/",
    "body": {
        "name": "Presentation deck",
        "id": "223fd4",
        "creation_time": "1987-10-15T11:45:00",
        "description": "Explanation about the deck",
        "team": "https://app.crunch.io/api/teams/58acf7/"
    },
    "catalogs": {
        "slides": "https://app.crunch.io/api/datasets/223fd4/decks/223fd4/slides/"
    },
    "urls": {
        "xlsx_export_url": "https://app.crunch.io/api/datasets/223fd4/decks/223fd4/export_xlsx/",
        "export_url": "https://app.crunch.io/api/datasets/223fd4/decks/223fd4/export/"
    }
}
HTTP/1.1 204 No Content

For deck entities that the current user owns, โ€œnameโ€, โ€œdescriptionโ€, โ€œteamsโ€ and โ€œis_publicโ€ are editable. Other deck attributes are not editable.

DELETE ๐Ÿ”—

To delete a deck, DELETE the deckโ€™s entity URL. On success, the server returns a 204 response.

Deck Exports ๐Ÿ”—

xlsx ๐Ÿ”—

A successful POST request to /datasets/{dataset_id}/decks/{deck_id}/export/ will generate a download location to which the exporter will write this file when it is done computing (it may take some time for large datasets). The server will return a 202 response indicating that the export job started with a Location header indicating where the final exported file will be available. The responseโ€™s body will contain the URL for the progress URL where to query the state of the export job. Clients should note the download URL, monitor progress, and when complete, GET the download location. See Progress for details. If no header is provided, this endpoint will produce an xlsx file.

Requesting the same job, if still in progress, will return the same 202 response indicating the original progress to check. If the export is finished, the server will 302 redirect to the destination for download.

If there have been changes on the dataset attributes, a new tab book will be generated regardless of the status of any other pending exports.

Note: You can provide an Accept: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet header to create an downloadable excel document. If no Accept header is provided, the default download will be xlsx.

json ๐Ÿ”—

This provides a json output for the analysis for each slide in the deck. Note that you _must_ provide an Accept: application/json header for this endpoint to work properly.

{
  "slides": [
    {
      "cube": {
        "query": {
          "measures": {
            "count": {
              "function": "cube_count",
              "args": []
            }
          },
          "dimensions": [
            {
              "function": "bin",
              "args": [
                {
                  "variable": "000001"
                }
              ]
            },
            {
              "variable": "000000"
            }
          ],
          "weight": null
        },
        "query_environment": {
          "filter": []
        },
        "result": {
          "dimensions": [
            {
              "references": {
                "alias": "Age",
                "description": null,
                "name": "Age"
              },
              "derived": true,
              "type": {
                "subtype": {
                  "missing_rules": {},
                  "class": "numeric",
                  "missing_reasons": {
                    "No Data": -1
                  }
                },
                "elements": [
                  {
                    "id": 1,
                    "value": [10.0, 20.0],
                    "missing": false
                  },
                  {
                    "id": 2,
                    "value": [20.0, 30.0],
                    "missing": false
                  },
                  {
                    "id": 3,
                    "value": [30.0, 40.0],
                    "missing": false
                  },
                  {
                    "id": 4,
                    "value": [40.0, 50.0],
                    "missing": false
                  }
                ],
                "class": "enum"
              }
            },
            {
              "references": {
                "alias": "Gender",
                "description": null,
                "name": "Gender"
              },
              "derived": false,
              "type": {
                "ordinal": false,
                "class": "categorical",
                "categories": [
                  {
                    "numeric_value": null,
                    "id": 2,
                    "name": "F",
                    "missing": false
                  },
                  {
                    "numeric_value": null,
                    "id": 1,
                    "name": "M",
                    "missing": false
                  }
                ]
              }
            }
          ],
          "missing": 0,
          "measures": {
            "count": {
              "data": [1, 3, 0, 0, 1, 0, 1, 1],
              "n_missing": 0,
              "metadata": {
                "references": {},
                "derived": true,
                "type": {
                  "integer": true,
                  "missing_rules": {},
                  "class": "numeric",
                  "missing_reasons": {
                    "No Data": -1
                  }
                }
              }
            }
          },
          "n": 7,
          "counts": [1, 3, 0, 0, 1, 0, 1, 1],
          "element": "crunch:cube"
        }
      },
      "meta": {
        "table_title": "",
        "name": "Slide #1 ",
        "weight": null,
        "title": "Slide #1",
        "filters": [],
        "subtitle": "",
        "display_settings": {
          "decimalPlaces": {
            "value": 2
          }
        }
      }
    }
  ],
  "dataset": {
    "notes": "",
    "name": "New dataset"
  }
}

Note that the export_xlsx endpoint is deprecated, no longer supported in favor of /export and will be removed shortly.

Order ๐Ÿ”—

/datasets/{id}/decks/order/

The deck order resource allows the user to arrange how API clients, such as the web application, will present the deck catalog. The deck order contains all decks that are visible to the current user, both personal and public. Unlike many other shoji:order resources, this order does not allow grouping or nesting: it will always be a flat list of slide URLs.

GET ๐Ÿ”—

Returns a Shoji Order response.

{
  "element": "shoji:order",
  "self": "https://app.crunch.io/api/datasets/223fd4/decks/order/",
  "graph": [
    "https://app.crunch.io/api/datasets/223fd4/decks/1/",
    "https://app.crunch.io/api/datasets/223fd4/decks/2/",
    "https://app.crunch.io/api/datasets/223fd4/decks/3/"
  ]
}

PATCH ๐Ÿ”—

PATCH the order resource to change the order of the decks. A 204 response indicates success.

If the PATCH payload contains only a subset of available decks, those decks not referenced will be appended at the bottom of the top level graph in arbitrary order.

{
  "element": "shoji:order",
  "self": "https://app.crunch.io/api/datasets/223fd4/decks/order/",
  "graph": [
    "https://app.crunch.io/api/datasets/223fd4/decks/1/",
    "https://app.crunch.io/api/datasets/223fd4/decks/3/"
  ]
}

Including invalid URLs, such as URLs of decks that are not present in the catalog, will return a 400 response from the server.

The deck order should always be a flat list of URLs. Nesting or grouping is not supported by the web application. Server will return a 400 response if the order supplied in the PATCH request has nesting.

Slides ๐Ÿ”—

Each deck contains a catalog of slides into which analyses are saved.

Catalog ๐Ÿ”—

/datasets/{id}/decks/{deck_id}/slides/

GET ๐Ÿ”—

Returns a shoji:catalog with the slides for this deck.

{
    "element": "shoji:catalog",
    "self": "https://app.crunch.io/api/datasets/123/decks/123/slides/",
    "orders": {
        "flat": "https://app.crunch.io/api/datasets/123/decks/123/slides/flat/"
    },
    "specification": "https://app.crunch.io/api/specifications/slides/",
    "description": "A catalog of the Slides in this Deck",
    "index": {
        "https://app.crunch.io/api/datasets/123/decks/123/slides/123/": {
            "analysis_url": "https://app.crunch.io/api/datasets/123/decks/123/slides/123/analyses/123/",
            "subtitle": "z",
            "display": {
                "value": "table"
            },
            "title": "slide 1"
        },
        "https://app.crunch.io/api/datasets/123/decks/123/slides/456/": {
            "analysis_url": "https://app.crunch.io/api/datasets/123/decks/123/slides/456/",
            "subtitle": "",
            "display": {
                "value": "table"
            },
            "title": "slide 2"
        }
    }
}

Each tuple on the slides catalog contains the following keys:

Name Type Description
analysis_url url Points to the first (and typically only) analysis contained on this slide
title string Optional title for the slide
subtitle string Optional subtitle for the slide
display object Stores settings used to load the analysis

POST ๐Ÿ”—

To create a new slide, POST a slide body to the slides catalog. It is necessary to include at least one analysis on the new slide.

The body should contain an analyses attribute that contains an array with one or many analyses bodies as described in the below section, should be wrapped as a shoji:entity.

On success, the server returns a 201 response with a Location header containing the URL of the newly created slide entity with its first analysis.

{
  "title": "New slide",
  "subtitle": "Variable A and B",
  "analyses": [
    {
      "query": {},
      "query_environment": {},
      "display_settings": {}
    },
    {
      "query": {},
      "query_environment": {},
      "display_settings": {}
    }
  ]
}

On each analysis, only a query field is required to create a new slide; other attributes are optional.

Slide attributes:

Name Type Description
title string Optional title for the slide
subtitle string Optional subtitle for the slide

Analysis attributes:

Name Type Description
query object Contains a valid analysis query, required
subtitle string Optional subtitle for the slide
display_settings object Contains a set of attributes to be interpreted by the client to render and export the analysis
query_environment object Contains the weight and filter applied during the analysis, they will be applied upon future evaluation/render/export

Old format ๐Ÿ”—

It is possible to create slides with one single initial analysis by POSTing an analysis body directly to the slides catalog. It will create a slide automatically with the new analysis on it:

{
  "title": "New slide",
  "subtitle": "Variable A and B",
  "query": {},
  "query_environment": {},
  "display_settings": {}
}

PATCH ๐Ÿ”—

It is possible to bulk-edit several slides at once by PATCHing a shoji:catalog to this endpoint.

The only editable attributes with this method are:

  • title
  • subtitle

Other attributes should be considered read-only.

Submitting invalid attributes or references to other slides results in a 400 error response.

To edit the first or any of the slideโ€™s analyses query attributes it is necessary to PATCH the individual analysis entity.

Entity ๐Ÿ”—

/datasets/223fd4/decks/slides/a126ce/

Each slide in the Slide Catalog contains reference to its first analysis.

GET ๐Ÿ”—

{
    "element": "shoji:entity",
    "self": "/api/datasets/123/decks/123/slides/123/",
    "catalogs": {
        "analyses": "/api/datasets/123/decks/123/slides/123/analyses/"
    },
    "description": "Returns the detail information for a given slide",
    "body": {
        "deck_id": "123",
        "subtitle": "z",
        "title": "slide 1",
        "analysis_url": "/api/datasets/123/decks/123/slides/123/analyses/123/",
        "display": {
            "value": "table"
        },
        "id": "123"
    }
}

DELETE ๐Ÿ”—

Perform a DELETE request on the Slide entity resource to delete the slide and its analyses.

PATCH ๐Ÿ”—

It is possible to edit a slide entity by PATCHing with a shoji:entity.

The editable attributes are:

  • title
  • subtitle

The other attributes are considered read-only.

Order ๐Ÿ”—

/datasets/223fd4/decks/slides/flat/

The owner of the deck can specify the order of its slides. As with deck order, the slide order must be a flat list of slide URLs.

GET ๐Ÿ”—

Returns the list of all the slides in the deck.

{
    "element": "shoji:order",
    "self": "/api/datasets/123/decks/123/slides/flat/",
    "description": "Order of the slides on this deck",
    "graph": [
        "/api/datasets/123/decks/123/slides/123/",
        "/api/datasets/123/decks/123/slides/456/"
    ]
}

PATCH ๐Ÿ”—

To make changes to the order, a client should PATCH the full shoji:order resource to the endpoint with the new order on its graph attribute.

Any slide not mentioned on the payload will be added at the end of the graph in arbitrary order.

{
    "element": "shoji:order",
    "self": "/api/datasets/123/decks/123/slides/flat/",
    "description": "Order of the slides on this deck",
    "graph": [
        "/api/datasets/123/decks/123/slides/123/",
        "/api/datasets/123/decks/123/slides/456/"
    ]
}

This is a flat order: grouping or nesting is not allowed. PATCHing with a nested order will generate a 400 response.

Analysis ๐Ÿ”—

Each slide contains one or more analyses. An analysis โ€“ a table or graph with some specific combination of variables defining measures, rows, columns, and tabs; settings such as percentage direction and decimal places โ€“ can be saved to a deck, which can then be exported, or the analysis can be reloaded in whole in the application or even exported as a standalone embeddable result.

Catalog ๐Ÿ”—

/api/datasets/123/decks/123/slides/123/analyses/

POST ๐Ÿ”—

To create multiple analyses on a slide, clients should POST analyses to the slideโ€™s analyses catalog.

{
    "query": {
        "dimensions" : [],
        "measures": {}
    },
    "query_environment": {
        "filter": [
            {"filter": "<url>"},
            {"function": "expression", "args": [], "name": "(Optional)"}
        ],
        "weight": "url"
    },
    "display_settings": {
        "decimalPlaces": {
            "value": 0
        },
        "percentageDirection": {
            "value": "colPct"
        },
        "vizType": {
            "value": "table"
        },
        "countsOrPercents": {
            "value": "percent"
        },
        "uiView": {
            "value": "expanded"
        }
    }
}

The server will return a 201 response with the new slide created. In case of invalid analysis attributes, a 400 response will be returned indicating the problems.

PATCH ๐Ÿ”—

It is possible to delete many analyses at once from the catalog sending null as their tuple. It is not possible to delete all the analysis from a slide. For that it is necessary to delete the slide itself.

{
    "/api/datasets/123/decks/123/slides/123/analyses/1/": null,
    "/api/datasets/123/decks/123/slides/123/analyses/2/": {}
}

A 204 response will be returned on success.

Order ๐Ÿ”—

As analyses get added to a slide, they will be stored on a shoji:order resource.

Like other order resources, it will expose a graph attribute that contains the list of created analyses having new ones added at the end.

If an incomplete set of analyses is sent to the graph, the missing analyses will be added in arbitrary order.

This is a flat order and does not allow nesting.

Entity ๐Ÿ”—

An analysis is defined by a query, query environment, and display settings. To save an analysis, POST these to a deck as a new slide.

Display settings can be anything a client may need to reproduce the view of the data returned from the query. The settings the Crunch web client uses are shown here, but other clients are free to store other attributes as they see fit. Display settings should be objects with a value member.

{
    "query": {
        "dimensions" : [],
        "measures": {}
    },
    "query_environment": {
        "filter": [
            {"filter": "<url>"},
            {"function": "expression", "args": [], "name": "(Optional)"}
        ],
        "weight": "url"
    },
    "display_settings": {
        "decimalPlaces": {
            "value": 0
        },
        "percentageDirection": {
            "value": "colPct"
        },
        "vizType": {
            "value": "table"
        },
        "countsOrPercents": {
            "value": "percent"
        },
        "uiView": {
            "value": "expanded"
        }
    }
}
Name Description
query Includes the query body for this analysis
query_environment An object with a weight and filters to be used for rendering/evaluating this analysis
display_settings An object containing client-specific instructions on how to recreate the analysis

PATCH ๐Ÿ”—

To edit an analysis, PATCH its URL with a shoji:entity.

The editable attributes are:

  • query
  • query_environment
  • display_settings

Providing invalid values for those attributes or extra attributes will be rejected with a 400 response from the server.

DELETE ๐Ÿ”—

It is possible to delete analyses from a slide as long as there is always one analysis left.

Attempting to delete the last analysis of a slide will cause a 409 response from the server indicating the problem.