# opensearch-search_service

Part of **OPENSEARCH**

# OpenSearch Search Service

## Capabilities Overview

| Sub-capability | Calling Mode | Description |
|----------------|--------------|-------------|
| Get Domain Info | Synchronous | Retrieves the industry type for a specified domain in Alibaba Cloud OpenSearch. |

## API Calling Patterns

### Authentication
The primary authentication method is **Bearer Token** via the `Authorization` header.

- Use the header: `Authorization: Bearer <your_api_key>`
- Store your API key in the environment variable: `DASHSCOPE_API_KEY`
- While other auth methods may exist in broader Alibaba Cloud contexts, Bearer token is the standard for OpenSearch Search Service APIs as shown in official examples.

### Service Endpoint (Endpoint)
The API uses region-specific base URLs:

- China region: `https://api.aliyun.com/v4/openapi/domains/{domainName}`
- International region: `https://api.alibabacloud.com/v4/openapi/domains/{domainName}`

Common regions include `cn-hangzhou`, `cn-shanghai`, and `ap-southeast-1`. Select the appropriate base URL based on your deployment region.

### Synchronous Request Pattern
This API follows a simple synchronous request-response flow:

1. Construct a GET request to the domain-specific endpoint with `{domainName}` in the path
2. Pass `appGroupIdentity` as a query parameter
3. Include the `Authorization: Bearer $DASHSCOPE_API_KEY` and `Content-Type: application/json` headers
4. Receive a JSON response immediately upon success
5. Parse the `result` and `requestId` fields from the response body

No polling or streaming is involved—each call returns the full result in one response.

## Parameter Reference

### Get Domain Info

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| domainName | string | Yes | — | — | The industry type. |
| appGroupIdentity | string | Yes | — | — | The name or ID of the application. |

## Code Examples

### Get Domain Info - Bash - All Regions

```bash
curl -X GET 'https://api.aliyun.com/v4/openapi/domains/{domainName}?appGroupIdentity={appGroupIdentity}' \
-H 'Authorization: Bearer $DASHSCOPE_API_KEY' \
-H 'Content-Type: application/json'
```

### Get Domain Info - Python - All Regions

```python
import requests

def get_domain(domain_name, app_group_identity):
    url = f"https://api.aliyun.com/v4/openapi/domains/{domain_name}"
    params = {
        'appGroupIdentity': app_group_identity
    }
    headers = {
        'Authorization': 'Bearer $DASHSCOPE_API_KEY',
        'Content-Type': 'application/json'
    }
    response = requests.get(url, params=params, headers=headers)
    return response.json()

# Example usage
result = get_domain('ecommerce', 'my_app_group_name')
print(result)
```

### Get Domain Info - Bash - International Region

```bash
curl -X GET 'https://api.alibabacloud.com/v4/openapi/domains/{domainName}?appGroupIdentity={appGroupIdentity}' \
-H 'Authorization: Bearer $DASHSCOPE_API_KEY' \
-H 'Content-Type: application/json'
```

### Get Domain Info - Python - International Region

```python
import requests

def get_domain_intl(domain_name, app_group_identity):
    url = f"https://api.alibabacloud.com/v4/openapi/domains/{domain_name}"
    params = {'appGroupIdentity': app_group_identity}
    headers = {
        'Authorization': 'Bearer $DASHSCOPE_API_KEY',
        'Content-Type': 'application/json'
    }
    response = requests.get(url, params=params, headers=headers)
    return response.json()

# Example usage
result = get_domain_intl('news', 'global_news_app')
print(result)
```

## Response Format

```json
{
  "result": {
    "test": "test",
    "test2": 1
  },
  "requestId": "271D5762-32B7-5F0D-B97D-463EB67F1F3B"
}
```

**Key Fields**:
- `result` — Contains the domain-specific metadata (structure varies by domain)
- `requestId` — Unique identifier for the API request, useful for debugging and support

## Error Handling

| Error Code | Description | Recommended Action |
|------------|-------------|---------------------|
| 400 | Bad Request: The request parameters are invalid or missing. | Verify that `domainName` and `appGroupIdentity` are provided and correctly formatted. |
| 403 | Forbidden: The user does not have sufficient permissions to access the domain. | Ensure your API key has the necessary OpenSearch permissions and is associated with the correct Alibaba Cloud account. |
| 404 | Not Found: The specified domain or application group does not exist. | Double-check the spelling of `domainName` and confirm the application group exists in your OpenSearch instance. |
| 500 | Internal Server Error: An unexpected error occurred on the server side. | Retry the request after a short delay. If the issue persists, contact Alibaba Cloud support with the `requestId`. |

## Pricing & Billing

### Billing Model
Per-request billing: each API call is counted as one request.

### Price Reference

| Tier | Input Price | Output Price |
|------|-------------|--------------|
| standard | 0.0001 / | 0.0001 / |

### Free Tier
1000 free calls per month.

### Usage Limits
100 queries per second (QPS) maximum.

### Billing Notes
Billing is based on actual number of requests. Each invocation of the GetDomain API counts as one billable request.

## FAQ

Q: What is the difference between `domainName` and `appGroupIdentity`?
A: `domainName` refers to the industry type (e.g., "ecommerce", "news"), while `appGroupIdentity` is the specific name or ID of your OpenSearch application group within that domain.

Q: Which endpoint should I use for my region?
A: Use `api.aliyun.com` for deployments in mainland China, and `api.alibabacloud.com` for international regions (e.g., Singapore, US, Europe).

Q: Why am I getting a 403 error even with a valid API key?
A: Your API key must be granted explicit permissions for OpenSearch Search Service operations. Check your RAM policy or contact your Alibaba Cloud administrator to ensure the key has `opensearch:GetDomain` permission.

Q: Can I use this API to list all available domains?
A: No, this API retrieves information for a single specified domain. There is no public listing endpoint in the current Search Service API.

Q: Is the response structure of `result` consistent across domains?
A: No—the contents of the `result` object depend on the domain type and configuration. Refer to your specific OpenSearch application documentation for expected fields.