XY Retail API for Developers

Introduction

Deliver world-class omnichannel customer experiences through our API-driven retail infrastructure and world's largest retail graph.

Today’s brands face enormous challenges to differentiate and meet the ever-changing behaviors of their customers. Customers are more empowered than ever before; they are social, connected, well-informed, and they expect experiences that are no less than stellar. XY Retail helps to integrate all digital and physical customer touchpoints onto a single and robust platform including online, mobile, point-of-sale, call center, and social media. It empowers brands to deliver exceptional, seamless omnichannel customer experiences.

The XY platform was created to address the challenge of what it means to be truly omnichannel. The platform exists to answer questions such as:

How does a brand move from being store centric to omnichannel centric?

How does a brand manage a complete asymmetric customer experience, where today's systems are inherently built for single store experiences?

How does a brand manage sales attribution when a customer orders from one store and performs a return an exchange at another?

How does a brand extend it's retail to support new marketplaces and business models like subscriptions and rentals with minimal effort?

How does a brand extend into other geographies and countries and support cross border shipments and returns with third party integrations?

A 360-degree view and analysis of the customer at every touchpoint is a bare minimum requirement to provide a relevant and personalized omnichannel experience.

But wait, there is more! For the platform to be truly omni we had to make the following key decisions and distinctions:

A sales order line is the only construct that can support and pass the true omni smell test -where a customer can buy 5 items at Store A, carry out 3 items, ship the other 2 to two separate addresses. Then at a later date, return an item at Store B, and exchange an item at Store C - all in one order.

An order or a sales order line cannot be restricted to a particular channel as a foundational capability.

Every location is a Point Of Sale, whether it is a store POS, ecommerce website, warehouse, showroom, dropship location..

It was imperative to make a distinction between a 'Point Of Sale' and a 'Channel', where sales attribution is tracked and accounted for, and return or exchange flows could be processed beyond just the sale.

Given that integrating disparate systems would not provide a real-time 360-degree customer view and get us to omnichannel nirvana, we had to put our heads down and build a first of it's kind, vertically integrated, cloud-native platform for omnichannel retail from the very ground-up

API Reference

XY’s cloud-native omnichannel platform is bringing a connections-first approach to applications and analytics across the enterprise.

The graph helps you build, query, and manage a retail data: a unified data layer that enables applications to interact with data from any combination of connected data stores and external APIs.

An XY query retrieves data from the cloud, similar to a GET request for a REST API. However, unlike REST, all XY queries are sent to a single endpoint and use the POST http method.

An XY data graph uses XY Query Language 'XYQL' to define and enforce the structure of this data flow.

XY Graph

XY Graph is the gateway to data and intelligence in the XY Omnichannel Platform. It provides a unified programmability model that you can use to access the tremendous amount of data from internal and external apps. It's an HTTP-based API that apps can use to programmatically query data. Use the wealth of data in XY Graph to build apps for organizations and consumers that interact with millions of users.

XY Query: A query language for XY API Graph

1. /xy/query/{node uri of query}

This endpoint supports a wide range of queries, such as aggregates and a few more enhancements such as joins and variables are coming soon.
2. /xy/collection/{node uri of collection}

This endpoint supports the base level and filtered collections.
3. /xy/path/{expression}

This will allow you to express any path in the graph and it will return results. Coming Soon
4. /xy/search/(node uri of query)

This endpoint for now is practically the same as 1, except with controls to define search behaviour through configuration.
5. /xy/functions/{node uri of function}

This endpoint allows developers to either use GET for read only functions or POST for write functions (mutations).

XY Content: A lightweight but flexible CMS

1. /xy/query/{node uri of query}

This endpoint supports all forms of content.

A new basic CMS but with the idea that developers should be able to use any framework of their choice. The focus of the CMS is to:

Dynamic Content

Merge HTML Templates with XY Graph.
Cloud Hosting

Provide a wide range of configurations and controls to optimize content hosting and distribution, which is available out of the box.
brand.xyretail.com

Provide an out of the box digital space for brands. A default web root will be provided to all brands and they can customize it by paying a fee.
brand.xyretail.com/private/{private links}

Bring an out of the box digital space for brands to interact with their customers.

XY Connect: An Integration Framework

1. /xy/api/{node uri of api}

The holy grail of endpoints. This endpoint allows developers to connect to any API. Coming Soon

XY Bot: An Automation Framework

1. xy/bot/{node uri of bot}

A new endpoint that will allow developers to invoke and create workflows developed within XY using functions and conditions. Coming Soon

What is XYQL?

XYQL is a native query language and a runtime system similar to GraphQL. Clients form requests by using the XY query language, and the XYQL executes the request and returns the data in a response. Unlike REST APIs, which exposes a different endpoint for each resource object, an XYQL API makes all data available at a single endpoint. A client specifies exactly the data that it wants, and the cloud responds with only that data. Data can be segmented using filters and access control can be done at a level as granular as an attribute level.

An XY query retrieves data from the cloud, similar to a GET request for a REST API. However, unlike REST, all XY queries are sent to a single endpoint and use the POST http method.

An XYQL API models data as nodes connected by edges. A node is an object that has a global ID, such as an Order object or Product object. You can fetch data about an individual node, or you can follow the edges to fetch data about a collection of related nodes. At each node, you specify the fields that you want to retrieve.

XYQL looks similar to JSON. The following example shows a simple XYQL query and the JSON response:

POST /admin/api/2021-01/xyql.json

Base URL

https://graph.xyretail.com

Authentication

Authentication is determining whether a user is logged in or not, and subsequently figuring out which user someone is. Authorization is then deciding what the user has permission to do or see.

Access to XY Query is based on OAuth token that is issued by the owner of the data. User can assign permission for specific endpoint to each token.

Authenticated Request

Authorization: Bearer

API Key

A sample test API key is included in all the examples here, so you can test any example right away.

To test requests using your account, replace the sample API key with your actual API key or sign in.

Attribute Types

XY currently supports 16 attribute types.

The primitive types are the most basic data types available within the Java language. Similar to JAVA, these types serve as the building blocks of data manipulation in XY platform. Such types serve only one purpose — containing pure, simple values of a kind.

The nested type is a specialised version of the object datatype that allows arrays of objects to be indexed in a way that they can be queried independently of each other.

Primitives

String

Any text value.
Integer

Any whole number from -2147483648 to 2147483647.
Long

Any whole number from -9223372036854775808 to 9223372036854775807.
Double

Number with decimal points.
Currency

Number representing currency value. Currency is a long with no decimal. For example, 1050 = 10.50.
Date

Date value. There are 3 parts to any date value ($year, $month, $day). $month value is in base 0.
Date/Time

Long value representing date and time in UTC timezone.
Password

One-way has value representing password value.
Boolean

A binary variable, having two possible values called "true" and "false".
Location

Geolocation value represented by $longitude and $longitude.
JSON

Any JSON object
Node

An object of any entity type. For example, charges object that is nested within a sales order object.
Any

Any attribute can be of any values with exception of attribute of type Lookup and XY Query

Connect to data sources

Fetch data from multiple locations using the following three methods.

A data source is any database, service, or API that holds the data you use to populate your schema's fields. Your XYQL API can interact with any combination of data sources.

XY provides a DataSource class that we can extend to handle interaction logic for a particular type of data source. In this section, we'll extend DataSource to connect both a REST API and a SQL database to XY Cloud. Don't worry, you don't need to be familiar with either of these technologies to follow along with the examples.

Link

Represent a connection to another addressable object in the system.
Lookup

Data from another source based on specified join condition.
XY Query

Customizable data source including aggregates.

Examples

{
    "string": "Lorem ipsum dolor sit amet, consectetur",
    "int": 20,
    "long": 12,
    "double": 1.30,
    "currency": 130000,
    "date":{
        "$year": 2021,
        "$day": 20,
        "$month": 1
    },
    "datetime": 1614220379000,
    "password": "YX72s98sn=2nj",
    "boolean": true,
    "location":{
        "$latitude": 40.7468831,
        "$longitude": -73.9964039
    },
    "json":{
        "a": "Sed ut perspiciatis unde omnis iste natus",
        "b": 777
    },
    "node":{
        "$type": "node",
        "$nodeType": "commerce.charges",
        "currency": {
            "$type": "string",
            "$value": "USD"
        },
    },
    "link":{
        "$type": "link",
        "$value": "7leaf.7leaf/spaces/type/sample"
    }
}

Node URI

Every object in XY is addressable with a node URI.

Node URI consists of 4 different parts:

Space - Indicate which space the data belongs to
App - Application domain such as commerce
Type - Object type
Id - Unique id

Example: spaces-identity.xyretail/commerce/salesorder/373938922

Entity Types

The most basic components of an XYQL schema are entity types, which just represent a kind of entity you can fetch from your service, and what fields it has. In the XYQL schema language, we might represent it like what you see on the right here.

View entity types

Example

{ "data": { "hero": { "name": "R2-D2", "appearsIn": [ "NEWHOPE", "EMPIRE", "JEDI" ] } } }

Errors

XY uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with the XY Cloud (these are rare).

Some 4xx errors that could be handled programmatically (e.g., a card is declined) include an error code that briefly explains the error reported.

HTTP Status Code Summary

200 - OK	Everything worked as expected.
400 - Bad Request	The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized	No valid API key provided.
402 - Request Failed	The parameters were valid but the request failed.
403 - Forbidden	The API key doesn't have permissions to perform the request.
404 - Not Found	The requested resource doesn't exist.
409 - Conflict	The request conflicts with another request (perhaps due to using the same idempotent key).
429 - Too Many Requests	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 - Server Errors	Something went wrong on XY's end. (These are rare.)

Pagination

XY Query utilizes cursor-based pagination via the from and parameters. The parameters take an existing position value and return objects in order specified by the sorter.

Parameters

from optional, default is 0

A cursor for use in pagination.
size optional, default is 20

The number of objects to be returned.

Response Format

hits array

An array containing the actual response elements, paginated by any request parameters..
total int

Total number of records matching specified query.
count int

Number of records in the current results set.
size int

Requested number of records per page.
from int

Requested cursor position.

Response

{
    "hits": [{...}],
    "total": 12,
    "size": 20,
    "count": 12,
    "from": 0
}

Filters

XY Query is filtered based on a pre-configured conditions by default. However, additional filters can be supplied using additional parameters.

String, Link

Equals (=)

An equals filter can be used to filter down the results by specifying one or more matching values

Date/Time

start

start is used to specified the start of the range. The range is inclusive and include results with matching values.
end

end is used to specified the end of the range. The range is inclusive and include results with matching values.

Equals Filter

/query/commerce/salesorder/open?id=8000000001&id=8000000002

Range Filter

/query/commerce/salesorder/open?orderDate.start=1613839805738&orderDate.end=1613857805738

Sorting

XY Query is sorted based on a pre-configured sorter by default. However, this can be overriden by supplying an additional parameter.

Parameters

desc optional

Sort direction with 2 possible values. true to sort descending and false to sort ascending.

URL

/query/commerce/salesorder/open?orderDate.desc=true

1. /xy/query/{node uri of query}

2. /xy/collection/{node uri of collection}

3. /xy/path/{expression}

4. /xy/search/(node uri of query)

5. /xy/functions/{node uri of function}

1. /xy/query/{node uri of query}

Dynamic Content

Cloud Hosting

brand.xyretail.com

brand.xyretail.com/private/{private links}

1. /xy/api/{node uri of api}

1. xy/bot/{node uri of bot}

String

Integer

Long

Double

Currency

Date

Date/Time

Password

Boolean

Location

JSON

Node

Any

Link

Lookup

XY Query

from optional, default is 0

size optional, default is 20

hits array

total int

count int

size int

from int

Equals (=)

start

end

desc optional

Row Actions Target:

Column Actions

Customize

Summary Toolbar Drag and drop these magic bars into the table for different summary views

LY Comparison Bar

YTD Bar

LYTD Bar

TY Bar

LY Bar

Year Bar

Season Bar

Month Bar

Week Bar

Date Bar

Term Bar

Trailing X Bar

Related Sheets

Related Summaries

Related Lists

File

Editor

Mode

Device Mode

Website

Related Widgets

Taxonomy

Linked Accounts

Editor

View

Row Actions
Target:

Summary Toolbar
Drag and drop these magic bars into the table for different summary views