[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M699G8V718EXYE8BR7NX734G":3,"skill-same:01M699G8V718EXYE8BR7NX734G":78},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":28,"publishedAt":44,"linkOnly":45,"markdownContent":46,"markdownBody":47,"frontMatter":48,"refName":49,"commitSha":50,"skillDirectory":51,"forksCount":52,"repositoryHtmlUrl":53,"repositoryHomepageUrl":6,"ownerHtmlUrl":54,"ownerBlogUrl":55,"ownerDescription":56,"updatedAt":57,"install":58,"resources":71},"01M699G8V718EXYE8BR7NX734G","rest-api-patterns",null,"Guide for implementing REST API wrapper functions. Use this when adding new API wrappers or troubleshooting API calls.","microsoft\u002Fsemantic-link-labs","microsoft","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F6154722?v=4","01M698VYDXZ6JW5WH3CRV650R8","Microsoft","01M699FKMT63C17BFNH8WHZN2K",600,"MIT","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fsemantic-link-labs\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Frest-api-patterns\u002FSKILL.md",[18,23],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000010","后端与接口","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":26,"taxonomyTypeDesc":27},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[29,30,31,32,33,34,35,36,37,38,39,40,41,42,43],"rest api patterns","REST","api patterns","api","patterns","rest api","troubleshooting","guide","use","Wrapper","functions","calls","implementing","for","when","2026-11-10 10:12:30",false,"---\nname: rest-api-patterns\ndescription: Guide for implementing REST API wrapper functions. Use this when adding new API wrappers or troubleshooting API calls.\n---\n\n# REST API Patterns\n\nThis skill covers the patterns and utilities for implementing REST API wrapper functions in Semantic Link Labs.\n\n## When to Use This Skill\n\nUse this skill when you need to:\n- Implement new REST API wrappers\n- Understand the `_base_api` helper function\n- Handle pagination, long-running operations, or errors\n- Debug API-related issues\n\n---\n\n## Finding API Documentation\n\nBefore implementing a wrapper, use the API search tool to find the relevant documentation:\n\n### Using `search_public_api_doc.py`\n\n```bash\n# Navigate to the scripts directory\ncd .claude\u002Fskills\u002Frest-api-patterns\u002Fscripts\n\n# Search both Fabric and Power BI APIs\npython search_public_api_doc.py \"dataset refresh\"\n\n# Search Fabric APIs only\npython search_public_api_doc.py \"create item\" --source fabric\n\n# Search Power BI APIs only\npython search_public_api_doc.py \"gateway\" --source powerbi\n\n# Limit results\npython search_public_api_doc.py \"workspace\" --limit 10\n```\n\n### Example Output\n\n```\n? Searching for: 'dataset refresh' in Fabric + Power BI\n================================================================================\n? Fetching Microsoft Fabric TOC...\n   ✅ Loaded 15 top-level categories from Microsoft Fabric\n? Fetching Power BI TOC...\n   ✅ Loaded 20 top-level categories from Power BI\n\nFound 5 results:\n\n1. [POWERBI] Datasets - Refresh Dataset In Group (score: 95.0)\n   URL: https:\u002F\u002Flearn.microsoft.com\u002Fen-us\u002Frest\u002Fapi\u002Fpower-bi\u002Fdatasets\u002Frefresh-dataset-in-group\n   Path: Datasets > Refresh Dataset In Group\n\n2. [POWERBI] Datasets - Get Refresh History In Group (score: 90.0)\n   URL: https:\u002F\u002Flearn.microsoft.com\u002Fen-us\u002Frest\u002Fapi\u002Fpower-bi\u002Fdatasets\u002Fget-refresh-history-in-group\n   Path: Datasets > Get Refresh History In Group\n```\n\n### Requirements\n\nThe script requires `rapidfuzz` and `requests`:\n\n```bash\npip install rapidfuzz requests\n```\n\n### API Documentation References\n\n| API | Base URL | Documentation |\n|-----|----------|---------------|\n| Fabric REST API | `https:\u002F\u002Fapi.fabric.microsoft.com\u002Fv1\u002F` | [Fabric REST API](https:\u002F\u002Flearn.microsoft.com\u002Frest\u002Fapi\u002Ffabric\u002F) |\n| Power BI REST API | `https:\u002F\u002Fapi.powerbi.com\u002Fv1.0\u002Fmyorg\u002F` | [Power BI REST API](https:\u002F\u002Flearn.microsoft.com\u002Frest\u002Fapi\u002Fpower-bi\u002F) |\n\n---\n\n## API Client Architecture\n\nSemantic Link Labs uses `sempy.fabric.FabricRestClient` as the underlying HTTP client, wrapped by the `_base_api` helper function.\n\n### Key Components\n\n| Component | Purpose |\n|-----------|---------|\n| `_base_api` | Main helper for all API calls |\n| `FabricRestClient` | HTTP client from sempy |\n| `pagination` | Handles paginated responses |\n| `lro` | Handles long-running operations |\n\n---\n\n## The `_base_api` Function\n\nLocated in `src\u002Fsempy_labs\u002F_helper_functions.py`, this is the standard way to make API calls.\n\n### Function Signature\n\n```python\ndef _base_api(\n    request: str,                      # API endpoint path\n    client: str = \"fabric\",            # Client type\n    method: str = \"get\",               # HTTP method\n    payload: Optional[str] = None,     # Request body\n    status_codes: Optional[int] = 200, # Expected status codes\n    uses_pagination: bool = False,     # Enable pagination\n    lro_return_json: bool = False,     # Wait for LRO, return JSON\n    lro_return_status_code: bool = False,  # Wait for LRO, return status\n    lro_return_df: bool = False,       # Wait for LRO, return DataFrame\n):\n```\n\n### Client Types\n\n| Client | Use Case | Authentication |\n|--------|----------|----------------|\n| `fabric` | Standard Fabric API | Default notebook credentials |\n| `fabric_sp` | Fabric API with SP support | Service Principal or default |\n| `azure` | Azure Resource Manager | Service Principal |\n| `graph` | Microsoft Graph | Service Principal |\n| `onelake` | OneLake storage | Storage token |\n\n### Return Types\n\n**The `_base_api` function returns different types depending on the parameters used:**\n\n| Parameters | Return Type | How to Access Data |\n|------------|-------------|-------------------|\n| Default (no special flags) | `Response` object | Call `.json()` to get dict |\n| `uses_pagination=True` | `list[dict]` | Iterate over list, each item has `.get(\"value\", [])` |\n| `lro_return_json=True` | `dict` | Access directly, already parsed JSON |\n| `lro_return_status_code=True` | `int` | HTTP status code |\n| `lro_return_df=True` | `DataFrame` | Use directly |\n\n**⚠️ COMMON MISTAKE:** Forgetting to call `.json()` on the response for simple GET requests.\n\n```python\n# ❌ WRONG - response is a Response object, not a dict\nresponse = _base_api(request=f\"\u002Fv1\u002Fworkspaces\u002F{workspace_id}\u002Fitems\u002F{item_id}\")\nname = response.get(\"displayName\")  # AttributeError: 'Response' object has no attribute 'get'\n\n# ✅ CORRECT - call .json() to get the dict\nresponse = _base_api(request=f\"\u002Fv1\u002Fworkspaces\u002F{workspace_id}\u002Fitems\u002F{item_id}\").json()\nname = response.get(\"displayName\")  # Works!\n```\n\n---\n\n## Common API Patterns\n\n### Simple GET Request\n\n```python\nfrom sempy_labs._helper_functions import _base_api\n\nresponse = _base_api(\n    request=f\"\u002Fv1\u002Fworkspaces\u002F{workspace_id}\u002Fitems\",\n    client=\"fabric_sp\",\n)\n\ndata = response.json()\n```\n\n### POST Request with Payload\n\n```python\npayload = {\n    \"displayName\": name,\n    \"description\": description,\n}\n\nresponse = _base_api(\n    request=f\"\u002Fv1\u002Fworkspaces\u002F{workspace_id}\u002Fitems\",\n    method=\"post\",\n    payload=payload,\n    status_codes=[201, 202],\n    client=\"fabric_sp\",\n)\n```\n\n### DELETE Request\n\n```python\n_base_api(\n    request=f\"\u002Fv1\u002Fworkspaces\u002F{workspace_id}\u002Fitems\u002F{item_id}\",\n    method=\"delete\",\n    client=\"fabric_sp\",\n)\n```\n\n### PATCH Request\n\n```python\npayload = {\n    \"displayName\": new_name,\n}\n\n_base_api(\n    request=f\"\u002Fv1\u002Fworkspaces\u002F{workspace_id}\u002Fitems\u002F{item_id}\",\n    method=\"patch\",\n    payload=payload,\n    client=\"fabric_sp\",\n)\n```\n\n---\n\n## Handling Pagination\n\nFor APIs that return paginated results:\n\n```python\nfrom sempy_labs._helper_functions import _base_api, _create_dataframe\n\ncolumns = {\n    \"Id\": \"string\",\n    \"Name\": \"string\",\n}\ndf = _create_dataframe(columns=columns)\n\n# Get all pages\nresponses = _base_api(\n    request=f\"\u002Fv1\u002Fworkspaces\u002F{workspace_id}\u002Fitems\",\n    uses_pagination=True,\n    client=\"fabric_sp\",\n)\n\n# Process all responses\nrows = []\nfor r in responses:\n    for item in r.get(\"value\", []):\n        rows.append({\n            \"Id\": item.get(\"id\"),\n            \"Name\": item.get(\"displayName\"),\n        })\n\nif rows:\n    df = pd.DataFrame(rows)\n\nreturn df\n```\n\n---\n\n## Handling Long-Running Operations (LRO)\n\nSome APIs return 202 Accepted and require polling for completion.\n\n### Return JSON When Complete\n\n```python\nresult = _base_api(\n    request=f\"\u002Fv1\u002Fworkspaces\u002F{workspace_id}\u002Fitems\u002F{item_id}\u002FgetDefinition\",\n    method=\"post\",\n    lro_return_json=True,\n    client=\"fabric_sp\",\n)\n\n# Result contains the final JSON response\ndefinition = result.get(\"definition\")\n```\n\n### Return Status Code\n\n```python\nstatus = _base_api(\n    request=f\"\u002Fv1\u002Fworkspaces\u002F{workspace_id}\u002Fitems\",\n    method=\"post\",\n    payload=payload,\n    lro_return_status_code=True,\n    client=\"fabric_sp\",\n)\n\n# status is the final HTTP status code\nif status == 200:\n    print(\"Operation completed successfully\")\n```\n\n---\n\n## Error Handling\n\n### Expected Status Codes\n\nSpecify expected status codes to avoid exceptions:\n\n```python\n# Accept 200, 201, or 202 as success\nresponse = _base_api(\n    request=url,\n    method=\"post\",\n    payload=payload,\n    status_codes=[200, 201, 202],\n    client=\"fabric_sp\",\n)\n```\n\n### FabricHTTPException\n\nWhen status code doesn't match, `FabricHTTPException` is raised:\n\n```python\nfrom sempy.fabric.exceptions import FabricHTTPException\n\ntry:\n    response = _base_api(\n        request=f\"\u002Fv1\u002Fworkspaces\u002F{workspace_id}\u002Fitems\u002F{item_id}\",\n        client=\"fabric_sp\",\n    )\nexcept FabricHTTPException as e:\n    if e.response.status_code == 404:\n        print(f\"Item not found\")\n    else:\n        raise\n```\n\n---\n\n## Building URLs with Parameters\n\nUse the `_build_url` helper for query parameters:\n\n```python\nfrom sempy_labs._helper_functions import _build_url\n\nurl = \"\u002Fv1\u002Fadmin\u002Fworkspaces\"\nparams = {\n    \"capacityId\": capacity_id,\n    \"state\": \"Active\",\n}\n\nurl = _build_url(url, params)\n# Result: \"\u002Fv1\u002Fadmin\u002Fworkspaces?capacityId=xxx&state=Active\"\n\nresponses = _base_api(\n    request=url,\n    uses_pagination=True,\n    client=\"fabric_sp\",\n)\n```\n\n---\n\n## API Endpoint Patterns\n\n### Fabric Core API\n\n```python\n# List items in workspace\nf\"\u002Fv1\u002Fworkspaces\u002F{workspace_id}\u002Fitems\"\n\n# Get specific item\nf\"\u002Fv1\u002Fworkspaces\u002F{workspace_id}\u002Fitems\u002F{item_id}\"\n\n# Item operations\nf\"\u002Fv1\u002Fworkspaces\u002F{workspace_id}\u002Fitems\u002F{item_id}\u002FgetDefinition\"\nf\"\u002Fv1\u002Fworkspaces\u002F{workspace_id}\u002Fitems\u002F{item_id}\u002FupdateDefinition\"\n```\n\n### Fabric Admin API\n\n```python\n# Admin workspaces\n\"\u002Fv1\u002Fadmin\u002Fworkspaces\"\n\n# Admin items\n\"\u002Fv1\u002Fadmin\u002Fitems\"\n\n# Capacities\n\"\u002Fv1\u002Fadmin\u002Fcapacities\"\n```\n\n### Power BI REST API\n\n```python\n# Groups (workspaces)\nf\"\u002Fv1.0\u002Fmyorg\u002Fgroups\u002F{workspace_id}\u002F...\"\n\n# Datasets\nf\"\u002Fv1.0\u002Fmyorg\u002Fgroups\u002F{workspace_id}\u002Fdatasets\u002F{dataset_id}\u002F...\"\n\n# Reports\nf\"\u002Fv1.0\u002Fmyorg\u002Fgroups\u002F{workspace_id}\u002Freports\u002F{report_id}\u002F...\"\n```\n\n### Azure Resource Manager\n\n```python\n# Fabric capacities\nf\"https:\u002F\u002Fmanagement.azure.com\u002Fsubscriptions\u002F{subscription_id}\u002Fproviders\u002FMicrosoft.Fabric\u002Fcapacities\"\n\n# Resource groups\nf\"https:\u002F\u002Fmanagement.azure.com\u002Fsubscriptions\u002F{subscription_id}\u002FresourceGroups\u002F{resource_group}\"\n```\n\n---\n\n## Authentication Headers\n\nFor non-Fabric clients (Azure, Graph), use `_get_headers`:\n\n```python\nfrom sempy_labs._authentication import _get_headers\nimport sempy_labs._authentication as auth\n\nheaders = _get_headers(auth.token_provider.get(), audience=\"azure\")\n\nresponse = requests.get(\n    url,\n    headers=headers,\n)\n```\n\n---\n\n## Creating Result DataFrames\n\nUse `_create_dataframe` for consistent empty DataFrames:\n\n```python\nfrom sempy_labs._helper_functions import _create_dataframe\n\ncolumns = {\n    \"Id\": \"string\",\n    \"Name\": \"string\",\n    \"Type\": \"string\",\n    \"Created Date\": \"datetime\",\n    \"Size\": \"int\",\n}\n\ndf = _create_dataframe(columns=columns)\n```\n\n### Updating DataFrame Types\n\n```python\nfrom sempy_labs._helper_functions import _update_dataframe_datatypes\n\ncolumn_map = {\n    \"Created Date\": \"datetime\",\n    \"Size\": \"int\",\n    \"Is Active\": \"bool\",\n}\n\n_update_dataframe_datatypes(df, column_map)\n```\n\n---\n\n## Complete Example\n\n```python\nfrom sempy._utils._log import log\nfrom sempy_labs._helper_functions import (\n    resolve_workspace_name_and_id,\n    _base_api,\n    _create_dataframe,\n    _build_url,\n)\nimport sempy_labs._icons as icons\nfrom typing import Optional\nfrom uuid import UUID\nimport pandas as pd\n\n\n@log\ndef list_my_items(\n    item_type: Optional[str] = None,\n    workspace: Optional[str | UUID] = None,\n) -> pd.DataFrame:\n    \"\"\"\n    Lists items in a workspace.\n\n    This is a wrapper function for the following API: `Items - List Items \u003Chttps:\u002F\u002Flearn.microsoft.com\u002Frest\u002Fapi\u002Ffabric\u002Fcore\u002Fitems\u002Flist-items>`_.\n\n    Service Principal Authentication is supported.\n\n    Parameters\n    ----------\n    item_type : str, default=None\n        Filter by item type.\n    workspace : str | uuid.UUID, default=None\n        The Fabric workspace name or ID.\n        Defaults to None which resolves to the workspace of the attached lakehouse.\n\n    Returns\n    -------\n    pandas.DataFrame\n        A pandas dataframe showing items in the workspace.\n    \"\"\"\n\n    (workspace_name, workspace_id) = resolve_workspace_name_and_id(workspace)\n\n    columns = {\n        \"Id\": \"string\",\n        \"Name\": \"string\",\n        \"Type\": \"string\",\n    }\n    df = _create_dataframe(columns=columns)\n\n    url = f\"\u002Fv1\u002Fworkspaces\u002F{workspace_id}\u002Fitems\"\n    params = {}\n    if item_type:\n        params[\"type\"] = item_type\n    if params:\n        url = _build_url(url, params)\n\n    responses = _base_api(\n        request=url,\n        uses_pagination=True,\n        client=\"fabric_sp\",\n    )\n\n    rows = []\n    for r in responses:\n        for item in r.get(\"value\", []):\n            rows.append({\n                \"Id\": item.get(\"id\"),\n                \"Name\": item.get(\"displayName\"),\n                \"Type\": item.get(\"type\"),\n            })\n\n    if rows:\n        df = pd.DataFrame(rows)\n\n    return df\n```\n\n---\n\n## Debugging API Calls\n\n### Print Response Details\n\n```python\nresponse = _base_api(\n    request=url,\n    client=\"fabric_sp\",\n)\n\nprint(f\"Status: {response.status_code}\")\nprint(f\"Headers: {response.headers}\")\nprint(f\"Body: {response.json()}\")\n```\n\n### Check Request Being Made\n\nAdd temporary debug prints:\n\n```python\nprint(f\"Making request to: {url}\")\nprint(f\"Payload: {payload}\")\n```\n\n---\n\n## API Documentation References\n\n| API | Documentation |\n|-----|---------------|\n| Fabric Core | [https:\u002F\u002Flearn.microsoft.com\u002Frest\u002Fapi\u002Ffabric\u002Fcore\u002F](https:\u002F\u002Flearn.microsoft.com\u002Frest\u002Fapi\u002Ffabric\u002Fcore\u002F) |\n| Fabric Admin | [https:\u002F\u002Flearn.microsoft.com\u002Frest\u002Fapi\u002Ffabric\u002Fadmin\u002F](https:\u002F\u002Flearn.microsoft.com\u002Frest\u002Fapi\u002Ffabric\u002Fadmin\u002F) |\n| Power BI | [https:\u002F\u002Flearn.microsoft.com\u002Frest\u002Fapi\u002Fpower-bi\u002F](https:\u002F\u002Flearn.microsoft.com\u002Frest\u002Fapi\u002Fpower-bi\u002F) |\n| Azure Fabric | [https:\u002F\u002Flearn.microsoft.com\u002Frest\u002Fapi\u002Fmicrosoftfabric\u002F](https:\u002F\u002Flearn.microsoft.com\u002Frest\u002Fapi\u002Fmicrosoftfabric\u002F) |\n| Graph | [https:\u002F\u002Flearn.microsoft.com\u002Fgraph\u002Fapi\u002Foverview](https:\u002F\u002Flearn.microsoft.com\u002Fgraph\u002Fapi\u002Foverview) |\n","# REST API Patterns\n\nThis skill covers the patterns and utilities for implementing REST API wrapper functions in Semantic Link Labs.\n\n## When to Use This Skill\n\nUse this skill when you need to:\n- Implement new REST API wrappers\n- Understand the `_base_api` helper function\n- Handle pagination, long-running operations, or errors\n- Debug API-related issues\n\n---\n\n## Finding API Documentation\n\nBefore implementing a wrapper, use the API search tool to find the relevant documentation:\n\n### Using `search_public_api_doc.py`\n\n```bash\n# Navigate to the scripts directory\ncd .claude\u002Fskills\u002Frest-api-patterns\u002Fscripts\n\n# Search both Fabric and Power BI APIs\npython search_public_api_doc.py \"dataset refresh\"\n\n# Search Fabric APIs only\npython search_public_api_doc.py \"create item\" --source fabric\n\n# Search Power BI APIs only\npython search_public_api_doc.py \"gateway\" --source powerbi\n\n# Limit results\npython search_public_api_doc.py \"workspace\" --limit 10\n```\n\n### Example Output\n\n```\n? Searching for: 'dataset refresh' in Fabric + Power BI\n================================================================================\n? Fetching Microsoft Fabric TOC...\n   ✅ Loaded 15 top-level categories from Microsoft Fabric\n? Fetching Power BI TOC...\n   ✅ Loaded 20 top-level categories from Power BI\n\nFound 5 results:\n\n1. [POWERBI] Datasets - Refresh Dataset In Group (score: 95.0)\n   URL: https:\u002F\u002Flearn.microsoft.com\u002Fen-us\u002Frest\u002Fapi\u002Fpower-bi\u002Fdatasets\u002Frefresh-dataset-in-group\n   Path: Datasets > Refresh Dataset In Group\n\n2. [POWERBI] Datasets - Get Refresh History In Group (score: 90.0)\n   URL: https:\u002F\u002Flearn.microsoft.com\u002Fen-us\u002Frest\u002Fapi\u002Fpower-bi\u002Fdatasets\u002Fget-refresh-history-in-group\n   Path: Datasets > Get Refresh History In Group\n```\n\n### Requirements\n\nThe script requires `rapidfuzz` and `requests`:\n\n```bash\npip install rapidfuzz requests\n```\n\n### API Documentation References\n\n| API | Base URL | Documentation |\n|-----|----------|---------------|\n| Fabric REST API | `https:\u002F\u002Fapi.fabric.microsoft.com\u002Fv1\u002F` | [Fabric REST API](https:\u002F\u002Flearn.microsoft.com\u002Frest\u002Fapi\u002Ffabric\u002F) |\n| Power BI REST API | `https:\u002F\u002Fapi.powerbi.com\u002Fv1.0\u002Fmyorg\u002F` | [Power BI REST API](https:\u002F\u002Flearn.microsoft.com\u002Frest\u002Fapi\u002Fpower-bi\u002F) |\n\n---\n\n## API Client Architecture\n\nSemantic Link Labs uses `sempy.fabric.FabricRestClient` as the underlying HTTP client, wrapped by the `_base_api` helper function.\n\n### Key Components\n\n| Component | Purpose |\n|-----------|---------|\n| `_base_api` | Main helper for all API calls |\n| `FabricRestClient` | HTTP client from sempy |\n| `pagination` | Handles paginated responses |\n| `lro` | Handles long-running operations |\n\n---\n\n## The `_base_api` Function\n\nLocated in `src\u002Fsempy_labs\u002F_helper_functions.py`, this is the standard way to make API calls.\n\n### Function Signature\n\n```python\ndef _base_api(\n    request: str,                      # API endpoint path\n    client: str = \"fabric\",            # Client type\n    method: str = \"get\",               # HTTP method\n    payload: Optional[str] = None,     # Request body\n    status_codes: Optional[int] = 200, # Expected status codes\n    uses_pagination: bool = False,     # Enable pagination\n    lro_return_json: bool = False,     # Wait for LRO, return JSON\n    lro_return_status_code: bool = False,  # Wait for LRO, return status\n    lro_return_df: bool = False,       # Wait for LRO, return DataFrame\n):\n```\n\n### Client Types\n\n| Client | Use Case | Authentication |\n|--------|----------|----------------|\n| `fabric` | Standard Fabric API | Default notebook credentials |\n| `fabric_sp` | Fabric API with SP support | Service Principal or default |\n| `azure` | Azure Resource Manager | Service Principal |\n| `graph` | Microsoft Graph | Service Principal |\n| `onelake` | OneLake storage | Storage token |\n\n### Return Types\n\n**The `_base_api` function returns different types depending on the parameters used:**\n\n| Parameters | Return Type | How to Access Data |\n|------------|-------------|-------------------|\n| Default (no special flags) | `Response` object | Call `.json()` to get dict |\n| `uses_pagination=True` | `list[dict]` | Iterate over list, each item has `.get(\"value\", [])` |\n| `lro_return_json=True` | `dict` | Access directly, already parsed JSON |\n| `lro_return_status_code=True` | `int` | HTTP status code |\n| `lro_return_df=True` | `DataFrame` | Use directly |\n\n**⚠️ COMMON MISTAKE:** Forgetting to call `.json()` on the response for simple GET requests.\n\n```python\n# ❌ WRONG - response is a Response object, not a dict\nresponse = _base_api(request=f\"\u002Fv1\u002Fworkspaces\u002F{workspace_id}\u002Fitems\u002F{item_id}\")\nname = response.get(\"displayName\")  # AttributeError: 'Response' object has no attribute 'get'\n\n# ✅ CORRECT - call .json() to get the dict\nresponse = _base_api(request=f\"\u002Fv1\u002Fworkspaces\u002F{workspace_id}\u002Fitems\u002F{item_id}\").json()\nname = response.get(\"displayName\")  # Works!\n```\n\n---\n\n## Common API Patterns\n\n### Simple GET Request\n\n```python\nfrom sempy_labs._helper_functions import _base_api\n\nresponse = _base_api(\n    request=f\"\u002Fv1\u002Fworkspaces\u002F{workspace_id}\u002Fitems\",\n    client=\"fabric_sp\",\n)\n\ndata = response.json()\n```\n\n### POST Request with Payload\n\n```python\npayload = {\n    \"displayName\": name,\n    \"description\": description,\n}\n\nresponse = _base_api(\n    request=f\"\u002Fv1\u002Fworkspaces\u002F{workspace_id}\u002Fitems\",\n    method=\"post\",\n    payload=payload,\n    status_codes=[201, 202],\n    client=\"fabric_sp\",\n)\n```\n\n### DELETE Request\n\n```python\n_base_api(\n    request=f\"\u002Fv1\u002Fworkspaces\u002F{workspace_id}\u002Fitems\u002F{item_id}\",\n    method=\"delete\",\n    client=\"fabric_sp\",\n)\n```\n\n### PATCH Request\n\n```python\npayload = {\n    \"displayName\": new_name,\n}\n\n_base_api(\n    request=f\"\u002Fv1\u002Fworkspaces\u002F{workspace_id}\u002Fitems\u002F{item_id}\",\n    method=\"patch\",\n    payload=payload,\n    client=\"fabric_sp\",\n)\n```\n\n---\n\n## Handling Pagination\n\nFor APIs that return paginated results:\n\n```python\nfrom sempy_labs._helper_functions import _base_api, _create_dataframe\n\ncolumns = {\n    \"Id\": \"string\",\n    \"Name\": \"string\",\n}\ndf = _create_dataframe(columns=columns)\n\n# Get all pages\nresponses = _base_api(\n    request=f\"\u002Fv1\u002Fworkspaces\u002F{workspace_id}\u002Fitems\",\n    uses_pagination=True,\n    client=\"fabric_sp\",\n)\n\n# Process all responses\nrows = []\nfor r in responses:\n    for item in r.get(\"value\", []):\n        rows.append({\n            \"Id\": item.get(\"id\"),\n            \"Name\": item.get(\"displayName\"),\n        })\n\nif rows:\n    df = pd.DataFrame(rows)\n\nreturn df\n```\n\n---\n\n## Handling Long-Running Operations (LRO)\n\nSome APIs return 202 Accepted and require polling for completion.\n\n### Return JSON When Complete\n\n```python\nresult = _base_api(\n    request=f\"\u002Fv1\u002Fworkspaces\u002F{workspace_id}\u002Fitems\u002F{item_id}\u002FgetDefinition\",\n    method=\"post\",\n    lro_return_json=True,\n    client=\"fabric_sp\",\n)\n\n# Result contains the final JSON response\ndefinition = result.get(\"definition\")\n```\n\n### Return Status Code\n\n```python\nstatus = _base_api(\n    request=f\"\u002Fv1\u002Fworkspaces\u002F{workspace_id}\u002Fitems\",\n    method=\"post\",\n    payload=payload,\n    lro_return_status_code=True,\n    client=\"fabric_sp\",\n)\n\n# status is the final HTTP status code\nif status == 200:\n    print(\"Operation completed successfully\")\n```\n\n---\n\n## Error Handling\n\n### Expected Status Codes\n\nSpecify expected status codes to avoid exceptions:\n\n```python\n# Accept 200, 201, or 202 as success\nresponse = _base_api(\n    request=url,\n    method=\"post\",\n    payload=payload,\n    status_codes=[200, 201, 202],\n    client=\"fabric_sp\",\n)\n```\n\n### FabricHTTPException\n\nWhen status code doesn't match, `FabricHTTPException` is raised:\n\n```python\nfrom sempy.fabric.exceptions import FabricHTTPException\n\ntry:\n    response = _base_api(\n        request=f\"\u002Fv1\u002Fworkspaces\u002F{workspace_id}\u002Fitems\u002F{item_id}\",\n        client=\"fabric_sp\",\n    )\nexcept FabricHTTPException as e:\n    if e.response.status_code == 404:\n        print(f\"Item not found\")\n    else:\n        raise\n```\n\n---\n\n## Building URLs with Parameters\n\nUse the `_build_url` helper for query parameters:\n\n```python\nfrom sempy_labs._helper_functions import _build_url\n\nurl = \"\u002Fv1\u002Fadmin\u002Fworkspaces\"\nparams = {\n    \"capacityId\": capacity_id,\n    \"state\": \"Active\",\n}\n\nurl = _build_url(url, params)\n# Result: \"\u002Fv1\u002Fadmin\u002Fworkspaces?capacityId=xxx&state=Active\"\n\nresponses = _base_api(\n    request=url,\n    uses_pagination=True,\n    client=\"fabric_sp\",\n)\n```\n\n---\n\n## API Endpoint Patterns\n\n### Fabric Core API\n\n```python\n# List items in workspace\nf\"\u002Fv1\u002Fworkspaces\u002F{workspace_id}\u002Fitems\"\n\n# Get specific item\nf\"\u002Fv1\u002Fworkspaces\u002F{workspace_id}\u002Fitems\u002F{item_id}\"\n\n# Item operations\nf\"\u002Fv1\u002Fworkspaces\u002F{workspace_id}\u002Fitems\u002F{item_id}\u002FgetDefinition\"\nf\"\u002Fv1\u002Fworkspaces\u002F{workspace_id}\u002Fitems\u002F{item_id}\u002FupdateDefinition\"\n```\n\n### Fabric Admin API\n\n```python\n# Admin workspaces\n\"\u002Fv1\u002Fadmin\u002Fworkspaces\"\n\n# Admin items\n\"\u002Fv1\u002Fadmin\u002Fitems\"\n\n# Capacities\n\"\u002Fv1\u002Fadmin\u002Fcapacities\"\n```\n\n### Power BI REST API\n\n```python\n# Groups (workspaces)\nf\"\u002Fv1.0\u002Fmyorg\u002Fgroups\u002F{workspace_id}\u002F...\"\n\n# Datasets\nf\"\u002Fv1.0\u002Fmyorg\u002Fgroups\u002F{workspace_id}\u002Fdatasets\u002F{dataset_id}\u002F...\"\n\n# Reports\nf\"\u002Fv1.0\u002Fmyorg\u002Fgroups\u002F{workspace_id}\u002Freports\u002F{report_id}\u002F...\"\n```\n\n### Azure Resource Manager\n\n```python\n# Fabric capacities\nf\"https:\u002F\u002Fmanagement.azure.com\u002Fsubscriptions\u002F{subscription_id}\u002Fproviders\u002FMicrosoft.Fabric\u002Fcapacities\"\n\n# Resource groups\nf\"https:\u002F\u002Fmanagement.azure.com\u002Fsubscriptions\u002F{subscription_id}\u002FresourceGroups\u002F{resource_group}\"\n```\n\n---\n\n## Authentication Headers\n\nFor non-Fabric clients (Azure, Graph), use `_get_headers`:\n\n```python\nfrom sempy_labs._authentication import _get_headers\nimport sempy_labs._authentication as auth\n\nheaders = _get_headers(auth.token_provider.get(), audience=\"azure\")\n\nresponse = requests.get(\n    url,\n    headers=headers,\n)\n```\n\n---\n\n## Creating Result DataFrames\n\nUse `_create_dataframe` for consistent empty DataFrames:\n\n```python\nfrom sempy_labs._helper_functions import _create_dataframe\n\ncolumns = {\n    \"Id\": \"string\",\n    \"Name\": \"string\",\n    \"Type\": \"string\",\n    \"Created Date\": \"datetime\",\n    \"Size\": \"int\",\n}\n\ndf = _create_dataframe(columns=columns)\n```\n\n### Updating DataFrame Types\n\n```python\nfrom sempy_labs._helper_functions import _update_dataframe_datatypes\n\ncolumn_map = {\n    \"Created Date\": \"datetime\",\n    \"Size\": \"int\",\n    \"Is Active\": \"bool\",\n}\n\n_update_dataframe_datatypes(df, column_map)\n```\n\n---\n\n## Complete Example\n\n```python\nfrom sempy._utils._log import log\nfrom sempy_labs._helper_functions import (\n    resolve_workspace_name_and_id,\n    _base_api,\n    _create_dataframe,\n    _build_url,\n)\nimport sempy_labs._icons as icons\nfrom typing import Optional\nfrom uuid import UUID\nimport pandas as pd\n\n\n@log\ndef list_my_items(\n    item_type: Optional[str] = None,\n    workspace: Optional[str | UUID] = None,\n) -> pd.DataFrame:\n    \"\"\"\n    Lists items in a workspace.\n\n    This is a wrapper function for the following API: `Items - List Items \u003Chttps:\u002F\u002Flearn.microsoft.com\u002Frest\u002Fapi\u002Ffabric\u002Fcore\u002Fitems\u002Flist-items>`_.\n\n    Service Principal Authentication is supported.\n\n    Parameters\n    ----------\n    item_type : str, default=None\n        Filter by item type.\n    workspace : str | uuid.UUID, default=None\n        The Fabric workspace name or ID.\n        Defaults to None which resolves to the workspace of the attached lakehouse.\n\n    Returns\n    -------\n    pandas.DataFrame\n        A pandas dataframe showing items in the workspace.\n    \"\"\"\n\n    (workspace_name, workspace_id) = resolve_workspace_name_and_id(workspace)\n\n    columns = {\n        \"Id\": \"string\",\n        \"Name\": \"string\",\n        \"Type\": \"string\",\n    }\n    df = _create_dataframe(columns=columns)\n\n    url = f\"\u002Fv1\u002Fworkspaces\u002F{workspace_id}\u002Fitems\"\n    params = {}\n    if item_type:\n        params[\"type\"] = item_type\n    if params:\n        url = _build_url(url, params)\n\n    responses = _base_api(\n        request=url,\n        uses_pagination=True,\n        client=\"fabric_sp\",\n    )\n\n    rows = []\n    for r in responses:\n        for item in r.get(\"value\", []):\n            rows.append({\n                \"Id\": item.get(\"id\"),\n                \"Name\": item.get(\"displayName\"),\n                \"Type\": item.get(\"type\"),\n            })\n\n    if rows:\n        df = pd.DataFrame(rows)\n\n    return df\n```\n\n---\n\n## Debugging API Calls\n\n### Print Response Details\n\n```python\nresponse = _base_api(\n    request=url,\n    client=\"fabric_sp\",\n)\n\nprint(f\"Status: {response.status_code}\")\nprint(f\"Headers: {response.headers}\")\nprint(f\"Body: {response.json()}\")\n```\n\n### Check Request Being Made\n\nAdd temporary debug prints:\n\n```python\nprint(f\"Making request to: {url}\")\nprint(f\"Payload: {payload}\")\n```\n\n---\n\n## API Documentation References\n\n| API | Documentation |\n|-----|---------------|\n| Fabric Core | [https:\u002F\u002Flearn.microsoft.com\u002Frest\u002Fapi\u002Ffabric\u002Fcore\u002F](https:\u002F\u002Flearn.microsoft.com\u002Frest\u002Fapi\u002Ffabric\u002Fcore\u002F) |\n| Fabric Admin | [https:\u002F\u002Flearn.microsoft.com\u002Frest\u002Fapi\u002Ffabric\u002Fadmin\u002F](https:\u002F\u002Flearn.microsoft.com\u002Frest\u002Fapi\u002Ffabric\u002Fadmin\u002F) |\n| Power BI | [https:\u002F\u002Flearn.microsoft.com\u002Frest\u002Fapi\u002Fpower-bi\u002F](https:\u002F\u002Flearn.microsoft.com\u002Frest\u002Fapi\u002Fpower-bi\u002F) |\n| Azure Fabric | [https:\u002F\u002Flearn.microsoft.com\u002Frest\u002Fapi\u002Fmicrosoftfabric\u002F](https:\u002F\u002Flearn.microsoft.com\u002Frest\u002Fapi\u002Fmicrosoftfabric\u002F) |\n| Graph | [https:\u002F\u002Flearn.microsoft.com\u002Fgraph\u002Fapi\u002Foverview](https:\u002F\u002Flearn.microsoft.com\u002Fgraph\u002Fapi\u002Foverview) |\n",{"name":5,"description":7},"main","2ddf46109c1209ceffa88149f4631e7b2275f9a1",".claude\u002Fskills\u002Frest-api-patterns",204,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fsemantic-link-labs","https:\u002F\u002Fgithub.com\u002Fmicrosoft","https:\u002F\u002Fopensource.microsoft.com","Open source projects and samples from Microsoft","2026-11-13 04:54:42",{"source":8,"skillName":5,"commands":59,"prompt":69,"zipAvailable":70},[60,63,66],{"tool":61,"command":62},"npx","npx skills add microsoft\u002Fsemantic-link-labs --skill rest-api-patterns",{"tool":64,"command":65},"bunx","bunx skills add microsoft\u002Fsemantic-link-labs --skill rest-api-patterns",{"tool":67,"command":68},"pnpm","pnpm dlx skills add microsoft\u002Fsemantic-link-labs --skill rest-api-patterns","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fsemantic-link-labs\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Frest-api-patterns\u002FSKILL.md",true,[72],{"path":73,"resourceType":74,"resourceTypeDesc":75,"sizeBytes":76,"sourceHtmlUrl":77},"scripts\u002Fsearch_public_api_doc.py","SCRIPT","脚本",12073,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fsemantic-link-labs\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Frest-api-patterns\u002Fscripts\u002Fsearch_public_api_doc.py",[79,104,136,152,167,181],{"skillNo":80,"name":81,"nameZh":6,"description":82,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":83,"categories":84,"keywords":94,"publishedAt":44},"01M699GKE0WWT6YVHBS06KM8AH","write-tests","Guide for writing unit tests. Use this when creating tests to verify Python logic.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fsemantic-link-labs\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fwrite-tests\u002FSKILL.md",[85,88,91],{"categoryNo":86,"categoryName":87,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000008","测试与质量",{"categoryNo":89,"categoryName":90,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000018","写作与文案",{"categoryNo":92,"categoryName":93,"taxonomyType":26,"taxonomyTypeDesc":27},"01JBSEEDCAT000000000000036","内容创作者",[95,96,97,43,98,42,99,100,37,36,101,102,103],"write tests","write","tests","python","unit","logic","verify","unit tests","writing",{"skillNo":105,"name":106,"nameZh":6,"description":107,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":108,"categories":109,"keywords":119,"publishedAt":44},"01M699GGVJHWCJNW68P08VWCMA","ui-styling","Guide for the visual style, structure, and shared building blocks used by Semantic Link Labs interactive UI tools (HTML widgets and anywidget-based widgets). Use this when adding a new interactive UI, modifying an existing one, or adding shared visual components.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fsemantic-link-labs\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fui-styling\u002FSKILL.md",[110,113,116],{"categoryNo":111,"categoryName":112,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000009","前端开发",{"categoryNo":114,"categoryName":115,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000015","视觉设计",{"categoryNo":117,"categoryName":118,"taxonomyType":26,"taxonomyTypeDesc":27},"01JBSEEDCAT000000000000032","设计师",[120,121,122,123,124,125,126,127,37,36,128,129,130,43,131,42,132,133,134,135],"styling","ui","ui styling","html","visual","components","structure","Building Blocks","interactive","Tools","shared","Existing","blocks","visual style","style","widgets",{"skillNo":137,"name":138,"nameZh":6,"description":139,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":140,"categories":141,"keywords":142,"publishedAt":44},"01M699GEZ3YRK8PCPVZF4NEEWF","tom-operations","Guide for working with the TOM (Tabular Object Model) wrapper. Use this when modifying semantic models programmatically.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fsemantic-link-labs\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Ftom-operations\u002FSKILL.md",[],[143,144,43,145,42,146,147,148,149,38,37,36,150,151],"tom operations","operations","model","object","with","semantic","models","tabular","semantic models",{"skillNo":153,"name":154,"nameZh":6,"description":155,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":156,"categories":157,"keywords":162,"publishedAt":44},"01M699GCWWBZM2XFNW5PTGRFJP","sql_to_dax","Guide for translating SQL aggregation expressions into DAX measures.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fsemantic-link-labs\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fsql_to_dax\u002FSKILL.md",[158,159],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":160,"categoryName":161,"taxonomyType":26,"taxonomyTypeDesc":27},"01JBSEEDCAT000000000000033","数据分析师",[163,164,165,42,36,166],"dax","sql to dax","sql","aggregation",{"skillNo":168,"name":169,"nameZh":6,"description":170,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":171,"categories":172,"keywords":173,"publishedAt":44},"01M699GAY10VVK66E4QGT94A93","run-tests","Guide for running pytest tests locally. Use this when running tests to verify code changes.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fsemantic-link-labs\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Frun-tests\u002FSKILL.md",[],[97,174,175,176,37,36,101,177,178,42,179,43,180],"run","run tests","pytest","running tests","code","running","changes",{"skillNo":182,"name":183,"nameZh":6,"description":184,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":185,"categories":186,"keywords":187,"publishedAt":44},"01M699G6XY1WTG7ESA1Y7YYCKT","query-builder-dax","Guide for the DAX query shape produced by the Query Builder in the DAX test widget. Use this when modifying how the Query Builder generates DAX, or when generating an EVALUATE query from columns, measures, filters and sorting.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fsemantic-link-labs\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fquery-builder-dax\u002FSKILL.md",[],[188,163,189,190,191,192,42,43,193,194,195,196,197,198,37,36,199],"query builder","query builder dax","query","builder","test","evaluate","sorting","columns","widget","filters","shape","how"]