Events API v2
Overview
In line with our commitment to continually improve our services, we have broken out the Events functions from ITAS Web Services v1 to allow us to create a more suitable framework around the most popular functions.
The Events API has been updated to use ASP.NET Core framework to both take advantage of performance improvements and also to align with the current technology strategy adopted by the other components of the ITAS Tech Stack.
This article is targeted to both new adopters of ITAS Events and those that have already implemented under v1.
What's New
- The underlying code has been updated and all endpoints under v2 are built on ASP.NET Core framework
- There are new ports assigned for both SSL certificated (5710) and uncertificated (4710) endpoints
- The v1 URL structure has been migrated to the new API to enable existing consumers to initially just switch ports for UAT (see Migration Planning below)
- New URL structure has been added to simplify the PEEK-RECEIVE-CONFIRM (v1) to a PEEK-CONFIRM (v2) message management process
- Authentication now available by bearer token (with new EVENTS role) as well as original HMAC
- Response code for new PEEK endpoint (see below) when no messages will be 204 (No Content)
- Direct testing is available via local documentation (see {{host.v2}}/swagger)
Endpoint Comparison
{{host.v1}} - port 81
{{host.v2}} - port 4710/5710
| Purpose | v1 | v2 |
| Create Subscriber (Mailbox) | POST {{host.v1}}/Events/Register?subscriberName={subscriberName} | POST {{host.v2}}/Subscribers/{subscriberName} |
| Subscribe to a Topic | POST {{host.v1}}/Events/Subscribe?subscriberId={subscriberID}&topic={n-nn}&companyCode=GF | PUT {{host.v2}}/Subscriptions/{subscriberID}/{n-nn} |
| Publish Message | PUT {{host.v1}}/Events/Publish?companyCode=GF&topic={n-nn} | PUT {{host.v2}}/Messages/{n-nn} |
| Peek Messages | GET {{host.v1}}/Events/Peek?subscriberId={subscriberID}&timeout=10 | GET {{host.v2}}/Messages/{subscriberID}?timeout=10 |
| Receive Message | POST {{host.v1}}/Events/Receive?subscriberId={subscriberID}&messageId={messageID}&lockTimeout=30 | first message is returned within the Peek response |
| Confirm Message | DELETE {{host.v1}}/Events/Confirm?subscriberId={subscriberID}&messageId={messageID} | DELETE {{host.v2}}/Messages/{subscriberID}/{messageID} |
Migration Planning
For existing consumers of Events API through ITAS Web Services v1 (port 81) there are two options:
- Option 1 - test new endpoints with new database in isolation
- The deployment team will setup a separate, test Events Database with the same tables used by v1
- Local IT / Integration Team (LI/IT) can test using the existing endpoints redirected to either port 4710 (HTTP) or 5710 (HTTPS)
- Optional (but recommended): LI/IT can test using the dedicated v2 endpoints (see Endpoint Comparison) on the same port as (2)
- Once UAT is signed-off the deployment team can re-configure the API to use the Events Database previously using through port 81 [v1] (see below)
- Option 2 - redirect migrated endpoints [v1] to existing database which simply involves applying changes to configuration files (see below)
The deployment team can assist with configuration changes to:
- Update trader desktop config
- Update to itascomapp.config
- Update to url used by middleware/integration (to be performed by Local IT / Integration Team)