Initial commit

2025-11-30 08:55:15 +08:00
commit 0e7a2dc56e
16 changed files with 4431 additions and 0 deletions
--- a/references/api-reference.md
+++ b/references/api-reference.md
@@ -0,0 +1,402 @@
+# SAP Service Manager API Reference
+
+**Base URI**: `[https://service-manager.cfapps.<region>.hana.ondemand.com/v1/`](https://service-manager.cfapps.<region>.hana.ondemand.com/v1/`)
+
+**Documentation**: [https://github.com/SAP-docs/sap-btp-service-manager/tree/main/docs/Service-Consumption/SAP-Service-Manager](https://github.com/SAP-docs/sap-btp-service-manager/tree/main/docs/Service-Consumption/SAP-Service-Manager)
+
+---
+
+## Table of Contents
+
+1. [Authentication](#authentication)
+   - User Access Tokens
+   - Client Access Tokens
+   - Token Retrieval
+2. [API Groups](#api-groups)
+   - [Platforms API](#1-platforms-api)
+   - [Service Brokers API](#2-service-brokers-api)
+   - [Service Offerings API](#3-service-offerings-api)
+   - [Service Plans API](#4-service-plans-api)
+   - [Service Instances API](#5-service-instances-api)
+   - [Service Bindings API](#6-service-bindings-api)
+   - [Operations API](#7-operations-api)
+3. [Common Patterns](#common-patterns)
+   - Filtering
+   - Pagination
+   - Error Handling
+4. [Response Formats](#response-formats)
+   - Success Responses
+   - Error Responses
+5. [Rate Limiting](#rate-limiting)
+   - Limits Overview
+   - Headers
+
+---
+
+## Authentication
+
+### User Access Tokens
+- Represent named users
+- Scopes derived from assigned roles
+- Obtained via password or SSO flow
+
+### Client Access Tokens
+- Represent technical clients
+- Scopes derived from service plan
+- Obtained via client credentials flow
+
+### Token Retrieval
+
+```bash
+curl '<uaa_url>/oauth/token' -X POST \
+  -H 'Accept: application/json' \
+  -d 'grant_type=client_credentials&client_id=<clientid>&client_secret=<clientsecret>'
+```
+
+**Response**:
+```json
+{
+  "access_token": "<access_token>",
+  "token_type": "bearer",
+  "expires_in": 43199,
+  "scope": "<xsappname>.job.read <xsappname>.event.read"
+}
+```
+
+**Usage**: Include `Authorization: Bearer <access_token>` header in all requests.
+
+---
+
+## API Groups
+
+### 1. Platforms API
+
+**Base**: `/v1/platforms`
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/v1/platforms` | List all registered platforms |
+| GET | `/v1/platforms/{platformID}` | Get specific platform |
+| POST | `/v1/platforms` | Register new platform |
+| PATCH | `/v1/platforms/{platformID}` | Update platform |
+| DELETE | `/v1/platforms/{platformID}` | Unregister platform |
+
+**Platform Registration Request**:
+```json
+{
+  "name": "my-platform",
+  "type": "kubernetes",
+  "description": "My K8s cluster"
+}
+```
+
+**Platform Response**:
+```json
+{
+  "id": "platform-id",
+  "name": "my-platform",
+  "type": "kubernetes",
+  "description": "My K8s cluster",
+  "created_at": "2025-01-01T00:00:00Z",
+  "updated_at": "2025-01-01T00:00:00Z",
+  "credentials": {
+    "basic": {
+      "username": "generated-user",
+      "password": "generated-pass"
+    }
+  }
+}
+```
+
+---
+
+### 2. Service Brokers API
+
+**Base**: `/v1/service_brokers`
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/v1/service_brokers` | List all brokers |
+| GET | `/v1/service_brokers/{brokerID}` | Get specific broker |
+| POST | `/v1/service_brokers` | Register broker |
+| PATCH | `/v1/service_brokers/{brokerID}` | Update broker |
+| DELETE | `/v1/service_brokers/{brokerID}` | Delete broker |
+
+**Broker Registration Request**:
+```json
+{
+  "name": "my-broker",
+  "broker_url": "[https://broker.example.com",](https://broker.example.com",)
+  "description": "My service broker",
+  "credentials": {
+    "basic": {
+      "username": "broker-user",
+      "password": "broker-pass"
+    }
+  }
+}
+```
+
+---
+
+### 3. Service Instances API
+
+**Base**: `/v1/service_instances`
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/v1/service_instances` | List all instances |
+| GET | `/v1/service_instances/{instanceID}` | Get specific instance |
+| POST | `/v1/service_instances` | Create instance |
+| PATCH | `/v1/service_instances/{instanceID}` | Update instance |
+| DELETE | `/v1/service_instances/{instanceID}` | Delete instance |
+
+**Create Instance Request**:
+```json
+{
+  "name": "my-instance",
+  "service_plan_id": "plan-guid",
+  "parameters": {
+    "key1": "value1"
+  },
+  "labels": {
+    "environment": ["production"]
+  }
+}
+```
+
+**Instance Response**:
+```json
+{
+  "id": "instance-id",
+  "name": "my-instance",
+  "service_plan_id": "plan-guid",
+  "platform_id": "platform-id",
+  "context": {},
+  "parameters": {},
+  "labels": {},
+  "ready": true,
+  "usable": true,
+  "created_at": "2025-01-01T00:00:00Z",
+  "updated_at": "2025-01-01T00:00:00Z",
+  "last_operation": {
+    "type": "create",
+    "state": "succeeded"
+  }
+}
+```
+
+**Query Parameters**:
+- `fieldQuery`: Filter by field values
+- `labelQuery`: Filter by label values
+- `max_items`: Limit results
+- `token`: Pagination token
+
+---
+
+### 4. Service Bindings API
+
+**Base**: `/v1/service_bindings`
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/v1/service_bindings` | List all bindings |
+| GET | `/v1/service_bindings/{bindingID}` | Get specific binding |
+| POST | `/v1/service_bindings` | Create binding |
+| DELETE | `/v1/service_bindings/{bindingID}` | Delete binding |
+
+**Create Binding Request**:
+```json
+{
+  "name": "my-binding",
+  "service_instance_id": "instance-id",
+  "parameters": {
+    "credential-type": "x509"
+  }
+}
+```
+
+**Binding Response** (Default Credentials):
+```json
+{
+  "id": "binding-id",
+  "name": "my-binding",
+  "service_instance_id": "instance-id",
+  "credentials": {
+    "clientid": "client-id",
+    "clientsecret": "client-secret",
+    "url": "[https://service.example.com",](https://service.example.com",)
+    "sm_url": "[https://service-manager.cfapps.region.hana.ondemand.com"](https://service-manager.cfapps.region.hana.ondemand.com")
+  },
+  "ready": true,
+  "created_at": "2025-01-01T00:00:00Z"
+}
+```
+
+**Binding Response** (X.509 Credentials):
+```json
+{
+  "credentials": {
+    "clientid": "client-id",
+    "certificate": "-----BEGIN CERTIFICATE-----...",
+    "key": "-----BEGIN RSA PRIVATE KEY-----...",
+    "certurl": "[https://cert.auth.url"](https://cert.auth.url")
+  }
+}
+```
+
+---
+
+### 5. Service Plans API
+
+**Base**: `/v1/service_plans`
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/v1/service_plans` | List all plans |
+| GET | `/v1/service_plans/{planID}` | Get specific plan |
+
+**Plan Response**:
+```json
+{
+  "id": "plan-id",
+  "name": "subaccount-admin",
+  "description": "Full administrative access",
+  "free": false,
+  "bindable": true,
+  "service_offering_id": "offering-id",
+  "catalog_id": "catalog-id",
+  "catalog_name": "subaccount-admin",
+  "metadata": {}
+}
+```
+
+---
+
+### 6. Service Offerings API
+
+**Base**: `/v1/service_offerings`
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/v1/service_offerings` | List all offerings |
+| GET | `/v1/service_offerings/{offeringID}` | Get specific offering |
+
+**Offering Response**:
+```json
+{
+  "id": "offering-id",
+  "name": "service-manager",
+  "description": "SAP Service Manager",
+  "bindable": true,
+  "broker_id": "broker-id",
+  "catalog_id": "catalog-id",
+  "catalog_name": "service-manager"
+}
+```
+
+---
+
+### 7. Operations API
+
+**Base**: `/v1/{resourceType}/{resourceID}/operations`
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/v1/{type}/{id}/operations/{opID}` | Get operation status |
+
+**Path Parameters**:
+- `resourceType`: `platforms`, `service_brokers`, `service_bindings`, `service_instances`
+- `resourceID`: Resource identifier
+- `operationID`: Operation identifier
+
+**Operation Response**:
+```json
+{
+  "id": "operation-id",
+  "type": "create",
+  "state": "in progress",
+  "resource_id": "resource-id",
+  "resource_type": "service_instances",
+  "description": "Provisioning service instance",
+  "created_at": "2025-01-01T00:00:00Z",
+  "updated_at": "2025-01-01T00:00:00Z"
+}
+```
+
+**Operation States**:
+- `in progress` - Operation running
+- `succeeded` - Operation completed successfully
+- `failed` - Operation failed
+
+---
+
+## HTTP Status Codes
+
+| Code | Description |
+|------|-------------|
+| 200 | Success |
+| 201 | Created |
+| 202 | Accepted (async operation started) |
+| 400 | Bad request (invalid parameters) |
+| 401 | Unauthorized (invalid/missing token) |
+| 403 | Forbidden (insufficient permissions) |
+| 404 | Not found |
+| 409 | Conflict (resource already exists) |
+| 422 | Unprocessable entity |
+| 429 | Rate limit exceeded |
+| 500 | Internal server error |
+
+---
+
+## Async Operations
+
+POST, PATCH, and DELETE operations on instances and bindings are async by default.
+
+**Response** (202 Accepted):
+```json
+{
+  "id": "resource-id",
+  "last_operation": {
+    "type": "create",
+    "state": "in progress"
+  }
+}
+```
+
+**Headers**:
+- `Location`: `/v1/service_instances/{id}/operations/{opId}` - Poll this URL
+
+**Polling**:
+```bash
+# Initial request
+POST /v1/service_instances
+# Response: 202 with Location header
+
+# Poll status
+GET /v1/service_instances/{id}/operations/{opId}
+# Repeat until state is "succeeded" or "failed"
+```
+
+---
+
+## Swagger UI
+
+Access interactive API documentation:
+
+`[https://service-manager.cfapps.<region>.hana.ondemand.com/swaggerui/swagger-ui.html`](https://service-manager.cfapps.<region>.hana.ondemand.com/swaggerui/swagger-ui.html`)
+
+**Example Regions**:
+- EU10 (Frankfurt): `eu10.hana.ondemand.com`
+- US10 (US East): `us10.hana.ondemand.com`
+- AP10 (Australia): `ap10.hana.ondemand.com`
+
+---
+
+## Documentation Links
+
+- **API Groups**: [https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/sap-service-manager-api-groups-9b97aee.md](https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/sap-service-manager-api-groups-9b97aee.md)
+- **Service Instances**: [https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/instances-23af00d.md](https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/instances-23af00d.md)
+- **Service Bindings**: [https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/service-bindings-392eb36.md](https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/service-bindings-392eb36.md)
+- **Platforms**: [https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/platforms-7610c08.md](https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/platforms-7610c08.md)
+- **Brokers**: [https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/brokers-743f3f7.md](https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/brokers-743f3f7.md)