# Server-Side API

### Postman Collection

The API documentation includes a [collection of requests with examples](https://www.postman.com/gravity-field/workspace/gravity-field-server-side-api/overview). It is designed for easy browsing, allowing you to explore the functionality even without a Postman account.

If you are already using Postman, you can fork and run the collection directly in your own account.

### Authorization

This API uses [basic authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization#basic_authentication). For the authorization, you will need to use your section's API-key.

Your authorization header should look like this:

```
--header 'Authorization: Basic YWhhbWwsdG9uQGFwaWdlZS5jb206bClwYXNzdzByZAo'
```

You can request the API Key from “Settings” → “API Keys”

### Main Differences Between Server-Side and Frontend Implementation

With the API integration, it is necessary to assign IDs to users and sessions on the customer’s side.

Creating new campaigns requires the involvement of the development team, specifically for:

* Implementing a campaign request using [`choose`](#ssapi-choose).
* Processing the received response (JSON) and rendering the result.
* Passing information about a user interactions with the campaign using `engagement`.

### Page: Sending Page View Information

For personalization to work correctly, it is necessary to send information about page views on the website (or screen views in the application) for all the users. Typically, this task is solved together with the campaign request via a dedicated parameter in the choose request (see below). However, there is also the option to send page view information separately from the campaign request using /page endpoint.

{% hint style="info" %}
When using hybrid implementation, it is necessary to send page view information for the pages where there is no frontend script.
{% endhint %}

{% openapi src="/files/cShIrR5KMKPUQJiT0WKe" path="/ssapi/page" method="post" %}
[SSAPI.yaml](https://3786223776-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgMtBULwktLmojWzNHUD1%2Fuploads%2Fgit-blob-6290de6fa9563f364d182b178e62313d65c8f683%2FSSAPI.yaml?alt=media)
{% endopenapi %}

### Events: Transmitting Information About Events

In order to collect statistics and optimize campaigns, it is necessary to provide Gravity Field with information about user actions on the site (in the application).

List of possible events: [3. Events](https://app.gitbook.com/o/EEasDkRclT6ZeuxuncO3/s/gMtBULwktLmojWzNHUD1/~/changes/13/documentation-to-be-removed/3.-events)

{% hint style="info" %}
It is recommended to exclude events generated by bots and the QA team from the transmitted data.
{% endhint %}

{% openapi src="/files/cShIrR5KMKPUQJiT0WKe" path="/ssapi/event" method="post" %}
[SSAPI.yaml](https://3786223776-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgMtBULwktLmojWzNHUD1%2Fuploads%2Fgit-blob-6290de6fa9563f364d182b178e62313d65c8f683%2FSSAPI.yaml?alt=media)
{% endopenapi %}

### Choose: Requesting Campaigns

Both Custom Code and Recommendations campaigns could be requested by `choose`.

The campaigns are identified in the requests by API Selector Name or API Selector Groups.

{% hint style="info" %}
In case of Hybrid implementation you can use a choose-request with`null` in `user.slid` and`session.sl` to get new identifiers.
{% endhint %}

{% openapi src="/files/cShIrR5KMKPUQJiT0WKe" path="/ssapi/choose" method="post" %}
[SSAPI.yaml](https://3786223776-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgMtBULwktLmojWzNHUD1%2Fuploads%2Fgit-blob-6290de6fa9563f364d182b178e62313d65c8f683%2FSSAPI.yaml?alt=media)
{% endopenapi %}

**To handle errors gracefully, you need to**

1. Set a response timeout.
2. In case of timeout or response different from status 200, you will need either
   * display nothing
   * display a stub (default banner, pre-installed set of products in the widget, etc.). Additionally, we recommend sending a custom fallback event to Gravity Field.

### Engagement: Passing Information About Users’ Interactions With Personalization Campaigns

In order to gather valuable statistics and further optimize your campaigns, you should pass the information about users's interactions with personalization campaigns.

{% openapi src="/files/cShIrR5KMKPUQJiT0WKe" path="/ssapi/engagement" method="post" %}
[SSAPI.yaml](https://3786223776-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgMtBULwktLmojWzNHUD1%2Fuploads%2Fgit-blob-6290de6fa9563f364d182b178e62313d65c8f683%2FSSAPI.yaml?alt=media)
{% endopenapi %}

### Rate limits <a href="#rate-limits" id="rate-limits"></a>

All requests are limited to 500 requests per second (RPS) per section.

### Additional Recommendations

* Keep API keys safe and do not disclose them to third parties
* Ensure that all API calls for the same user within one session have the same User and Session IDs
* Request recommendations asynchronously to speed up content rendering
* Set a timeout for waiting for a response from the API. Prepare a default content option in advance for displaying when there is no response. It is also recommended to keep statistics on timings and cases when a response from the API was not received (additional events can be sent in case of response timeouts).

### Debugging

You can view all your requests and corresponding responses in real-time in your Gravity Field account (Settings/API Logs).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.gravityfield.ai/lang/en/implementation/server-side-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.