v23.0
v23 was originally planned as a short internal release focusing primarily on technical debt. We also planned to prepare for moving onto shorter release cycles and ultimately continuous delivery, which would entail some breaking changes in v23, so that we could provide backwards compatibility in subsequent releases. As a result v23 is heavily biased towards how things work under the hood rather than Producer-facing features.
In the course of v23 development our priorities shifted back to v22, which meant v23 took longer than originally planned. We've extended v22 with new features, such as Instagram voting, Control API rate limits, listings limits, multi vote GNIP voting, GNIP voting restrictions on number of followers, collection items reordering, collection items labelling, and performance improvements. All of these features were ported into v23 as well.
You will also find that we've made several breaking changes, which was done intentionally. We have made the foundations more consistent and flexible to enable more efficient development in the future. Most of these changes are around APIs, including Control API, LViS Service API, Leaderboard API and client APIs. Although breaking changes where made, it should not take longer than a couple of days to migrate. Please refer to our migration guide.
The biggest change in the APIs is that we are moving away from using numerical IDs for objects in favour of UUIDs. In v22 some of the APIs used numerical IDs and some used UUIDs, which made it impossible or very cumbersome in some cases to integrate several different APIs. For example LViS Service notifications used UUIDs, but Control API used numerical IDs, so making Control API calls off the back of receiving a notification was a problem. In v23 we've replaced the double ID system with a single system of using UUIDs.
The second biggest change, closely linked to the first, is replacing Control API v1 with v2, where v2 uses UUIDs to identify objects and also significantly changes the way to fetch a list of events.
Control API v1 has been removed. We've decided to remove it rather than deprecate because the scope in which v1 would be usable became very narrow after we migrated other APIs to use UUIDs as their main object ID mechanism. V1 also had high potential for putting heavy load on the system due to lack of filtering facility.
V2 uses UUIDs as object identifiers, introduces a more flexible and safer way of fetching events, implements a consistent approach around actions and element states, has enhanced image properties validations, and adds functionality for apps and accounts management. Full documentation is here.
As an example:
- In v22:
PATCH /api/v1/elements/123
- In v23:
PATCH /api/v2/elements/f6844ce1-28a5-478f-9f71-d60112b2944a
Actions include publish, stop, results reveal. In Control API v1 there was a mix of approaches, some actions required the
action
attribute, others did not and worked as a side effect of setting a state property to a desired state. In v2 this side effect based approach is removed and the explicit action
attribute is used to:- publish an element (added in v2)
- stop an active element (available in v1)
- reveal correct answer (available in v1)
- reveal results (available in v1)
- revoke an element (added in v2)
Element states exposed by Control API v2 are more granular and better reflect the life cycle of an element in v23: "non_scheduled", "future", "current, "past", "on_demand", "revoked", "cancelled", against these in v22: "nonscheduled", "scheduled", "current", "finished", "revoked", "cancelled".
All of these states and their combinations can be used for filtering when fetching a list of elements.
Events fetching in v22 was limited and a heavy “all or nothing” operation. V23 is much more flexible. Fetching can be fine-tuned to a particular need via filtering and sorting. The results are not returned as one bulk either. Instead you can fetch them using a cursor page by page.
GET /events
end-point now requires filter[state]
URL parameter. Full list of states supported by the filter are here.Combining states in a filter is also supported.
Control API now validates image pixel size, file size and aspect ratio as per app spec.
When the maximum number of elements or events is reached and more can not be created via Control API (manually creation is not limited) the API now returns HTTP 422, rather than HTTP 429. This change was made because strictly speaking this limit is not a limit on a number of calls and therefore in most case it does not make sense to repeat the call, unlike when handling HTTP 429.
Creating an app in the context of LViS Studio means loading an app spec into the Studio.
V2 adds an end-point for app creation. This end-point is available only to tokens with super admin access.
App spec loader validation has been improved with a goal of providing better diagnostic information if app spec loading fails:
- More data validation is done than in v22
- Stricter validation
- Clearer diagnostic messages are produced for validation errors
- Diagnostic messages include a reference to the exact file which has a problem
- Invalid SSL certificate errors are properly reported
- Corrupt JSON and incorrect MIME detection
New rules are implemented for how
requires_validated_user
setting changes are handled on app spec reload and element cloning. The aim is to make it predictable and consistent.Element duration mode is configurable via app spec. The optional
has_duration
attribute is replaced with a mandatory duration
attribute. This is done in order to create complete clarity and control for the app developer over what duration management mechanism will be used by the Studio. has_duration
was very limited in what it could do, being a simple ON/OFF switch. duration
allows three modes: instant, fixed and flexible, and allows the setting of a default duration via app spec. You can find full documentation here.- Element is not migrated to new app spec during app spec update if
derived_from
is changed to prevent unexpected results.
- Image
width
andheight
attributes are now mandatory (where optional in v22) - New mandatory attribute
file_size
added to set maximum allowed file size for animage
field.
- Added ability to stop an element early
- Width, height, aspect ratio and file size for uploaded images is validated by Studio and Control API image uploader. The validation rules are set up by the app developer within app spec. This feature helps to prevent images that are too big being published.
- Repeat events scheduler now takes "on demand" time into account, so that a repeat event is scheduled with requested delay only after the original event's "on demand" state is finished.
In v23 if certification is enabled at element level, but disabled at project level, then the element is published with certification switched off. Full documentation is here.
- Consistent language "Reveal answer" for revealing the correct answer is used on forms and in cog menu
- File size is displayed for each image within assets library
- Improved UI of 404 and 500 error pages
- Events that do not have audio delay setup are transitioned from "current" to "past" state on the timeline page bypassing the "on demand" state. For events which have audio delay setup the "on-demand" state lasts for the duration of the audio delay.
- UUIDs are displayed for elements (instead of numerical IDs), accounts, apps
A new mechanism is in place that can record spikes and sessions as short as 5 seconds.
In v22 if there was more than one qualifying past or future event starting at exactly the same time, then all such events were included in listings. This meant that the number of events in listings could be higher than limits set for the project.
In v23 the limits are enforced, so in this case not all of the events starting at the same time would be included in listings. You can find more information in the listings guide.
Content publishing latency has been reduced for some cases.
A new role has been added, which sits above "Admin" role. A Tech Admin is allowed to:
- Reload services and switch services on the project
- Access more sensitive service settings, e.g. keys (this assumes that the service was developed with this role in mind)
A Tech Admin can NOT add a service to LViS or reload a service at the LViS instance level. These require Super Admin level of access.
- Account name is displayed in projects list on the service page
- Notification types required by the service are displayed on the service page
- Ability to select & copy data (accounts, projects, members names) on admin pages
static_host
has been added to service instance handshake data to enable the service to use public feeds- Project handshake and project update requests are merged into one
- "project" is changed to "projects" in the URLs to conform to REST resource naming
- IDs are replaced with UUIDs in
- All LViS Services API endpoints including handshakes
- Service notifications
- Element prefill
- Tabs URLs
id
field now contains element UUID instead of integer ID anduuid
field has been removed
- Control API v1
- Combipoll element
- Proxy connections concurrency graph
- A new form of
setDelay
method has been added. It calculates the delay based on the current video/audio/content stream timecode so that the app developer should not have to calculate the delay separately. signIn
method is deprecated and replaced withlogin
method. The principle difference between the two methods is that the latter one reports on success or failure of login operation, while the former does not.
- In order to achieve consistency around naming various properties the
user_id
attribute has been renamedprivate_id
. Full list of attributes is here. - In order to be less cryptic the
value
attribute has been renamedscore
. Full list of attributes is here. - URLs schema for event level leaderboards in Leaderboard WS has been changed to have a consistent approach across project and event level leaderboards. The
event_id
query parameter has been removed and event UUID incorporated into the URL instead, like this:/api/projects/{project_id}/events/{event_id}/leaderboards/{leaderboard_id}
. New format is described here.
Last modified 2yr ago