JSON Payload Documentation

JSON requests manual

Introduction

The eml-cts (Energy Market Lab - Common Transactive Services) project is a Spring Boot-based solution for handling real-time trading operations within the energy sector. It enables clients to interact with an energy trading system that supports complex transactions such as streaming quotes, interval-based pricing, and time-bound expirations. The eml-cts library uses HTTP requests, including POST for creating or modifying resources and GET for retrieving data, to manage data flows between clients and the server.

Key HTTP Requests within eml-cts

1. POST Requests: These are used to initiate or modify specific trading actions. For example:

   • POST /clientCreateStreamQuote: Allows clients to create streaming quotes by providing details such as transaction type (side), unique identifiers, interval prices, quantities, start times, and expiration times. This is particularly valuable for time-sensitive trading decisions, enabling clients to outline multiple pricing intervals within a single quote request.
   • POST /clientModifyStreamQuote (hypothetical): Could allow clients to adjust existing quotes by changing intervals, quantities, or expiration times based on updated market data.
   • POST /clientCancelStreamQuote (hypothetical): May enable clients to cancel previously created stream quotes, helping to manage trading risks or cancel stale requests.

2. GET Requests: These requests retrieve current or historical data, supporting clients in making informed trading decisions. For example:

   • GET /clientGetStreamQuotes: Retrieves a list of all active streaming quotes, including details like interval pricing, quantities, and timeframes.
   • GET /clientStreamQuoteStatus/{id}: Allows clients to check the status of a specific quote, retrieving metadata about interval pricing updates, trade executions, or pending quantities.
   • GET /clientHistoricalQuotes: Could be used to pull historical trading data, allowing clients to analyze past quote performance and trends in market demand.

Methodology

ClientCreatedStreamQuotePayload

This class acts akin to a container that holds all the details about a client's request to create a streaming quote.

The ClientCreatedStreamQuotePayload class provides the following:

1. Attributes for Tracking the Quote Information:

   • ctsStreamQuotesIds: A list of unique identifiers(List<long>) for client-generated quotes, essential for referencing and handling multiple quote streams.

   • success: A Boolean flag to indicate if the quote creation was successful.

   • info: A string for metadata?, allowing details about the payload

2. Constructors:

   • There are 3 different constructors: a no-argument constructor, a constractor that accepts a list of quote IDs and sets success to true, and a full constructor that simply allows setting all the member class member variables.

3. JSON Structure for Payload: The JSON structure posted to the endpoint includes:

   Post to : http://localhost:8080/teua/1/clientCreateStreamQuote
   {
       "info": "ClientCreateStreamQuotePayload",
       "side": "BUY",
       "ctsQuoteId": 0,
       "streamInvervals": [
               {"streamIntervalPrice":190, "streamIntervalQuantity":50, "streamUid": 1},
               {"streamIntervalPrice":110, "streamIntervalQuantity":20, "streamUid": 1},
               {"streamIntervalPrice":123, "streamIntervalQuantity":23, "streamUid": 1},
               {"streamIntervalPrice":123, "streamIntervalQuantity":23, "streamUid": 1},
               {"streamIntervalPrice":112, "streamIntervalQuantity":33, "streamUid": 1},
               {"streamIntervalPrice":200, "streamIntervalQuantity":53, "streamUid": 1}
       ],
       "streamStart":{"instantString": "2020-06-20T08:00:00Z"},
       "intervalDurationInMinutes": 60,
       "bridgeExpireTime": {
           "instantString": "2020-06-20T19:00:00Z"
       }
   }

   • info: Metadata about the payload.
   • side: The type of transaction (e.g., BUY)
   • ctsQuoteId: The specific identifier for the quote
   • streamIntervals: A list of intervals with streamIntervalPrice, streamIntervalQuantity, streamUid to indicate the price, the quantity, and the unique identifiers.
   • streamStart and bridgeExpireTime: Objects containing timestamp strings, defining the start and expiration/end times for the quote stream.
   • intervalDurationInMinutes: Indicates the duration in minutes for each streaming interval.

EiCreatedStreamTenderPayload

Design of the component: In the CTS market, stream tenders do not exist. They are simply a client-side semantic that allows clients to construct a stream tender specifying a stream of resource purchases or sales. Stream tenders themselves are just a sequence of separate tenders with different prices and quantities, arranged in sequential intervals of the same length. So, we can leverage the existing architecture around creating tenders to generate a sequence of createTender requests according to the prices and intervals outlined in the stream tender object. This may later be changed with the implementation of allOrNone, but currently, it serves our purposes.

Please note, this class' main functionality stems from TeuaRestController.java to LmaRestController.java and finally ends in the LmeRestController.java.

The JSON structure posted to the endpoint includes:

Post to : http://localhost:8080/...
{
    "info": "ClientCreateStreamTenderPayload",
    "side": "BUY",
    "ctsTenderId": 0,
    "streamIntervals": [
            {"streamIntervalPrice":190, "streamIntervalQuantity":50, "streamUid": 1},
            {"streamIntervalPrice":110, "streamIntervalQuantity":20, "streamUid": 1},
            {"streamIntervalPrice":123, "streamIntervalQuantity":23, "streamUid": 1},
            {"streamIntervalPrice":123, "streamIntervalQuantity":23, "streamUid": 1},
            {"streamIntervalPrice":112, "streamIntervalQuantity":33, "streamUid": 1},
            {"streamIntervalPrice":200, "streamIntervalQuantity":53, "streamUid": 1}
    ],
    "streamStart":{"instantString": "2020-06-20T08:00:00Z"},
    "intervalDurationInMinutes": 60,
    "bridgeExpireTime": {
        "instantString": "2020-06-20T19:00:00Z"
    }
}

• info: Metadata about the payload.
• side: The type of transaction (e.g., BUY)
• ctsTenderId: The specific identifier for the Tender
• streamIntervals: A list of intervals with streamIntervalPrice, streamIntervalQuantity, streamUid to indicate the price, the quantity, and the unique identifiers.
• streamStart and bridgeExpireTime: Objects containing timestamp strings, defining the start and expiration/end times for the quote stream.
• intervalDurationInMinutes: Indicates the duration in minutes for each streaming interval.

ClientManageTickerSubscriptionPayload

Overview:

The ClientManageTickerSubscriptionPayload payload is designed for managing ticker subscriptions in the EML-CTS system. It supports various operations such as subscribing to real-time quotes, requesting snapshots of market data, and canceling active subscriptions. This payload format is typically sent between clients and servers in JSON format.

Payload Structure Breakdown

Here’s a detailed explanation of each field in the payload, including its purpose and possible values.

The JSON structure posted to the endpoint includes:

1. info

"info": "ClientManageTickerSubscriptionPayload"

• Description: A metadata field indicating the type of payload.
• Purpose: Helps the receiving system understand what type of operation this payload represents.
• Value: Always set to "ClientManageTickerSubscriptionPayload".

2. tickerType

"tickerType": "QUOTES"

• Description: Specifies the type of data the client wants to subscribe to.
• Purpose: Determines the category of market data requested.
• Possible Values:
  • "QUOTES": Real-time market quotes.
  • (Other values could be supported depending on the system configuration.)

3. marketId

"marketId": {
    "value": 1
}

• Description: An object containing the unique identifier for a specific market.
• Purpose: Distinguishes the relevant market where subscription actions should be performed.
• Structure:
  • value (int): A unique integer representing the market ID.

4. segmentId

"segmentId": 2

• Description: The segment of the market related to the subscription.
• Purpose: Enables finer market data targeting, such as a specific stock market segment or trading floor.
• Value:
  • Any valid integer representing a market segment.
  • Example: 2 might refer to a stock trading segment.

5. subscriptionActionType

"subscriptionActionType": "SNAPSHOT_AND_UPDATES"

• Description: Specifies the type of action the client wants to perform concerning the ticker subscription.
• Purpose: Determines how the system processes the subscription request.
• Possible Values:
  • "SNAPSHOT_AND_UPDATES": Requests the current snapshot and real-time updates afterward.
  • "SNAPSHOT": Requests only the current snapshot with no continuous updates.
  • "CANCEL": Cancels an active subscription.

6. subscriptionId (Optional)

"subscriptionId": 0

• Description: A unique identifier representing the subscription being managed.
• Purpose: Useful when modifying or canceling an existing subscription.
• Value:
  • An integer, typically auto-generated or assigned during subscription creation.
  • Example Scenarios:
    • 0: When requesting a new subscription.
    • Non-zero values when updating or canceling existing subscriptions.

Sample Paylod Examples

1. Request a New Subscription:

{
    "info": "ClientManageTickerSubscriptionPayload",
    "tickerType": "QUOTES",
    "marketId": { "value": 1 },
    "segmentId": 2,
    "subscriptionActionType": "SNAPSHOT_AND_UPDATES",
    "subscriptionId": 0
}

Purpose: Requests the latest data and continuous updates from market ID 1, segment 2

2. Request a Snapshot Only:

{
    "info": "ClientManageTickerSubscriptionPayload",
    "tickerType": "QUOTES",
    "marketId": { "value": 1 },
    "segmentId": 2,
    "subscriptionActionType": "SNAPSHOT",
    "subscriptionId": 456
}

Purpose: Retrieves the latest snapshot from market ID 1, segment 2, without updates.

3. Cancel the Subscription:

{
    "info": "ClientManageTickerSubscriptionPayload",
    "tickerType": "QUOTES",
    "marketId": { "value": 1 },
    "segmentId": 2,
    "subscriptionActionType": "CANCEL",
    "subscriptionId": 41
}

Purpose: Cancels an active subscription with ID 41 for market ID 1, segment 2.

ClientCreateQuote Payload

Overview:

The ClientCreateQuotePayload class defines a payload structure used within the Energy Mashup Lab's Common Transactive Services (EML-CTS) for creating quotes. This payload is part of a system designed for handling tenders, including interval and stream tenders, following the latest standards as of September 2024.

The class includes attributes necessary for representing a client quote in the trading system, including details about the transaction side, quantity, price, and associated time intervals.

Payload Structure Breakdown

Here’s a detailed explanation of each field in the payload, including its purpose and possible values.

1. info

   • A descriptor string
   • Default value: ClientCreateTenderPayload

2. side

   • Indicate whether the quote is a buy or sell operation
   • Values: BUY or SELL

3. quantity

   • The amount of quoted resource

4. price

   • The proposed price for quantity

5. ctsTenderId

   • Represents the duration and start time of the tender's activity

6. bridgeExpireTime

   • Indicates the expiration time for the tender
   • Defaults to null unless set

ClientAcceptQuote Payload

The ClientAcceptQuotePayload class represents a payload used within the Energy Mashup Lab - Common Transactive Services (EML-CTS) for accepting a previously created quote. This payload is used when a client agrees to the terms of a specific quote within the transactive system.

The class encapsulates essential data required to accept a quote, such as the referenced quote ID, the agreed quantity, and the price. It supports JSON serialization and deserialization for seamless integration with the REST API.

Payload Structure Breakdown

Here’s a detailed explanation of each field in the payload, including its purpose and possible values.

1. info

   • A descriptor string for the payload, usded for logging and debugging
   • Default value: ClientAcceptQuotePayload

2. quantity

   • The agreed amount of the resource to be exchanged

3. price

   • The agreed price for the specified quantity

4. referenceQuoteId

   • A unique identifier for the quote being accepted