# 4. Request & Response

# Request and Response Specifications

This section describes the **request format** and **response structure** conventions for the FoxData API, to facilitate consistent encapsulation, parsing, and debugging by callers.

---

## 1. Request Structure

### Request Methods

- All FoxData API data interfaces uniformly use **`POST`**.

### Request Headers

- `Content-Type: application/json`
- `x-openapi-key: <YOUR_LICENSE>` (Authorization key; obtain from the Personal Center or by contacting Sales)

### Request Body (JSON)

- The request body is a JSON object
- Common fields include:
  - `appId`: Application identifier (App Store App ID or Google Play package name; refer to the API documentation for specifics)
  - `region`: Country/region (e.g., `US`)
  - `language`: Language (e.g., `en_US`; optional for some APIs)
  - `start` / `end`: Time range (optional for some APIs; format is typically `YYYY-MM-DD`)
  - `metrics` / `keywords` / `competitorIds`, etc.: Expanded based on the API scenario

### Parameter Naming Conventions

- Parameter names typically use **lowerCamelCase**, for example: `appId`, `categoryId`, `pageKey`.
- Whether a parameter is required, its type, and valid values are subject to the corresponding API documentation.

---

## 2. Response Structure

APIs typically return a standardized JSON structure:

- `code`: Business status code (commonly `200` in examples, indicating success; refer to the actual API for specifics)
- `msg`: Status description (commonly `success` in examples)
- `data`: Business data body

### Common Fields in `data`

In most APIs, `data` typically contains the following (depending on the API):

- `requestParam`: Request parameters returned by the server (for debugging and auditing)
- `result`: Business result (may be an object or an array)
- `creditsCost`: Information on credits consumed by this call
  - `requestCredits` / `baseCredits` / `extraCredits` / `totalCostCredits`
- `next`: Pagination information (present in some interfaces)

Example (structure illustration):

```json
{
  “code”: 200,
  “msg”: “success”,
  “data”: {
    “requestParam”: {
      “appId”: “com.moye.shelter”,
      “region”: “US”,
      “language”: “en_US”
    },
    “result”: [],
    “creditsCost”: {
      “requestCredits”: 0,
      “baseCredits”: 10,
      “extraCredits”: 0,
      “totalCostCredits”: 10
    },
    “next”: null
  }
}
```

> Note: `code` is a business status code and is not the same as an HTTP status code. The mapping between HTTP-layer status codes and the business-layer `code` depends on your server-side implementation.

---