307 lines
7.7 KiB
Markdown
307 lines
7.7 KiB
Markdown
# SAP Build Work Zone API Reference
|
|
|
|
Complete API reference for SCIM, OData, and Webhook APIs in SAP Build Work Zone, advanced edition.
|
|
|
|
**Source**: [https://github.com/SAP-docs/sap-btp-build-work-zone-advanced](https://github.com/SAP-docs/sap-btp-build-work-zone-advanced)
|
|
|
|
## Table of Contents
|
|
|
|
- [API Documentation Resources](#api-documentation-resources)
|
|
- [SCIM API](#scim-api)
|
|
- [Overview](#overview-scim)
|
|
- [Rate Limits](#rate-limits)
|
|
- [Response Headers](#response-headers)
|
|
- [Content Type](#content-type)
|
|
- [User Filtering](#user-filtering)
|
|
- [SCIM Operations](#scim-operations)
|
|
- [User Lists](#user-lists)
|
|
- [Maintenance Windows](#maintenance-windows)
|
|
- [OData API](#odata-api)
|
|
- [Overview](#overview-odata)
|
|
- [Authentication](#authentication)
|
|
- [Key Endpoints](#key-endpoints)
|
|
- [Query Options](#query-options)
|
|
- [Business Records](#business-records)
|
|
- [Webhooks](#webhooks)
|
|
- [Overview](#overview-webhooks)
|
|
- [Webhook URL Format](#webhook-url-format)
|
|
- [Configuration](#configuration)
|
|
- [Event Types](#event-types)
|
|
- [Payload Structure](#payload-structure)
|
|
- [Chatbot API](#chatbot-api)
|
|
- [Available Template Variables](#available-template-variables)
|
|
- [Webhook Actions](#webhook-actions)
|
|
- [Create Workspace Example](#create-workspace-example)
|
|
- [Render Card Example](#render-card-example)
|
|
- [Authentication](#authentication-main)
|
|
- [OAuth 2.0 Setup](#oauth-20-setup)
|
|
- [Token Request](#token-request)
|
|
- [API Request](#api-request)
|
|
- [Alias Accounts](#alias-accounts)
|
|
|
|
---
|
|
|
|
## API Documentation Resources
|
|
|
|
| Resource | URL |
|
|
|----------|-----|
|
|
| SAP API Hub | [https://api.sap.com/](https://api.sap.com/) (SAP Cloud Portal Service) |
|
|
| OData API Docs | [https://jam2.sapjam.com/work_zone/ODataDocs/ui](https://jam2.sapjam.com/work_zone/ODataDocs/ui) |
|
|
| Webhook Reference | [https://jam2.sapjam.com/work_zone/ODataDocs/webhook_reference](https://jam2.sapjam.com/work_zone/ODataDocs/webhook_reference) |
|
|
|
|
---
|
|
|
|
## SCIM API
|
|
|
|
### Overview {#overview-scim}
|
|
|
|
SAP Build Work Zone implements SCIM 2.0 for user provisioning.
|
|
|
|
**Endpoint**: `/api/v1/scim`
|
|
|
|
**Authentication**: 2-legged OAuth using "Workzone API Client"
|
|
|
|
### Rate Limits
|
|
|
|
| Limit Type | Value |
|
|
|------------|-------|
|
|
| Hourly limit | 10,000 requests/tenant |
|
|
| Burst limit | 200 requests/minute |
|
|
|
|
### Response Headers
|
|
|
|
| Header | Description |
|
|
|--------|-------------|
|
|
| `X-RateLimit-Limit` | Maximum hourly requests |
|
|
| `X-RateLimit-Remaining` | Available requests |
|
|
| `X-RateLimit-Reset` | Seconds until reset |
|
|
|
|
### Content Type
|
|
|
|
All POST/PUT requests require:
|
|
```
|
|
Content-Type: application/json
|
|
```
|
|
|
|
### User Filtering
|
|
|
|
Supported filter: `SCIM.userName eq <value>`
|
|
|
|
### SCIM Operations
|
|
|
|
| Operation | Endpoint | Method |
|
|
|-----------|----------|--------|
|
|
| List Users | `/api/v1/scim/Users` | GET |
|
|
| Get User | `/api/v1/scim/Users/{id}` | GET |
|
|
| Create User | `/api/v1/scim/Users` | POST |
|
|
| Update User | `/api/v1/scim/Users/{id}` | PUT |
|
|
| Delete User | `/api/v1/scim/Users/{id}` | DELETE |
|
|
|
|
### User Lists
|
|
|
|
| Operation | Endpoint | Method |
|
|
|-----------|----------|--------|
|
|
| List User Lists | `/api/v1/scim/Groups` | GET |
|
|
| Get User List | `/api/v1/scim/Groups/{id}` | GET |
|
|
| Create User List | `/api/v1/scim/Groups` | POST |
|
|
| Update User List | `/api/v1/scim/Groups/{id}` | PUT |
|
|
|
|
### Maintenance Windows
|
|
|
|
During maintenance, API returns:
|
|
```
|
|
HTTP 503 Service Unavailable
|
|
```
|
|
|
|
---
|
|
|
|
## OData API
|
|
|
|
### Overview {#overview-odata}
|
|
|
|
SAP Build Work Zone uses OData v2 protocol with support for OData v4 query syntax (e.g., advanced `$filter`, `$select` expressions).
|
|
|
|
**Protocol**: OData v2 (with v4 query operator extensions)
|
|
|
|
**Format**: XML (AtomPub) or JSON
|
|
|
|
**Base URL**: `/api/v1/OData`
|
|
|
|
### Authentication {#authentication}
|
|
|
|
Same OAuth flow as SCIM API.
|
|
|
|
### Key Endpoints
|
|
|
|
| Resource | Endpoint | Description |
|
|
|----------|----------|-------------|
|
|
| Groups | `/api/v1/OData/Groups` | Workspace management |
|
|
| Members | `/api/v1/OData/Members` | User management |
|
|
| ContentItems | `/api/v1/OData/ContentItems` | Content operations |
|
|
| Feeds | `/api/v1/OData/Feeds` | Feed operations |
|
|
| FeedEntries | `/api/v1/OData/FeedEntries` | Feed entries |
|
|
|
|
### Query Options
|
|
|
|
| Option | Example |
|
|
|--------|---------|
|
|
| $select | `$select=Id,Name` |
|
|
| $filter | `$filter=Name eq 'Value'` |
|
|
| $orderby | `$orderby=Created desc` |
|
|
| $top | `$top=10` |
|
|
| $skip | `$skip=20` |
|
|
| $expand | `$expand=Members` |
|
|
|
|
### Business Records
|
|
|
|
Configure OData annotations to display external business records:
|
|
|
|
1. Create OData metadata file with annotations
|
|
2. Register in Administration Console
|
|
3. Configure display annotations
|
|
4. Map to business record types
|
|
|
|
---
|
|
|
|
## Webhooks
|
|
|
|
### Overview {#overview-webhooks}
|
|
|
|
Track platform events and send notifications to external applications.
|
|
|
|
### Webhook URL Format
|
|
|
|
```
|
|
[https://<host-url>/api/v2/ai/webhook](https://<host-url>/api/v2/ai/webhook)
|
|
```
|
|
|
|
### Configuration
|
|
|
|
1. Register webhook URL in Administration Console
|
|
2. Configure events to monitor
|
|
3. Set authentication tokens
|
|
4. Test webhook delivery
|
|
|
|
### Event Types
|
|
|
|
| Category | Events |
|
|
|----------|--------|
|
|
| Workspace | Created, updated, deleted |
|
|
| Content | Created, modified, deleted |
|
|
| User | Joined, left, updated |
|
|
| Feed | Posted, commented, liked |
|
|
|
|
### Payload Structure
|
|
|
|
```json
|
|
{
|
|
"action": "perform_actions",
|
|
"context": {
|
|
"senderId": "user_id"
|
|
},
|
|
"parameters": {
|
|
// Event-specific parameters
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Chatbot API
|
|
|
|
### Available Template Variables
|
|
|
|
When configuring chatbot webhooks, the following template variables are available:
|
|
|
|
| Variable | Description |
|
|
|----------|-------------|
|
|
| `{{participant_data.jamId}}` | Current user's Jam/Work Zone ID |
|
|
| `{{participant_data.email}}` | Current user's email address |
|
|
| `{{participant_data.firstName}}` | Current user's first name |
|
|
| `{{participant_data.lastName}}` | Current user's last name |
|
|
| `{{conversation_id}}` | Current conversation identifier |
|
|
| `{{memory.variableName}}` | Custom memory variable from bot |
|
|
|
|
### Webhook Actions
|
|
|
|
| Action | Description |
|
|
|--------|-------------|
|
|
| `perform_actions` | Execute platform actions |
|
|
| `ui5_card` | Render UI Integration Cards |
|
|
|
|
### Create Workspace Example
|
|
|
|
```json
|
|
{
|
|
"action": "perform_actions",
|
|
"context": { "senderId": "{{participant_data.jamId}}" },
|
|
"parameters": {
|
|
"actionName": "create_workspace",
|
|
"name": "Workspace Name",
|
|
"is_private": false
|
|
}
|
|
}
|
|
```
|
|
|
|
### Render Card Example
|
|
|
|
```json
|
|
{
|
|
"action": "ui5_card",
|
|
"context": { "senderId": "{{participant_data.jamId}}" },
|
|
"parameters": {
|
|
"cardId": "sap.card.id",
|
|
"widgetType": "sapCard"
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Authentication {#authentication-main}
|
|
|
|
### OAuth 2.0 Setup
|
|
|
|
1. Create OAuth client in Administration Console
|
|
2. Configure client credentials grant
|
|
3. Obtain access token
|
|
4. Include in Authorization header
|
|
|
|
### Token Request
|
|
|
|
```http
|
|
POST /oauth/token
|
|
Content-Type: application/x-www-form-urlencoded
|
|
|
|
grant_type=client_credentials
|
|
&client_id={client_id}
|
|
&client_secret={client_secret}
|
|
```
|
|
|
|
### API Request
|
|
|
|
```http
|
|
GET /api/v1/OData/Groups
|
|
Authorization: Bearer {access_token}
|
|
```
|
|
|
|
---
|
|
|
|
## Alias Accounts
|
|
|
|
For system-level API access:
|
|
|
|
1. Create alias account in Administration Console
|
|
2. Navigate to API Access section
|
|
3. Add OAuth2 Access Token
|
|
4. Select OAuth client
|
|
5. Use token for automated API calls
|
|
|
|
---
|
|
|
|
**Documentation Links**:
|
|
- SAP API Hub: [https://api.sap.com/](https://api.sap.com/)
|
|
- OData Docs: [https://jam2.sapjam.com/work_zone/ODataDocs/ui](https://jam2.sapjam.com/work_zone/ODataDocs/ui)
|
|
- Webhook Reference: [https://jam2.sapjam.com/work_zone/ODataDocs/webhook_reference](https://jam2.sapjam.com/work_zone/ODataDocs/webhook_reference)
|
|
- SAP Help Portal: [https://help.sap.com/docs/build-work-zone-advanced-edition](https://help.sap.com/docs/build-work-zone-advanced-edition)
|