The SAP BTP Gamification service web API is based on JSON-RPC (JavaScript Object Notation Remote Procedure Call), a very simple protocol for calling Java methods remotely using a JSON-based serialization via HTTP POST.
The API is split into different topics. However, all methods from all topics can be accessed via central endpoints. In the sections listed below, all available Java methods accessible via JsonRPC are grouped and documented by topic. Authorization is generally based on roles. For each method we annotated the allowed roles (Field “Limited to Roles”).
All methods documented in the sections below include sample requests and responses based on the JSON-RPC specification. Furthermore, there is a small collection of sample requests available for the popular POSTMAN REST Client. Import this collection into your POSTMAN Client to quickly understand how requests have to be configured (X-CSRF, contentTypes, file handling, pagination,.. ).
Backend integration requires a technical user. Authentication is based on the BASIC profile. XSRF protection is disabled. Frontend integration assumes that a user has authenticated against an Identity Provider (IDP) and possesses a SAML token. XSRF protection is enabled, i.e. a token is required for accessing the endpoint.
For details on the integration concept see: SAP Help Portal
Remark: Integration of the user endpoint should normally be done via the available ProxyServlet in combination with App-to-App SSO destinations. For manual testing of requests follow the procedure below or try out the POSTMAN example requests linked above.
When dealing with large numbers of players or other entities, non-paginated queries will become very slow. As a solution, the service allows paginated access to all collections returned by the API. Developers are able to split the total result set into pages of individual sizes from where they request only one page at a time. You can try out the POSTMAN example requests linked above.
{ "error": null, "result": { "metadata": { ... }, "collection": [ element1, element2,... ] } }
Note: Methods which currently do not support pagination are those methods returning player achievements. The service will ignore any pagination related parameters and instead return the full result set. In case a method currently does not allows pagination, a note can be found in its documentation.
Images in requests have to be transported with the appropriate "contentType: multipart/form-data" instead of the regular "contentType: x-www-form-urlencoded". Everything else in the request remains the same (the JsonRPC json object and the related app are added as further key-value pairs). You can find an example in our POSTMAN Example Request Collection linked above.
Images stored in the service are always linked to specific entities (Players, Badges, Levels). Loading the entity will also return meta information for the linked image. Within this data a relative URL can be found which can be used to display the image.
{ "playerId": "player_id", "isPublic": true, "name": "", "image": { "id": 3, "url": "/gamification/api/picture/GetPicture?id=3" } }
In productive settings, the user endpoint should only be used with user roles, while the
technical endpoint should be limited to technical roles. For testing and evaluation purposes it
is possible to assign all roles to a single user. However, to use the technical endpoint a user
at least requires a technical role (AppStandard or AppAdmin).
Requests documented may contain deprecated properties, which
will be removed in future releases.
To test the API we provide Postman import files using the technical endpoint on
localhost:8080. If required change the requests to the user endpoint.
Set of methods used to create, read and delete all game mechanics except for rules.
Set of methods used for managing rules (create, deploy, undeploy, update, delete) and the rule engine itself.
Set of methods used to read data related to the gamification users (players), e.g. earned badges, reached level, earned points, available players, teams, leaderboards etc.
Set of methods used to manage players as well as teams and update their achievements, e.g. give badges, give points, assign missions.
Set of methods used for import and export of gamification data such as points, missions etc.
Set of methods used to query the service for various analytics.
Set of methods used manage players, team and player-specific information, such nickname and image, privacy settings.
Set of methods used for creating, reading and deleting apps.
Set of methods used to submit events that need to be processed by SAP BTP Gamification.