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,.. ).

• POSTMAN Example Requests

Available endpoints

According to our integration concept the web API comprises two endpoints:

• Technical endpoint for backend integration: /gamification/api/tech/JsonRPC
• User endpoint for frontend integration: /gamification/api/user/JsonRPC

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

How to use the technical endpoint:

1. Create a technical user and assign roles via the SAP BTP Cockpit. The following roles are available for the technical endpoint:
   • App Standard: Send events, read achievements
   • App Admin: User management
2. Create new request in the REST client of your choice (e.g. POSTMAN) and configure it to use BASIC authentication, i.e. set header field “Authorization” to value “Basic” + Base64-encoded "username:password" for requests.
3. Send request

How to use the user endpoint

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.

1. Assign roles via SAP BTP Cockpit. User can have the following roles:
   • GamificationDesigner: Modify game mechanics; import apps; read aggregated player data and analytics
   • GamificationReviewer: Read game mechanics; read aggregated player data and analytics
   • TenantOperator: Read game mechanics; full app management; modify player data
   • Player: Read own achievements; edit own profile; read team information
2. Open Browser and logon to SAP BTP Gamification via IDP, e.g. by opening the workbench.
3. Open a REST client (e.g. POSTMAN) in same browser (otherwise SAML token is not available).
4. Get a XSRF token by executing an HTTP GET on the user endpoint with the following header set: Key: "X-CSRF-Token", Value: “Fetch”.
5. Extract XSRF token from response headers. Key= X-CSRF-Token
6. Create new request in REST client (e.g. POSTMAN) and include token in request header field “X-CSRF-Token”.
7. Send the request

How to paginate through large collections

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.

• Pagination parameters are optional request parameters. Leaving them out will always return the full collection. Adding any pagination related parameter will enable pagination for this particular request. Missing parameters are added with their default values.
• There are two pagination related parameters available
  • page: this parameter points to a particular page in the result set (default: 1)
  • perPage: this parameter allows to define a page size (default: 100)
• When splitting the result set into pages, the API user needs information about the total number of results, total number of pages and eventually more. Such information is called metadata and stored within the service response.
• Available metadata:
  • page: the page parameter used in the original request
  • perPage: the page parameter used in the original request
  • totalResults: total number of available result elements
  • totalPages: total number of available pages when using the provided page size (perPage)
  • nextUrl: links to the next page of result sets, when available, else null
  • prevUrl: links to the previous page of result sets, when available, else null
• Response with pagination:

                        {
                            "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.

Sending Images

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.

Image Retrieval

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"
                            }
                        }
                    

Important Remarks

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.