Subscriptions

• Subscribing: Means requesting the resources server to start pushing (stream) data to a designated URL (called CallBack URL). This is done via HTTP POST with the payload being JSON. Additionally subscriptions can be done using AWS SNS Topics.
  A subscription contains a list of Stream Configurations. A Stream Configuration has a Stream Type, a CallBack URL, Channel Type(Http or SNS) that declares the type of the callback url and optionally an alert email address and API key.
  
  • Subscription expiration: Subscriptions have a duration of 30 days from the day they were created. If a subscription expires, data will stop being streamed to the customer endpoints but will be retained in Sycada's system for a period of 24 hours. After that the data will be purged (see Alerting section).
• Unsubscribing: Means requesting the resources server to stop pushing data. This is a permanent deletion of the subscription that leads to immediate purging of all queued data.
• Resubscribing: A client should re-subscribe before the expiration timestamp. A client can re-subscribe to any combination of entities as long as there is a single Callback URL for each Stream Type.

The listening side, should return an HTTP Status in the range of 200 - 299 to acknowledge the data entity being processed. If any other status code is returned or a connection cannot be established, the Sycada side will re-queue the message and attempt to send it again with a few seconds interval. The message will not be removed from the queue until a successful response is received or the message limit for the queue is reached (see Alerting section).

Exact details on how to subscribe and unsubscribe can be found here.

Delivery

Pushing occurs once the object to be pushed is created on Sycada’s backend. Available Stream Types are:

• Trip segments: When a trip is calculated by the Sycada platform. This happens on either a specific report from the device installed in the vehicle or after a specific message on the Vehicle Status API.
  
  Important: Due to the continuous nature of the trip segment calculation within Sycada, it is possible that trip segments may be re-evaluated and thus re-pushed (streamed) to the customer’s CallBack URL. A trip segment can be uniquely identified by the combination of Vehicle.id and Start.timestamp properties. Meaning no two trips can have the same vehicle id and start timestamp.
  
  The receiving system must be able to handle this scenario by comparing the trip segment’s vehicle id and start timestamp and keeping only the one with the latest stop timestamp, as this will be the correct one.
• Events: Events are created based on asset reports and sent immediately upon creation by the Sycada platform.
  
  Important: Due to the continuous nature of events calculation within Sycada, it is possible that some events may be re-evaluated and thus re-pushed (streamed) to the customer’s CallBack URL. An event can be uniquely identified by the combination of Vehicle.id and Timestamp properties. Meaning no two events can have the same vehicle id and timestamp.
  
  The receiving system must be able to handle this scenario by comparing the event's vehicle id and timestamp and keeping only the last event received with this combination of vehicle id and timestamp
• Charge point transactions: Charge point transactions are created after an electric vehicle is unplugged from a charger, and sent immediately upon creation by the Sycada platform.
• Vehicle status: Whenever there is a change to the status of a vehicle, a new Vehicle status is created and sent by the Sycada platform.
• Charge sessions: Charge sessions are reported by electric vehicles when they are charging. They are sent immediately upon creation by the Sycada platform.
  
  Important: Due to the continuous nature of the charge session calculation within Sycada, it is possible that charge sessions may be re-evaluated and thus re-pushed (streamed) to the customer’s CallBack URL. A charge session can be uniquely identified by the combination of Vehicle.id and Start.timestamp properties. Meaning no two charge sessions can have the same vehicle id and start timestamp.
  
  The receiving system must be able to handle this scenario by comparing the charge session’s vehicle id and start timestamp and keeping only the one with the latest stop timestamp, as this will be the correct one.
• Charge Point status: Whenever there is a change to the status of a charge point, a new Charge Point status is created and sent by the Sycada platform.
• Das configuration: Das Configuration

Authorization If a Callback API key has been specified in the subscription request then it will be included in the X-Sycada-Authorization header of each post request to each Callback API.

Non-delivery

In case the Sycada platform cannot deliver the messages, it will retry automatically. Although the system keeps a buffer of messages that cannot be delivered, at some point it needs to purge all the messages queued. The maximum number of messages that the system will queue is provided upon subscription.

Alerting

The subscriber can specify an email address in its subscription request. If an email address is specified, the following emails may be received in the course of time:

• If 50% of the maximum number of messages is being queued.
• If 100% of the maximum number of messages is being queued and the whole queue was purged.
• Queue being purged 24 hours after expiration of the subscription.
• Prior to subscription expiration:
  • 7 days prior to expiration
  • 3 days prior to expiration
  • 1 day prior to expiration
• When the subscription expires.

Recovery process

Although Sycada’s infrastructure is highly redundant and has multiple persistent data stores along the processing pipe-line, a need for re-processing data entities may arise (i.e. in case of any disaster). In that case, Sycada cannot guarantee that any entity that was delivered before is not delivered again via this API. The consumer must therefore implement entity ‘fingerprinting’ to make sure in such a case, data is not duplicated on their side.