zhongwei/gh-secondsky-sap-skills-skills-sap-btp-service-manager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
gh-secondsky-sap-skills-ski…/references/api-reference.md
Zhongwei Li 0e7a2dc56e Initial commit
2025-11-30 08:55:15 +08:00

403 lines
11 KiB
Markdown
Raw Permalink Blame History

# 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)
Reference in New Issue View Git Blame Copy Permalink