Release notes
This page contains release notes that apply to all APIs.
2024r4
Multithreading using multiple workers in REST services
Previously, when using REST services in WHATS’ON Base, only one call at the same time could be processed.
For example, if user A’s call took 1 minute and user B’s 1 second, user B had to wait 1 minute before their shorter call was processed.
To process multiple calls at the same time, you would need to start 5 instances of the service with different ports, which made it difficult to configure and used up a lot of memory.
Usually, in this case, a load balancer was used between the client and WHATS’ON, which would randomly redirect the calls to one of the services so multiple calls could be processed. If not, the client would need to be configured to send calls randomly.
This meant configuration outside WHATS’ON was usually needed to make the parallel REST calls possible.
From this version, changes have been made to make multithreading or parallelism possible on REST services in WHATS’ON.
Number of workers
On REST services, such as the Business API interface service or configurable REST interface service, the Number of workers field has been added.
This field defines how many workers can process REST calls in parallel. It is by default set to 1 to reflect the previous behaviour.
When the service is started, it will look at this number and internally start as many processes or workers as the defined number. For example, if you set it to 5, 5 workers are started, meaning 5 calls could be handled at the same time.
If a REST call is sent to the service, it will act as a load balancer and give the task to one of these workers. This means only one instance of the service now needs to run to handle more calls, which also takes up less memory.
If more calls are sent than there are workers, the calls are added to a queue. Once a worker is done, it will take up the call and process it.
Limitations
Note that this number has a limitation. Entering a number like 100.000 would be possible but would not work as WHATS’ON can only use 4GB of memory. Additionally, each worker needs two database connections and there is usually also a limitation on the number of connections.
It is recommended to look at the number of cores on the machine processor to define this number. For example, if your computer has 10 cores, it is advised to set the Number of workers field equal to or lower than 10.
Logging for REST service
For REST services with this Number of workers field, logging will now be different. When the Logging check box on the Logging tab is selected, multiple log files will be created: one for the main service and one per worker. For example, if the Number of workers is set to 2, there will be 3 log files.
The main service log (for example, 20240426_001_won1_WOnRESTDefinitionService.log) will now contain less information. The details of the calls processed by the workers will be stored in separate worker logs. (For example, 20240426_001_WORKER_1_won1_WOnRESTDefinitionService.log)
26 March 2024 16:09:52.631 REST Worker 1 started. 26 March 2024 16:10:24.347 GET /content/v1/api HTTP/1.1 26 March 2024 16:10:24.366 Started 26 March 2024 16:10:24.370 Changes detected: Processed 2 transactions in 4 milliseconds (246 bytes in 1 loops). 26 March 2024 16:10:24.371 Execution duration: 4 ms 26 March 2024 16:10:24.371 Finished 26 March 2024 16:10:24.389 HTTP/1.1 200 OK
In the service launcher log, the full content of each call is also not shown anymore. For example, for the Business API interface service, only the start and end of the executed calls per worker will be logged for monitoring purposes. Otherwise, it would seem as if the service was not doing anything while in fact, the workers were taking care of the tasks. Note that this does not show up in the main log file of the service.
In the following screenshot, calls were executed immediately after each other so each worker took one call.
The WHATS'ON Services_2024r4 and higher.pdf technical document has been updated for this change. It can also be found on the FTP.
2023r11
Activate individual business APIs
Previously, when the Business API module was activated, all business APIs were available to use, even the ones that were not needed.
From this version, the Available Business APIs field has been added to the WOnComponent drop-down list.
It can only be edited in configuration mode when the Business API value is selected. Only the needed APIs should be added here. Contact MEDIAGENIX to do this for you.
When adding business APIs to the business API interface service, the Active criterion on the browser is now set to Yes to filter out the BAPIs not part of the Available Business APIs field. The inactive APIs are indicated in the result list with a trash can icon.
If any APIs were already part of the service, and then deactivated via the drop-down list, they will be marked as inactive in the list and ignored when the service is started.
When the user tries to add an API that is not active, message 5992 is shown.
2023r10
Fix for incorrectly parsed login call in BAPIs
Login calls are used to authenticate a user when sending calls to the business APIs. They will contain the username and password of the user in the body. When the body is entered incorrectly but in JSON format and sent, for example:
{dsdqs
"username": "user",
"password": "won"
}
then the following error response would sent:
{
"statusCode": "400",
"message": "The specified JSON is not syntactically valid",
"timestamp": "2023-10-04T13:37:43Z",
"errors": [
{
"errorCode": "REST-400",
"description": "The specified JSON is not syntactically valid",
"data": []
}
]
}However, when you would enter a body not in JSON format, for example,
--"username": "user", --"password": "won"
then the BAPI service would crash and the credentials were visible in the crash report.
This issue has been fixed. From now, in this case, the same error message is returned:
{
"statusCode": "400",
"message": "The specified JSON is not syntactically valid",
"timestamp": "2023-10-04T13:45:11Z",
"errors": [
{
"errorCode": "REST-400",
"description": "The specified JSON is not syntactically valid",
"data": []
}
]
}2023r8
Fix for content-type header of login call from REST services
It is possible to authenticate calls from REST services to external systems using JWT.
Previously, when a login call was sent from a REST service in WHATS'ON (for example when pushing change log entries), the Content-type header was set to application/plaintext while the format of the body was in JSON.
This issue has been fixed. The Content-type header is now set to application/json.
Fix for error response code for expired JWT
In a previous version, authentication using JWT was implemented using the JWT standard.
Previously, when the JWT was expired, error response code 403 was returned.
{
"statusCode": "403",
"message": "The account being accessed does not have sufficient permissions to execute this operation. [Additional info]",
"timestamp": "2022-08-19T12:27:48Z"
}However, according to the standard, error code 401 should be returned.
{
"statusCode": "401",
"message": "The access token expired",
"timestamp": "2022-08-19T12:27:48Z"
}This issue has been fixed. When the token is expired, a 401 error will be returned.
2022r12
Setting for unique external references per concept
Previously, the external reference of objects in WHATS'ON was a string field without a uniqueness constraint. However, this field is used as a unique identifier in BAPIs and other integrations, which can cause errors.
From this version, it is possible to configure whether external references should be unique per concept. This means that a product and a media asset with the same external reference are still allowed.
When this hard-coded setting is enabled, and there are duplicate external references on the same concept, a problem will appear that prevents saving.
Please contact MEDIAGENIX to enable this setting for you.
2022r8
Fix for error messages for incorrect values in BAPI
Previously, when defining an incorrect value for attributes in the BAPI that consisted of integers (for example, sequence numbers) or digits and periods (for example, cost fields), the error response contained the following description:
Value of [field] should be a string
Since this was misleading for the content of the attributes, the following errors are now returned:
-
Integers:
Value of [field] should be an integer
-
Digits and periods:
Value of [field] should be a number
2022r7
Standard JWT tokens for REST API services
It was already possible to authenticate users for a REST API using JWT. Previously, however, the implementation in WHATS'ON did not completely follow the JWT standard.
From this version, the tokens are generated according to the standard.
The JWTs are still used by setting the Authentication method on a service to User-based JWT, which now triggers the new implementation. When the correct credentials of the API user are sent using the login call of the API, the access token is returned in the response.
{
"statusCode": "200",
"message": "Authentication successful",
"token": "0123456",
"service": "BAPI"
}When this token is decoded, it now contains the following header and claims:
-
alg or algorithm: the algorithm used to sign or encrypt the JWT. For WHATS'ON, this is always HS256.
-
typ or type: the type of the token, which should always be JWT.
-
jti or JWT ID: a generated UUID used for identification. It can be used to find the token in the issued tokens list. (RN-5008)
-
sub or subject: the name of the user for which the token was issued
-
iat or issued at: the timestamp of when the token was issued in INTDATE format.
-
exp or expiration time: the timestamp of when the token will expire in INTDATE format. This is determined by the Access token validity period (seconds) property on the service or when issuing the token (RN-5008).
-
aud or audience: the user code of the Allowed API endpoints on the user account for which the token was issued.
When the token is combined with the JWT secret of WHATS'ON, it is possible to verify the signature.
When the JWT is not accepted, a 403 response is returned:
{
"statusCode": "403",
"message": "The account being accessed does not have sufficient permissions
to execute this operation. [Additional info]",
"timestamp": "2022-08-19T12:27:48Z"
}The additional info in the response indicates the cause:
-
Invalid header: a different alg from HS256 or typ from JWT.
-
Invalid signature:
-
Expired token: when the token has expired.
-
Revoked token: when the token has been revoked (RN-5008)
Note that existing tokens will not work anymore after the upgrade as the verification now expects the JWT standard.
Issued tokens on user account
WHATS'ON now keeps track of the issued tokens for a user in the Issued tokens tab on the user account. Note that not the actual token is not stored on the database. Tokens can also be revoked from this tab. See RN-5008 for more information.
API endpoint on REST services and user accounts
WHATS'ON REST APIs can be protected from unauthorized access by enabling authentication on the service settings. When used, access to API resources require a bearer access token header, as part of each request. This token is obtained by authenticating to a logon endpoint, using a user and password of a WHATS'ON password with access type API or UI and API. (RN-1917)
Up until now, an API user could be used to access any WHATS'ON REST API.
In order to provide better control of which user can access which services, an additional level of API permissions has been added.
On the service configuration, the drop-down API endpoint is available where it can be used to specify the endpoint needed for this service. It is only enabled when the Authentication is set to User-based JWT.
On the user account, the drop-down Allowed API endpoints is available, where it can be used to specify which endpoints the user has access to. It is only enabled when the Access type is set to API or UI and API.
The field takes its values from the new drop-down list MgXAPIEndPoint. The user code for each value is mandatory since it will be used for authentication.
When a user authenticates to a REST API service by sending a login call, the token is returned. When it is decoded, the aud claim will contain the user codes of the API endpoints of the user. In my example, the user has the endpoints BAPI and Push defined.
When the user sends a call with the token to the API, the API endpoints of the service and user are compared. If the service has no end points defined, those of the user do not need to be checked. If it does, it will be checked if the API endpoint of the service matches any of the endpoints on the user account. If not, a 403 response is returned:
{
"statusCode": "403",
"message": "The account being accessed does not have sufficient permissions to execute this operation.
User not allowed for this API endpoint.",
"timestamp": "2022-08-19T13:50:49Z"
}If user has the endpoint, the call is handled and executed.
Fix for response for invalid tokens sent to BAPI
Previously, when using authentication on the BAPI service and a token was sent that was changed manually, for example by adding text to it, the service would crash.
This issue has been fixed. When an invalid token is sent, the following 401 response is returned:
{
"statusCode": "401",
"message": "Server failed to authenticate the request.
Make sure the value of the Authorization header is formed correctly including the signature.",
"timestamp": "2022-11-14T14:42:21Z"
}2022r4
Applications part of business API module
Previously, certain applications that are needed for using the business APIs were not part of the business API module. This meant that when the module was not active, it was still possible to access them.
From this version, the following applications can only be used when the business API module is active:
-
Business API browser
-
File API log entry browser
-
the Business API interface and the File BAPI interface service types when creating a new service
Fix for BAPI service receiving tokens
When using the business API service to send calls to WHATS'ON, it is possible to authenticate using a user-based JWT.
Previously, when a token was sent with a POST /login call to the service, for example via Postman, the system crashed. This was because of a bug in the token parser.
This issue has been fixed.
2021r1.001
Previously, the messages returned by the REST interfaces (configurable REST with REST API definitions or the BAPIs) had a different format depending on the type of error.
From this version, the format of the different messages has been made consistent per status code across XML and JSON REST responses.
2021r1.000
Maximum number of failed authentications for REST services
Previously, when logging into a REST service but the credentials could not be validated several times, it was not possible to configure notifications for this. However, invalid logins could be a sign that someone is trying to hack their way into the system and pose a security risk.
Therefore, in this version, a new property has been added to the REST services called Maximum number of failed authentications.
When a user of access type API fails to log in more than the number of times set in this field, and email notifications are configured, an email will be sent to the email addressee to notify that maximum authentication tries was exceeded.
The log of the service will then include a reference to the user and the IP address from which the logging in was attempted. This allows security officers to block this IP in the firewall.
