Read AGT¶
Prerequisite to test following examples is to have an API key with permissions:
| Path | Methods | ACL |
|---|---|---|
| /aggregates/core\.aggregate | POST | off |
| /resources/product | POST | off |
| /aggregates/agt\.product-group | GET | off |
| /aggregates/agt\.product-group/relationships/flat-products | GET | off |
| /aggregates/agt\.product-group/flat-products | GET | off |
| /aggregates/agt\.flat-product | GET | off |
| /aggregates/agt\.flat-product/[0-9a-fA-F]{24}-[0-9]+/relationships/product | GET | off |
| /aggregates/agt\.flat-product/[0-9a-fA-F]{24}-[0-9]+/product | GET | off |
Read AGT documention is explained using a test model created by the following requests:
Create agt.flat-product aggregate using API request:
curl -H 'Content-Type: application/vnd.api+json' \
-H 'Accept: application/vnd.api+json' \
-H 'api-key: <YOUR_API_KEY_SECURE_ID>' \
-H 'application-id: <YOUR_APPLICATION_ID>' \
-d '
{
"data": {
"type": "core.aggregate",
"attributes": {
"input-type": "product",
"output-type": "agt.flat-product",
"pipeline": [{
"unwind": {
"path": "$models",
"includeArrayIndex": "unwindIndex"
}
}, {
"project": {
"id": { "$concat": [ { "$toString": "$id" }, "-", { "$toString": "$unwindIndex" } ] },
"subtype": "$subtype",
"name": "$name",
"model": "$models",
"product": { "type": "product", "id": "$id" }
}
}, {
"output": {
"attributes": [ "subtype", "name", "model" ],
"relationships": [ "product" ]
}
}]
}
}
}' \
-X POST https://api.jazer.io/aggregates/core.aggregate
Create agt.product-group aggregate using API request:
curl -H 'Content-Type: application/vnd.api+json' \
-H 'Accept: application/vnd.api+json' \
-H 'api-key: <YOUR_API_KEY_SECURE_ID>' \
-H 'application-id: <YOUR_APPLICATION_ID>' \
-d '
{
"data": {
"type": "core.aggregate",
"attributes": {
"input-type": "product",
"output-type": "agt.product-group",
"pipeline": [{
"unwind": {
"path": "$models",
"includeArrayIndex": "unwindIndex"
}
}, {
"group": {
"id": "$id",
"flat-products": {
"$push": {
"type": "agt.flat-product",
"id": { "$concat": [ { "$toString": "$id" }, "-", { "$toString": "$unwindIndex" } ] }
}
}
}
}, {
"output": {
"attributes": [],
"relationships": [ "flat-products" ]
}
}]
}
}
}' \
-X POST https://api.jazer.io/aggregates/core.aggregate
Create a product document using API request:
curl -H 'Content-Type: application/vnd.api+json' \
-H 'Accept: application/vnd.api+json' \
-H 'api-key: <YOUR_API_KEY_SECURE_ID>' \
-H 'application-id: <YOUR_APPLICATION_ID>' \
-d '
{
"data": {
"type": "product",
"attributes": {
"subtype": "shirt",
"name": "Vintage 1",
"models": [{
"color": "red",
"price": 100.0
}, {
"color": "blue",
"price": 200.0
}, {
"color": "green",
"price": 300.0
}]
}
}
}' \
-X POST https://api.jazer.io/resources/product
Document¶
Single AGT document is available at endpoint: /aggregates/<AGT_TYPE>/<AGT_DOCUMENT_ID>.
Test model contains agt.flat-product documents where its ID is composed of a product ID and a model index. To fetch AGT document of type agt.flat-product using a product ID and model index, following API request can be used:
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.flat-product/<AGT_DOCUMENT_ID>
For example created product ID is 5bae7a94a01c5b129d3a3e3e and wanted model index is 1. AGT document ID is then 5bae7a94a01c5b129d3a3e3e-1. The response for mentioned AGT document ID will be:
{
"data": {
"type": "agt.flat-product",
"id": "5bae7a94a01c5b129d3a3e3e-1",
"attributes": {
"subtype": "shirt",
"name": "Vintage 1",
"model": {
"color": "blue",
"price": 200
}
},
"relationships": {
"product": {
"data": {
"type": "product",
"id": "5bae7a94a01c5b129d3a3e3e"
},
"links": {
"self": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-1/relationships/product",
"related": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-1/product"
}
}
},
"links": {
"self": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-1"
}
}
}
Document fields¶
An AGT document does not have to be returned will all fields. The client is able to instruct the system which document fields are returned and which to omit.
Query parameter fields supports AGT document field customization. The syntax is: fields[<AGT_TYPE>]=<FIELD_NAMES>, where FIELD_NAMES is a comma-separated list of field names.
Example agt.flat-product document is:
{
"data": {
"type": "agt.flat-product",
"id": "5bae7a94a01c5b129d3a3e3e-1",
"attributes": {
"subtype": "shirt",
"name": "Vintage 1",
"model": {
"color": "blue",
"price": 200
}
},
"relationships": {
"product": {
"data": {
"type": "product",
"id": "5bae7a94a01c5b129d3a3e3e"
},
"links": {
"self": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-1/relationships/product",
"related": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-1/product"
}
}
},
"links": {
"self": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-1"
}
}
}
Fetching agt.flat-product document with only fields name and model can be accomplished using fields[agt.flat-product]=name,model. Complete API request is:
curl --globoff -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.flat-product/<AGT_DOCUMENT_ID>?fields[agt.flat-product]=name,model
The response contains agt.flat-product document with omitted attribute subtype and relationship product:
{
"data": {
"type": "agt.flat-product",
"id": "5bae7a94a01c5b129d3a3e3e-1",
"attributes": {
"name": "Vintage 1",
"model": {
"color": "blue",
"price": 200
}
},
"links": {
"self": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-1"
}
}
}
Document inclusion¶
An AGT document can have related documents using relationships. The client is able to instruct the system to include related documents in the response. Query parameter include supports document inclusion. The syntax is: include=<RELATIONSHIP_PATHS>, where RELATIONSHIP_PATHS is a comma-separated list of relationship paths.
To-one relationship inclusion¶
Example agt.flat-product document contains a to-one relationship product:
{
"data": {
"type": "agt.flat-product",
"id": "5bae7a94a01c5b129d3a3e3e-1",
"attributes": {
"subtype": "shirt",
"name": "Vintage 1",
"model": {
"color": "blue",
"price": 200
}
},
"relationships": {
"product": {
"data": {
"type": "product",
"id": "5bae7a94a01c5b129d3a3e3e"
},
"links": {
"self": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-1/relationships/product",
"related": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-1/product"
}
}
},
"links": {
"self": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-1"
}
}
}
The following request will instruct the system to include document referenced in relationship product alongside primary agt.flat-product document:
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.flat-product/<AGT_DOCUMENT_ID>?include=product
The response for ID 5bae7a94a01c5b129d3a3e3e-1 is:
{
"data": {
"type": "agt.flat-product",
"id": "5bae7a94a01c5b129d3a3e3e-1",
"attributes": {
"subtype": "shirt",
"name": "Vintage 1",
"model": {
"color": "blue",
"price": 200
}
},
"relationships": {
"product": {
"data": {
"type": "product",
"id": "5bae7a94a01c5b129d3a3e3e"
},
"links": {
"self": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-1/relationships/product",
"related": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-1/product"
}
}
},
"links": {
"self": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-1"
}
},
"included": [
{
"type": "product",
"id": "5bae7a94a01c5b129d3a3e3e",
"attributes": {
"subtype": "shirt",
"name": "Vintage 1",
"models": [{
"color": "red",
"price": 100
}, {
"color": "blue",
"price": 200
}, {
"color": "green",
"price": 300
}]
},
"links": {
"self": "https://api.jazer.io/resources/product/5bae7a94a01c5b129d3a3e3e"
}
}
]
}
To-many relationship inclusion¶
Example agt.product-group document contains a to-many relationship flat-products:
{
"data": {
"type": "agt.product-group",
"id": "5bae7a94a01c5b129d3a3e3e",
"relationships": {
"flat-products": {
"data": [{
"type": "agt.flat-product",
"id": "5bae7a94a01c5b129d3a3e3e-0"
}, {
"type": "agt.flat-product",
"id": "5bae7a94a01c5b129d3a3e3e-1"
}, {
"type": "agt.flat-product",
"id": "5bae7a94a01c5b129d3a3e3e-2"
}],
"links": {
"self": "https://api.jazer.io/aggregates/agt.product-group/5bae7a94a01c5b129d3a3e3e/relationships/flat-products",
"related": "https://api.jazer.io/aggregates/agt.product-group/5bae7a94a01c5b129d3a3e3e/flat-products"
}
}
},
"links": {
"self": "https://api.jazer.io/aggregates/agt.product-group/5bae7a94a01c5b129d3a3e3e"
}
}
}
The following request will instruct the system to include all documents referenced in relationship flat-products alongside primary agt.product-group document:
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.product-group/<AGT_DOCUMENT_ID>?include=flat-products
The response for ID 5bae7a94a01c5b129d3a3e3e is:
{
"data": {
"type": "agt.product-group",
"id": "5bae7a94a01c5b129d3a3e3e",
"relationships": {
"flat-products": {
"data": [{
"type": "agt.flat-product",
"id": "5bae7a94a01c5b129d3a3e3e-0"
}, {
"type": "agt.flat-product",
"id": "5bae7a94a01c5b129d3a3e3e-1"
}, {
"type": "agt.flat-product",
"id": "5bae7a94a01c5b129d3a3e3e-2"
}],
"links": {
"self": "https://api.jazer.io/aggregates/agt.product-group/5bae7a94a01c5b129d3a3e3e/relationships/flat-products",
"related": "https://api.jazer.io/aggregates/agt.product-group/5bae7a94a01c5b129d3a3e3e/flat-products"
}
}
},
"links": {
"self": "https://api.jazer.io/aggregates/agt.product-group/5bae7a94a01c5b129d3a3e3e"
}
},
"included": [
{
"type": "agt.flat-product",
"id": "5bae7a94a01c5b129d3a3e3e-0",
"attributes": {
"subtype": "shirt",
"name": "Vintage 1",
"model": {
"color": "red",
"price": 100
}
},
"relationships": {
"product": {
"data": {
"type": "product",
"id": "5bae7a94a01c5b129d3a3e3e"
},
"links": {
"self": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-0/relationships/product",
"related": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-0/product"
}
}
},
"links": {
"self": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-0"
}
},
{
"type": "agt.flat-product",
"id": "5bae7a94a01c5b129d3a3e3e-1",
"attributes": {
"subtype": "shirt",
"name": "Vintage 1",
"model": {
"color": "blue",
"price": 200
}
},
"relationships": {
"product": {
"data": {
"type": "product",
"id": "5bae7a94a01c5b129d3a3e3e"
},
"links": {
"self": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-1/relationships/product",
"related": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-1/product"
}
}
},
"links": {
"self": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-1"
}
},
{
"type": "agt.flat-product",
"id": "5bae7a94a01c5b129d3a3e3e-2",
"attributes": {
"subtype": "shirt",
"name": "Vintage 1",
"model": {
"color": "green",
"price": 300
}
},
"relationships": {
"product": {
"data": {
"type": "product",
"id": "5bae7a94a01c5b129d3a3e3e"
},
"links": {
"self": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-2/relationships/product",
"related": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-2/product"
}
}
},
"links": {
"self": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-2"
}
}
]
}
Deeply nested relationship inclusion¶
Example agt.product-group document contains a to-many relationship flat-products which contains references to agt.flat-product documents. Each agt.flat-document document contains a to-one relationship product which points to a document of type product.
To fetch agt.product-group document with included related documents under relationship flat-products and of those documents related document under relationship product, following API request can be used:
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.product-group/<AGT_DOCUMENT_ID>?include=flat-products.product
The response for ID 5bae7a94a01c5b129d3a3e3e is:
{
"data": {
"type": "agt.product-group",
"id": "5bae7a94a01c5b129d3a3e3e",
"relationships": {
"flat-products": {
"data": [{
"type": "agt.flat-product",
"id": "5bae7a94a01c5b129d3a3e3e-0"
}, {
"type": "agt.flat-product",
"id": "5bae7a94a01c5b129d3a3e3e-1"
}, {
"type": "agt.flat-product",
"id": "5bae7a94a01c5b129d3a3e3e-2"
}],
"links": {
"self": "https://api.jazer.io/aggregates/agt.product-group/5bae7a94a01c5b129d3a3e3e/relationships/flat-products",
"related": "https://api.jazer.io/aggregates/agt.product-group/5bae7a94a01c5b129d3a3e3e/flat-products"
}
}
},
"links": {
"self": "https://api.jazer.io/aggregates/agt.product-group/5bae7a94a01c5b129d3a3e3e"
}
},
"included": [
{
"type": "product",
"id": "5bae7a94a01c5b129d3a3e3e",
"attributes": {
"subtype": "shirt",
"name": "Vintage 1",
"models": [{
"color": "red",
"price": 100
}, {
"color": "blue",
"price": 200
}, {
"color": "green",
"price": 300
}]
},
"links": {
"self": "https://api.jazer.io/resources/product/5bae7a94a01c5b129d3a3e3e"
}
},
{
"type": "agt.flat-product",
"id": "5bae7a94a01c5b129d3a3e3e-0",
"attributes": {
"subtype": "shirt",
"name": "Vintage 1",
"model": {
"color": "red",
"price": 100
}
},
"relationships": {
"product": {
"data": {
"type": "product",
"id": "5bae7a94a01c5b129d3a3e3e"
},
"links": {
"self": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-0/relationships/product",
"related": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-0/product"
}
}
},
"links": {
"self": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-0"
}
},
{
"type": "agt.flat-product",
"id": "5bae7a94a01c5b129d3a3e3e-1",
"attributes": {
"subtype": "shirt",
"name": "Vintage 1",
"model": {
"color": "blue",
"price": 200
}
},
"relationships": {
"product": {
"data": {
"type": "product",
"id": "5bae7a94a01c5b129d3a3e3e"
},
"links": {
"self": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-1/relationships/product",
"related": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-1/product"
}
}
},
"links": {
"self": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-1"
}
},
{
"type": "agt.flat-product",
"id": "5bae7a94a01c5b129d3a3e3e-2",
"attributes": {
"subtype": "shirt",
"name": "Vintage 1",
"model": {
"color": "green",
"price": 300
}
},
"relationships": {
"product": {
"data": {
"type": "product",
"id": "5bae7a94a01c5b129d3a3e3e"
},
"links": {
"self": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-2/relationships/product",
"related": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-2/product"
}
}
},
"links": {
"self": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-2"
}
}
]
}
Inclusion security¶
The system will not include a document for which client does not have permission to access. API key must have permission path which matches document endpoint with allowed GET method.
A document with relationship with type agt.flat-product and ID 5bae7a94a01c5b129d3a3e3e-1 requires API key to have a path like /aggregates/agt\.flat-product/[0-9a-fA-F]{24}-[0-9]+ and allowed GET method. Basically, if the client can read the document by ID then it can be included.
Document relationships¶
An AGT document relationship has a unique endpoint which can be used to directly read its value. The endpoint path is a document path appended with /relationships/<RELATIONSHIP_NAME>. The endpoint provides only links to related documents. There is an additional relationship endpoint which provides related documents linked by relationship. Its endpoint is an AGT document path appended with /<RELATIONSHIP_NAME>.
Example API request fetching relationship flat-products:
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.product-group/<AGT_DOCUMENT_ID>/relationships/flat-products
Response contains relationship value:
{
"data": [
{
"type": "agt.flat-product",
"id": "5bae7a94a01c5b129d3a3e3e-0"
},
{
"type": "agt.flat-product",
"id": "5bae7a94a01c5b129d3a3e3e-1"
},
{
"type": "agt.flat-product",
"id": "5bae7a94a01c5b129d3a3e3e-2"
}
],
"links": {
"self": "https://api.jazer.io/aggregates/agt.product-group/5bae7a94a01c5b129d3a3e3e/relationships/flat-products",
"related": "https://api.jazer.io/aggregates/agt.product-group/5bae7a94a01c5b129d3a3e3e/flat-products"
}
}
Example API request fetching relationship flat-products linked documents:
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.product-group/<AGT_DOCUMENT_ID>/flat-products
Response contains linked documents:
{
"data": [
{
"type": "agt.flat-product",
"id": "5bae7a94a01c5b129d3a3e3e-0",
"attributes": {
"subtype": "shirt",
"name": "Vintage 1",
"model": {
"color": "red",
"price": 100
}
},
"relationships": {
"product": {
"data": {
"type": "product",
"id": "5bae7a94a01c5b129d3a3e3e"
},
"links": {
"self": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-0/relationships/product",
"related": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-0/product"
}
}
},
"links": {
"self": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-0"
}
},
{
"type": "agt.flat-product",
"id": "5bae7a94a01c5b129d3a3e3e-1",
"attributes": {
"subtype": "shirt",
"name": "Vintage 1",
"model": {
"color": "blue",
"price": 200
}
},
"relationships": {
"product": {
"data": {
"type": "product",
"id": "5bae7a94a01c5b129d3a3e3e"
},
"links": {
"self": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-1/relationships/product",
"related": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-1/product"
}
}
},
"links": {
"self": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-1"
}
},
{
"type": "agt.flat-product",
"id": "5bae7a94a01c5b129d3a3e3e-2",
"attributes": {
"subtype": "shirt",
"name": "Vintage 1",
"model": {
"color": "green",
"price": 300
}
},
"relationships": {
"product": {
"data": {
"type": "product",
"id": "5bae7a94a01c5b129d3a3e3e"
},
"links": {
"self": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-2/relationships/product",
"related": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-2/product"
}
}
},
"links": {
"self": "https://api.jazer.io/aggregates/agt.flat-product/5bae7a94a01c5b129d3a3e3e-2"
}
}
]
}
Conditional get¶
Successful read API request will return a response with the ETag header. Repeating the same request with an additional header If-None-Match with the value of an ETag value from previous response can have two outcomes. The server can return 200 OK with the body if the primary document or any of the included documents have changed or 304 Not Modified without a body when there have been no changes to the documents since last request, i.e. the given ETag is still valid.
Example API request fetches document of type agt.flat-product:
curl -i -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.flat-product/<AGT_PRODUCT_ID>
The response will be 200 OK with the body containing agt.flat-product document. Response headers will contain an ETag. Repeating the same API request with an additional header If-None-Match with the value of ETag returned from this response like:
curl -i -H 'Accept: application/vnd.api+json' \
-H 'api-key: <YOUR_API_KEY_SECURE_ID>' \
-H 'application-id: <YOUR_APPLICATION_ID>' \
-H 'If-None-Match: <ETAG_VALUE>' \
-X GET https://api.jazer.io/aggregates/agt.flat-product/<AGT_PRODUCT_ID>
The response will be 304 Not Modified if in the meantime agt.flat-product document with the given ID has not been modified or removed.
Note
Web browsers support such local caching automatically.
Visit Security to find out security surrounding aggregation collections.