Resources API ^BETA

The Spaaza Resources API is a RESTful API that conforms to OpenAPI standards and provides a consistent interface for managing Spaaza resources. The API is designed to achieve consistency across all resource types and follows standard REST conventions.

The Resources API is currently in BETA. While it is fully functional, some aspects may change as we continue to refine and improve the API based on user feedback and evolving requirements.

Contents

• Overview
• Available Resources
• Available Paths
• Schema Endpoint
• Retrieving Multiple Resources (pagination, sorting and filtering)
• Spaaza Vendor Attributes
• Standard Attributes
• Authentication
• Required Headers
• Responses
• Response Recursion Levels
• Example Requests (CURL)
• Versioning
• Error and Warning Codes

Overview

The Resources API provides a standardised way to interact with Spaaza resources using RESTful principles. Each resource supports standard HTTP methods (GET, POST, PATCH, PUT, DELETE) and follows OpenAPI specifications for consistent request and response formats.

The API is built around the concept of resources with properties that can be filtered, sorted, and paginated. Each resource includes OpenAPI annotations that define validation rules, data types, and custom Spaaza-specific attributes.

Available Resources

The Resources API currently supports the following resources:

• Business - Represents a physical store location that is part of a retailer’s chain. Includes location information, contact details, operational settings, and chain association.
• Voucher - Represents a digital entitlement redeemable for discounts or rewards. Supports multiple types including basket vouchers, percentage vouchers, and honour vouchers with comprehensive status tracking.

Available Paths

The Resources API supports the following general endpoint patterns for resources:

Single Resource Operations

• GET /resources/{resource name}/{id} - Retrieve a single resource by ID
• GET /resources/{resource name}?{identifier parameter}={value} - Retrieve a single resource by identifier parameter
• POST /resources/{resource name} - Create a new resource
• PATCH /resources/{resource name}?{identifier parameter}={value} - Update an existing resource (by identifier parameter)
• PATCH /resources/{resource name}/{id} - Update an existing resource (by ID)
• PUT /resources/{resource name}?{identifier parameter}={value} - Update an existing resource (by identifier parameter)
• PUT /resources/{resource name}/{id} - Update an existing resource (by ID)
• DELETE /resources/{resource name}?{identifier parameter}={value} - Delete a resource (by identifier parameter)
• DELETE /resources/{resource name}/{id} - Delete a resource (by ID)

Single resource operations return a JSON object results containing the resource object in accordance with the OpenAPI specification of the resource.

Multiple Resource Operations

• GET /resources/{plural resource name} - Retrieve a list of resources with optional filtering and pagination

Multiple resource operations return a JSON object results containing an array of resources along with pagination metadata:

• resources - Array of resource objects
• limit - Maximum number of results returned
• offset - Starting position of results returned
• total_count - Total number of matching resources available
• result_type - Type of resources returned (plural)

Schema Endpoint

• GET /resources/schema - Retrieve the complete OpenAPI schema for all resources (see Schema Endpoint below for details)

Schema Endpoint

The Resources API provides a comprehensive OpenAPI schema that describes all available resources, their properties, validation rules, and available operations.

Accessing the Schema

curl -X GET https://api0.spaaza.com/resources/schema \
  -H "X-Spaaza-Chain-ID: {chain_id}" \
  -H "X-Spaaza-API-version: 1.6.1" \
  -H "X-Spaaza-Session-User-ID: {your user ID}" \
  -H "X-Spaaza-Session-Key: {your key}"

Schema Structure

The schema response includes the following OpenAPI elements:

• components - Reusable objects and schemas included in the OpenAPI specification
• info - Metadata about the API including contact details and version information
• openapi - The OpenAPI specification version being used
• paths - All available API endpoints with their supported methods and parameters
• servers - Array of servers providing connectivity information
• tags - List of tags used to group related endpoints

The schema provides complete documentation of all resource properties, including standard OpenAPI attributes (type, format, validation rules) and custom Spaaza vendor extensions (recursion levels, filter properties, operation support).

Retrieving Multiple Resources (pagination, sorting and filtering)

When retrieving multiple resources using the plural endpoint (e.g., GET /resources/{plural resource name}), you can use pagination, sorting, and filtering to manage the results.

Pagination and Sorting

When retrieving multiple resources using the plural endpoint (e.g., GET /resources/{plural resource name}), the following query parameters are supported for pagination and sorting:

Example

curl -X GET "https://api0.spaaza.com/resources/{plural resource name}?limit=25&offset=50&sort_by=name&sort_order=asc" \
  -H "X-Spaaza-Chain-ID: {chain_id}" \
  -H "X-Spaaza-API-version: 1.6.1" \
  -H "X-Spaaza-Session-User-ID: {your user ID}" \
  -H "X-Spaaza-Session-Key: {your key}" \
  -H "X-Spaaza-Response-Recursion-Level: 3"

Filtering Multiple Resources

For plural resource endpoints, you can filter results using multiple properties that have the filter-property attribute set to true. These filterable properties are identified in each resource’s documentation in the “Spaaza Vendor Attributes” column of the Properties table.

You can combine filter properties with pagination and sorting parameters:

curl -X GET "https://api0.spaaza.com/resources/{plural resource name}?{filter_property}={value}&{filter_property}={value}&limit=10" \
  -H "X-Spaaza-Chain-ID: {chain_id}" \
  -H "X-Spaaza-API-version: 1.6.1" \
  -H "X-Spaaza-Session-User-ID: {your user ID}" \
  -H "X-Spaaza-Session-Key: {your key}" \
  -H "X-Spaaza-Response-Recursion-Level: 3"

Refer to each resource’s Properties table to see which properties support filtering.

Spaaza Vendor Attributes

Spaaza vendor attributes are custom extensions to the OpenAPI specification that provide additional metadata about resource properties. These attributes control various aspects of API behavior and are prefixed with spaaza- in the underlying schema but documented without the prefix for clarity.

Available Spaaza Vendor Attributes

These attributes help developers understand how properties behave in different API contexts and which properties are available for filtering, identification, sorting, and operation-specific requirements.

Standard Attributes

Standard attributes are part of the OpenAPI specification and define the basic characteristics and validation rules for resource properties.

Common Standard Attributes

These attributes ensure data consistency and provide validation rules that are enforced by the API when creating or updating resources.

Authentication

The Resources API requires authentication for all requests. For detailed information about authentication methods and requirements, please see the Authentication section of the API documentation.

Required Headers

All requests to the Resources API must include the following headers:

Responses

Resources API endpoints return payloads in JSON format as follows:

• Single Resource Retrieval: Returns a JSON object representing the resource in accordance with the OpenAPI specification of the resource.
• Multiple Resource Retrieval: Returns a JSON object containing an array of resources along with pagination metadata.

For more detailed information about API response formats, status codes, and data structures, please see the Responses section of the API documentation.

Response Recursion Levels

The Resources API supports configurable response detail levels through the X-Spaaza-Response-Recursion-Level header. This controls how much detail is included in API responses, particularly for nested objects and relationships.

Recursion Level Values

• Level 0: Minimal response with only basic identifiers
• Level 1: Basic properties without nested objects
• Level 2: Includes some nested object properties
• Level 3: Default level with comprehensive property details
• Level 4: Maximum detail including all available properties

Usage

Include the X-Spaaza-Response-Recursion-Level header in your requests to specify the desired detail level:

curl -X GET https://api0.spaaza.com/resources/{resource name}/{id} \
  -H "X-Spaaza-Response-Recursion-Level: 2" \
  # ... other headers

Note that, in the case of nested resources, the recursion level applies recursively to related resources as well and the remaining recursion level value is “carried” down the object tree. For example, if you request recursion level 3 for a resource, Resource 1, and a nested resource in Resource 1 has a recursion level of 2, then that nested resource will be returned with recursion level of (3 - 2 = 1).

If not specified, the default recursion level of 3 is used.

Example Requests (CURL)

Create a Resource (POST)

curl -X POST https://api0.spaaza.com/resources/{resource name} \
  -H "Content-Type: application/json" \
  -H "X-Spaaza-Chain-ID: {chain_id}" \
  -H "X-Spaaza-API-version: 1.6.1" \
  -H "X-Spaaza-Session-User-ID: {your user ID}" \
  -H "X-Spaaza-Session-Key: {your key}" \
  -H "X-Spaaza-Response-Recursion-Level: 3" \
  -d '{
    "{parameter name 1}": "{string}",
    "{parameter name 2}": {integer},
    "{parameter name 3}": {float}
  }'

Get a Resource by ID (GET)

curl -X GET https://api0.spaaza.com/resources/{resource name}/{id} \
  -H "X-Spaaza-Chain-ID: {chain_id}" \
  -H "X-Spaaza-API-version: 1.6.1" \
  -H "X-Spaaza-Session-User-ID: {your user ID}" \
  -H "X-Spaaza-Session-Key: {your key}" \
  -H "X-Spaaza-Response-Recursion-Level: 3"

Get a Resource by Identifier Parameter (GET)

curl -X GET "https://api0.spaaza.com/resources/{resource name}?{identifier parameter}={value}" \
  -H "X-Spaaza-Chain-ID: {chain_id}" \
  -H "X-Spaaza-API-version: 1.6.1" \
  -H "X-Spaaza-Session-User-ID: {your user ID}" \
  -H "X-Spaaza-Session-Key: {your key}" \
  -H "X-Spaaza-Response-Recursion-Level: 3"

Get List of Resources (GET)

curl -X GET "https://api0.spaaza.com/resources/{plural resource name}?{filter_parameter_1}={value}&{filter_parameter_2}={value}&limit=10&offset=0" \
  -H "X-Spaaza-Chain-ID: {chain_id}" \
  -H "X-Spaaza-API-version: 1.6.1" \
  -H "X-Spaaza-Session-User-ID: {your user ID}" \
  -H "X-Spaaza-Session-Key: {your key}" \
  -H "X-Spaaza-Response-Recursion-Level: 3"

Update a Resource (PATCH or PUT)

The PATCH and PUT methods can be used interchangeably to update resources. Below are examples for both methods.

# By identifier parameter
curl -X PATCH "https://api0.spaaza.com/resources/{resource name}?{identifier parameter}={value}" \
  -H "Content-Type: application/json" \
  -H "X-Spaaza-Chain-ID: {chain_id}" \
  -H "X-Spaaza-API-version: 1.6.1" \
  -H "X-Spaaza-Session-User-ID: {your user ID}" \
  -H "X-Spaaza-Session-Key: {your key}" \
  -H "X-Spaaza-Response-Recursion-Level: 3" \
  -d '{
    "{parameter name 1}": "{string}",
    "{parameter name 2}": {integer}
  }'

# By ID
curl -X PATCH "https://api0.spaaza.com/resources/{resource name}/{id}" \
  -H "Content-Type: application/json" \
  -H "X-Spaaza-Chain-ID: {chain_id}" \
  -H "X-Spaaza-API-version: 1.6.1" \
  -H "X-Spaaza-Session-User-ID: {your user ID}" \
  -H "X-Spaaza-Session-Key: {your key}" \
  -H "X-Spaaza-Response-Recursion-Level: 3" \
  -d '{
    "{parameter name 1}": "{string}",
    "{parameter name 2}": {integer}
  }'

Delete a Resource (DELETE)

# By identifier parameter
curl -X DELETE "https://api0.spaaza.com/resources/{resource name}?{identifier parameter}={value}" \
  -H "X-Spaaza-Chain-ID: {chain_id}" \
  -H "X-Spaaza-API-version: 1.6.1" \
  -H "X-Spaaza-Session-User-ID: {your user ID}" \
  -H "X-Spaaza-Session-Key: {your key}" \
  -H "X-Spaaza-Response-Recursion-Level: 3"

# By ID
curl -X DELETE "https://api0.spaaza.com/resources/{resource name}/{id}" \
  -H "X-Spaaza-Chain-ID: {chain_id}" \
  -H "X-Spaaza-API-version: 1.6.1" \
  -H "X-Spaaza-Session-User-ID: {your user ID}" \
  -H "X-Spaaza-Session-Key: {your key}" \
  -H "X-Spaaza-Response-Recursion-Level: 3"

Versioning

For information about API versioning and version compatibility, please see the Versioning section of the API documentation.

Error and Warning Codes

For a complete list of error codes, warning codes, and troubleshooting information, please see the Error and Warning Codes section of the API documentation.

Table of contents

• Business
• Voucher Resource