API routes (Click a route to expand it, click here to expand/collapse all)
Default APIs
GET/ ⎘
Provides the API-specification. Only enabled if API exposure is enabled.
Parameter Location Type Requirements Optional Default value Description
format URI-Query string
enum: [ "KateAPI", "InternalAPIMap", "OpenAPI", "Swagger" ]
 Yes "KateAPI" Documentation format. We support KateAPI documentation, Swagger/OpenAPI documentation and raw output of the internal API-map cache.
openApiVersion URI-Query int
enum: [ 2, 3 ]
 Yes 2 Version 3 is crappy with request bodies, so we prefer version 2 (which only sucks regarding Response definitions; hence we prefer KateAPI documentation).
Response HTTP Type Description
Success 200 object The API-documentation.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
Authentication required:
No
Publisher API
POST/publish/redGroupUpdate ⎘
Publish an announcement to all subscribers that a REDGroup has been updated.
Parameter Location Type Requirements Optional Default value Description
idREDGroup POST-body int No ID of the REDGroup that got updated
Response HTTP Type Description
Success 200 int Returns 1 immediately, regardless of processing success.
InvalidRequestSignatureException 400 The request has an invalid KATEv2 IntraService Request Signature.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
Authentication required:
No
POST/publish/redSetUpdate ⎘
Publish an announcement to all subscribers that a REDSet has been updated.
Parameter Location Type Requirements Optional Default value Description
idREDSet POST-body string No ID of the REDSet that got updated
idCustomer POST-body string No ID of the customer owning the REDSet
idDepartment POST-body string No ID of the department owning the REDSet
publisherAuthToken POST-body string No Authorization token (JWT) of the user session that triggered this event. This event will not be sent back to this user session (unnecessary loop).
Response HTTP Type Description
Success 200 int Returns 1 immediately, regardless of processing success.
InvalidRequestSignatureException 400 The request has an invalid KATEv2 IntraService Request Signature.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
Authentication required:
No
POST/publish/redSuggestions ⎘
Publish an announcement to all subscribers that Suggestions for a REDSet have been updated.
Parameter Location Type Requirements Optional Default value Description
idREDSet POST-body string No ID of the REDSet that got updated
idCustomer POST-body string No ID of the customer owning the REDSet
idDepartment POST-body string No ID of the department owning the REDSet
publisherAuthToken POST-body string No Authorization token (JWT) of the user session that triggered this event. This event will not be sent back to this user session (unnecessary loop). Set to empty if system token; i.e. originating from external event.
Response HTTP Type Description
Success 200 int Returns 1 immediately, regardless of processing success.
InvalidRequestSignatureException 400 The request has an invalid KATEv2 IntraService Request Signature.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
Authentication required:
No
POST/publish/redUpdated ⎘
Publish an announcement to all subscribers that one or more REDPoints and/or REDComments have been updated.
Parameter Location Type Requirements Optional Default value Description
idREDSet POST-body string No ID of the REDSet that got updated
idCustomer POST-body string No ID of the customer owning the REDSet
idDepartment POST-body string No ID of the department owning the REDSet
publisherAuthToken POST-body string No Authorization token (JWT) of the user session that triggered this event. This event will not be sent back to this user session (unnecessary loop).
data POST-body string
format: json
 No Array of objects. Each object has 4 keys:
  • type: "point" or "comments"
  • redPath
  • scenario: Optional. If omitted, will assume base data.
  • value: Only for type=point. Optional.
  • comments: Only for type-comments. Required: array of full comment-thread.

Example:
[
{ "type": "point", "redPath": "my_table.[2].my_int", "value": 3 },
{ "type": "comments", "redPath": "my_table.[4]", "scenario": "vacant", "comments": [ ... ] },
{ "type": "point", "redPath": "my_table" },
]
scenario POST-body string Yes "" Scenario of the datapoint that got updated.
value POST-body string
format: json
 Yes "-" Optional. JSON-stringified new value of the datapoint.
Response HTTP Type Description
Success 200 int Returns 1 immediately, regardless of processing success.
InvalidRequestSignatureException 400 The request has an invalid KATEv2 IntraService Request Signature.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
Authentication required:
No
POST/publish/translationUpdate ⎘
Publish an announcement to all subscribers that a namespace has been updated.
Parameter Location Type Requirements Optional Default value Description
namespace POST-body string
format: [A-Za-z0-9.]{2,}
 No Namespace that got updated
Response HTTP Type Description
Success 200 int Returns 1 immediately, regardless of processing success.
InvalidRequestSignatureException 400 The request has an invalid KATEv2 IntraService Request Signature.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
Authentication required:
No
Subscriber API
GET/sse ⎘Authentication required
Subscriber endpoint to listen to SSE events.

Maximum connection time: 2700 seconds. After this or after a server error/disconnect, reconnect accordingly. Do NOT hardcode this runtime length, later it will update to the remaining validity time of the JWT.
Parameter Location Type Requirements Optional Default value Description
idREDSets URI-Query string[] Yes [] Array of REDSet IDs to listen to for dataset updates
idREDGroups URI-Query int[] Yes [] Array of REDGroup IDs to listen to for definition updates
rfcLanguageTags URI-Query string[] Yes [] Array of language-tags to listen to for translation namespace updates
Response HTTP Type Description
Success 200 text/event-stream Returns an event stream for at most 2700 seconds.

Types of returned events:
  • reconnect. Payload: empty. Expected action: resubscribe to this SSE endpoint with refreshed auth token, etc.
  • translationsUpdated. Payload: raw string identifying the updated namespace. Expected action: (re)fetch provided namespace for loaded languages.
  • redGroupUpdated. Payload: raw int identifying the updated REDGroup ID. Expected action: (re)fetch all REDDefinitions having this REDGroup in their definitionContext, and rerender REDEdits involving these REDDefinitions.
  • redSetUpdated. This usually happens when more than a datapoint is updated, such as workflow transitions. Payload: raw string identifying the updated REDSet ID. Expected action: (re)fetch entire referred REDSet, and rerender involved REDEdit/REDSetSelect/REDSetTable accordingly.
  • redPoint. Payload: JSON-encoded string with 2 or 4 keys: "idREDSet", "redPath" and optionally "value" and "scenario". Expected action: if "value" is present, updated the given redPath x scenario with the provided value in the corresponding REDSet; and rerender accordingly. If "value" is NOT present (i.e. for bigger elements, such as HTMLText or FixedTable), [TO BE DEFINED, either refetch REDSet or specific REDPoint].
  • redComments. Payload: Same as redPoint, but instead of "value" has a key "comments" containing the entire comments-thread. Expected action: update the comments on the given redPath x scenario with the provided value in the corresponding REDSet; and rerender accordingly.
  • redSuggestions. Sent when suggestions were updated (user defined or external). Payload: raw string identifying the updated REDSet ID. Expected action: (re)fetch suggestions from suggestions service and display accordingly ONLY when payload REDSetID is an active/open REDEdit REDSet. Otherwise refetch suggestions only upon opening a REDEdit again.

Examples:
type: reconnect
data:

type: translationsUpdated
data: ui.red

type: redGroupUpdated
data: 21

type: redSetUpdated
data: 6433e61dc57ebc57a20640a3

type: redPoint
data: { "idREDSet": "6433e61dc57ebc57a20640a3", "redPath": "my_table.[2].my_number", "value": 0.35 }

type: redPoint
data: { "idREDSet": "6433e61dc57ebc57a20640a3", "redPath": "my_table.[2].my_number", "scenario": "my_scenario", "value": 0.35 }

type: redPoint
data: { "idREDSet": "6433e61dc57ebc57a20640a3", "redPath": "my_table.[6].my_html_text" }

type: redComments
data: { "idREDSet": "6433e61dc57ebc57a20640a3", "redPath": "my_table.[2].my_number", "scenario": "my_scenario", "value": [ ... entire comment array ... ] }

type: redSuggestions
data: 6433e61dc57ebc57a20640a3
InvalidRequestSignatureException 400 The request has an invalid KATEv2 IntraService Request Signature.
UnauthorizedException 403 Authorization for requested method rejected. See error details for details.
MissingRequiredParameterException 400 The request is missing a required input parameter. See details for involved parameter.
InvalidParameterException 400 The request has an invalid argument. See details for involved parameter and invalidation.
AuthenticationFailedException 401 Authentication failed. Re-authenticate and retry. See error details for details.
Authentication required:
Yes
Authentication scheme:
JWTAuth
Required flags:
None ⎘
Authentication schemes (Click an authentication scheme to expand it)
JWTAuth
Result wrappers (Click a result-wrapper to expand it)
Success
Error