API v2
The Genesys API v2 aims to make the API more consistent, allowing for simpler implementation of the UI and for easier maintenance of the backend.
The key change is the introduction of OpResponse<T>
for actions and default support for executing the same action on multiple objects.
Actions
Services must be designed to handle all action logic within a single transaction. Handle transaction rollbacks properly. Action services must be designed for a single unit of work.
- Actions must operate only on the current records and must fail when attempting to operate on outdated records.
- Actions must check for appropriate permissions.
- API for such actions must not use HTTP GET method.
Action response
The result of the action must be clearly communicated to the client. There are two possible outcomes of an action execution: either the action succeeded (“success”) or the action failed (“error”): { “success”: { … } }
or { “error”: “Error message” }
In case of success, the object under “success” key is whatever the action returned. In case of failure, the contents of the “error” property is the error message.
Same action on multiple objects
Executing the same action on multiple inputs should be supported. In this case, the application should receive a list of input parameters and return a list of responses, one for each set of action parameters.
When actions are executed in the order received, there are no further requirements, the action responses are returned in the order received. Parallel action execution is possible, and can be handled on the server by using Futures: tasks are scheduled for execution and action results collected in the order they were submitted.
Consistent APIs are a benefit to the client and to the developer. With that in mind, only multiple-input actions should not be supported to avoid having duplicate endpoints for the same action.