Security

Aggregate collections contain AGT (non-persisted) documents which do not have ACL records. Setting API key on an aggregate collection endpoint to use ACL security will result in respecting ACL records of input-type collection documents. Dedicated input-type endpoint can have different ACL security from one used by aggregate collections. Following example illustrates this nature.

Example:

An e-commerce application contains shopping-cart collection where client API key contains permission for shopping-cart documents with ACL turned on. A user needs to have explicit rights on shopping-cart document to fetch it or to modify it. One user can not see shopping cart of another. This is fine in terms of privacy. However, application would like to be able to fetch for each product how many shopping carts contain it. Only user who is owner of shopping-cart is able to fetch it, but any user is able to fetch aggregated data based on all shopping-cart documents when aggregation endpoint has ACL turned off.

Collection product contains:

{
  "data": [
    {
      "type": "product",
      "id": "5c40d8e3c967fe2f89e6dcb3",
      "attributes": {
        "title": "KTM Super Duke 1290R"
      }
    }, {
      "type": "product",
      "id": "5c40d8dbe07902e0029a1076",
      "attributes": {
        "title": "Ducati Monster 1200"
      }
    }
  ]
}

Collection shopping-cart contains:

{
  "data": [
    {
      "type": "shopping-cart",
      "id": "5c40d9831e4191e15f86039f",
      "attributes": {
        "items": [
          {
            "product-id": "5c40d8e3c967fe2f89e6dcb3",
            "quantity": 1
          },
          {
            "product-id": "5c40d8dbe07902e0029a1076",
            "quantity": 1
          }
        ]
      },
      "relationships": {
        "products": {
          "data": [
            { "type": "product", "id": "5c40d8e3c967fe2f89e6dcb3" },
            { "type": "product", "id": "5c40d8dbe07902e0029a1076" },
          ]
        }
      }
    },
    {
      "type": "shopping-cart",
      "id": "5c40d99851fe1cabd5f21ff4",
      "attributes": {
        "items": [
          {
            "product-id": "5c40d8e3c967fe2f89e6dcb3",
            "quantity": 1
          }
        ]
      },
      "relationships": {
        "products": {
          "data": [
            { "type": "product", "id": "5c40d8e3c967fe2f89e6dcb3" }
          ]
        }
      }
    }
  ]
}

Client API key permissions:

Path	Methods	ACL
/resources/product	GET	off
/resources/product/[0-9a-fA-F]{24}	GET	off
/resources/shopping-cart	GET	on
/resources/shopping-cart/[0-9a-fA-F]{24}	GET, PATCH	on
/aggregates/agt\.shopping-cart-product	GET	off
/aggregates/agt\.shopping-cart-product/[0-9a-fA-F]{24}	GET	off

An aggregation pipeline unwinding products from all shopping carts and counting them based on product ID:

[
  {
    "unwind": "$products"
  },
  {
    "group": {
      "id": "$products.id",
      "count": { "$sum": 1 }
    }
  }
]

Number of shopping carts containing product with ID 5c40d8e3c967fe2f89e6dcb3 can be found out using following API request:

curl -H 'Accept: application/vnd.api+json' \
-H 'api-key: <YOUR_API_KEY_SECURE_ID>' \
-H 'application-id: <YOUR_APPLICATION_ID>' \
-X GET https://api.jazer.io/aggregates/agt.shopping-cart-product/5c40d8e3c967fe2f89e6dcb3

Response is:

{
  "data": {
    "type": "agt.shopping-cart-product",
    "id": "5c40d8e3c967fe2f89e6dcb3",
    "attributes": {
      "count": 2
    }
  }
}

Note

Example API key permissions for endpoint agt.shopping-cart-product have ACL turned off. Turning it on will restrict aggregation pipeline to only reach shopping-cart documents for which user has explicit read rights. Since user has most likely one shopping cart, only it will be examined.