CorvidReference

External Database Collections

The External Database Collections SPI describes the API requests your SPI needs to expect from your Wix site and the responses your Wix site expects in return. The SPI takes the request from your Wix site and converts it into something your external database can receive. It also takes the response from the external database and converts into something your Wix site can receive.

You can learn more about working with External Databases on your Wix site here.

Schema

The Schema SPI describes the payloads for schema API requests to your external database and the payloads for their success and failure responses. Schema API requests may occur whenever your site needs to interact with the data in your external collection. The schema may be cached for at most the amount of time indicated in the ttl field of the schema object.

Find Schemas

POST

/schemas/find

PAYLOAD

{
schemaIds?: string[],
requestContext: RequestContext
}

Success Response

Condition: At least one schema found
Code: 200
PAYLOAD

{
schemas: Schema[]
}

Failure Response

Condition: No schemas found
Code: 404
PAYLOAD

{
message: "..."
}

List Available Schemas

POST

/schemas/list

PAYLOAD

{
requestContext: RequestContext
}

Response

Code: 200
PAYLOAD

{
schemas: Schema[]
}

Schema Object

{
id: string,
ttl: integer, // time in seconds it is safe to cache the schema
defaultSort?: OrderSpec,
allowedOperations: Array < AllowedOperation >,
fields:
{
[fieldName: string]: FieldSpec,
},
maxPageSize?: int
}

OrderSpec Object

{
fieldName: string,
direction:Direction
}

Direction Object

{
asc = "asc",
desc = "desc"
}

FieldSpec Object

{
displayName: string,
type:FieldType
queryOperators: Array <AllowedFilterOperator>,
isDeleted?: boolean
}

FieldType Object

{
number = "number",
text = "text",
boolean = "boolean",
url = "url",
dateTime = "datetime",
image = “image”,
object = "object"
}

AllowedOperation Object

{
insert = "insert",
update = "update",
get = "get",
remove = "remove",
find = "find",
count = "count"
}

AllowedFilterOperator Object

{
eq = "eq",
ne = "ne",
lt = "lt",
lte = "lte",
gt = "gt",
gte = "gte",
hasSome = "hasSome",
hasAll = "hasAll",
contains = "contains",
startsWith = "startsWith",
endsWith = "endsWith",
urlized = "urlized"
}

Data

The External Database Collections SPI describes the API requests your SPI needs to expect from your Wix site and the responses your Wix site expects in return. The SPI takes the request from your Wix site and converts it into something your external database can receive. It also takes the response from the external database and converts into something your Wix site can receive.

You can learn more about working with External Databases on your Wix site here.

The Data SPI describes the payloads for data API requests to your external database and the payloads for their success and failure responses. Data API requests occur whenever your site needs to interact with the data in your external collection.

Find Items

POST

/data/find

PAYLOAD

{
collectionName: string,
filter: Filter,
sort: OrderSpec[],
skip: int,
limit: int,
requestContext: RequestContext
}

Success Response

Condition: Valid query
Code: 200
PAYLOAD

{
items: Item[],
totalCount: int
}

Failure Response

Condition: Invalid query
Code: 400
PAYLOAD

{
message: “...”
}

Get Item

POST

data/get

PAYLOAD

{
collectionName: string,
itemId: string,
requestContext: RequestContext
}

Success Response

Condition: Item found
Code: 2xx
PAYLOAD

{
items: Item[]
}

Failure Response

Condition: Item not found
Code: 404
PAYLOAD

{
message: “...”
}

Insert Item

POST

data/insert

PAYLOAD

{
collectionName: string,
items: Item[]
requestContext: RequestContext
}

Success Response

Condition: Item inserted
Code: 200
PAYLOAD

{
items: Item[]
}

Failure Response

Condition: Invalid item, constraint violation
Code: 400
PAYLOAD

{
message: “...”
}

Item Already Exists Response

Code: 409
PAYLOAD

{
message: “...”
}

Update

POST

data/update

PAYLOAD

{
collectionName: string,
itemId: String,
items: Item[]
requestContext: RequestContext
}

Success Response

Condition: Item updated
Code: 200
PAYLOAD

{
items: Item[]
}

Failure Response

Condition: Invalid item, constraint violation
Code: 400
PAYLOAD

{
message: “...”
}

Condition: Item not found
Code: 404
PAYLOAD

{
message: “...”
}

Remove

POST

data/remove

PAYLOAD

{
collectionName: string,
itemId: String,
requestContext: RequestContext
}

Success Response

Condition: Item removed
Code: 200
PAYLOAD

{
items: Item[]
}

Failure Response

Condition: Item not found
Code: 404
PAYLOAD

{
message: “...”
}

Count

POST

data/count

PAYLOAD

{
collectionName: string,
items: Item[]
requestContext: RequestContext
}

Success Response

Condition: Valid query
Code: 200
PAYLOAD

{
totalCount: int
}

Failure Response

Condition: Invalid query
Code: 400
PAYLOAD

{
message: “...”
}

Item Object

{
_id: string;
[other_fields]: any;
}

Request Context Object

{
settings: object,
instanceId: uuid,
installationId: uuid,
memberId?: uuid,
memberRole?: string
}

Filter Object

The filter object contains a single condition or a combination of conditions through And or Or filters.

And

{
operator: "$and",
value:
[
{
operator: "$gt",
fieldName: 'someField',
value:6
},
{
operator: "$lt",
fieldName: 'someField',
value:12
}
]
}

Or

{
operator: "$or",
value:
[
{
operator: "$eq",
fieldName: 'someField',
value:"hi"
},
{
operator: "$eq",
fieldName: 'someField',
value:"bye"
}
]
}

Not

{
operator: "$not",
value:
[
{
operator: "$eq",
fieldName: 'someField',
value:"hi"
}
]
}

Eq (equal)

{
operator: "$eq",
fieldName: 'someField',
value:"hi"
}

Ne (not equal)

{
operator: "$ne",
fieldName: 'someField',
value:"hi"
}

Lt (less than)

{
operator: "$lt",
fieldName: 'someField',
value:6
}

Lte (less than or equal)

{
operator: "$lte",
fieldName: 'someField',
value:6
}

Gt (greater than)

{
operator: "$gt",
fieldName: 'someField',
value:6
}

Gte (greater than or equal)

{
operator: "$gte",
fieldName: 'someField',
value:6
}

StartsWith

{
operator: "$startsWith",
fieldName: 'someField',
value:6
}

EndsWith

{
operator: "$endsWith",
fieldName: 'someField',
value:6
}

Urlized

{
operator: "$matches",
ignoreCase: true,
fieldName: 'someField',
value: ['hello', 'world']
}

Contains

{
operator: "$contains",
fieldName: 'someField',
value:'ell'
}

HasSome

{
operator: "$hasSome",
fieldName: 'someField',
value:[1,2,3]
}

HasAll

{
operator: "$hasAll",
fieldName: 'someField',
value:[1,2,3]
}

Provision

The External Database Collections SPI describes the API requests your SPI needs to expect from your Wix site and the responses your Wix site expects in return. The SPI takes the request from your Wix site and converts it into something your external database can receive. It also takes the response from the external database and converts into something your Wix site can receive.

You can learn more about working with External Databases on your Wix site here.

The Provision SPI describes the payloads for provisioning API requests to your external database and the payloads for their success and failure responses. Provision API requests occur when you initially connect your endpoint to your site or change its settings.

Provision

POST

/provision

PAYLOAD

{
requestContext: ProvisionRequestContext
}

Success Response

Condition:
Code: 200
PAYLOAD

{
}

Failure Response

Condition:
Code: Other than 200
PAYLOAD

{
message: “...”
}

Provision Request Context Object

{
settings: object,
installationId: UUID
}