Some endpoints are designed to support searching by using request query and body together. When these endpoints also require using JSON-LD data format (or values), we are talking about JSON-LD search endpoints.
They can be requested with GET and POST methods:
●GET https://{domain}/{platform}/orders/v1/orders/
●POST https://{domain}/{platform}/orders/v1/orders/_search
Their interfaces are based on the following rules:
●Service-related query parameters have names consistent with the context used by the service when compacting request data and its response.
●Other specific query parameters are also supported. For example, parameters like range, sort, marker, paginationDirection, afterUpdateId, and others with specific meaning.
●The request payload (body) must always be a valid object in JSON-LD data format.
By default, such endpoints merge the query parameters with the object received in the payload to create the resulting JSON-LD search object.
Merge the request query with the body. The body has a bigger priority!
1.First retrieve from the query parameters, i.e., the query string
2.Then from jsonLdQuery, i.e., the body
If a parameter exists both in the query and the body, the body value is used.
Example:
Below you will find examples of the main usage cases of JSON-LD search endpoints.
For example, a service has the following output context:
{ "sc": "https://schema.org/", "seller": { "@id": "sc:seller", "@type": "@id" }, "orderStatus": { "@id": "sc:orderStatus", "@type": "@id" } } |
Merging query parameters with payload
When the service merges the query parameters with the payload, we can send the following request:
POST https://{domain}/{platform}/orders/v1/orders/_search?seller=JoeBlack&orderStatus=sc:OrderProcessing&range=10 { "@context": { "sc": "https://schema.org/", "exmp": "http://example.com/", "orderSeller": { "@id": "sc:seller", "@type": "@id" } }, "orderSeller": "exmp:seller/JohnDoe" } |
The service will see the following parameters:
1.seller = http://example.com/seller/JohnDoe
●value comes from payload (body have bigger priority) - value from query parameter is ignored
●value was compacted to persistence context, so 'exmp:' prefix is expanded
2.orderStatus = sc:OrderProcessing
●value comes from query parameters as it matches persistence context
3.range = 10
●specific query parameter
