microsoft-graph

Microsoft Graph API Orchestration Skill

Microsoft Graph is a unified REST API endpoint for accessing Microsoft Cloud resources across Microsoft 365, Windows, and Enterprise Mobility + Security. Base URL: https://graph.microsoft.com/{version}/{resource}

API Versions: v1.0 (production) or beta (preview)
Authentication: OAuth 2.0 via Azure AD
Data Format: JSON

When to Load Which Resource

Task	Service	Load Resource
Setup auth, register apps, manage credentials	Applications & Auth	resources/authentication-apps.md
Manage users, groups, organization, directory	Identity & Access	resources/identity-access.md
Email, folders, attachments, rules, signatures	Mail Operations	resources/mail-operations.md
Calendar, events, scheduling, meetings, free/busy	Calendar & Scheduling	resources/calendar-scheduling.md
Upload files, folders, share, OneDrive, SharePoint	Files & Storage	resources/files-storage.md
Teams, channels, chats, presence, online meetings	Teams & Communications	resources/teams-communications.md
Planner tasks, To Do lists, OneNote notebooks	Planning & Notes	resources/planning-notes.md
Security alerts, compliance, device management, reports	Security & Governance	resources/security-governance.md

Orchestration Protocol

Phase 1: Analyze Your Task

Identify which service area you need by answering:

• What resource? (users, files, messages, events, etc.)
• What action? (read, create, update, delete)
• Who? (signed-in user or service account)
• Permissions? (delegated or application)

Phase 2: Load the Right Resource

Use the decision table above to find your resource file. Each resource includes:

• Complete endpoint reference with base paths
• Request/response examples for all CRUD operations
• Query parameters and filter options
• Required permissions (delegated and application)
• Error handling patterns and best practices
• Common workflows and patterns

Phase 3: Implement with Confidence

Each resource shows practical, copy-paste-ready examples for your use case.

Universal Graph Concepts

Standard Query Parameters:

$select=prop1,prop2              Choose properties to return
$filter=startsWith(name,'A')     Filter results by condition
$orderby=name desc               Sort results (asc or desc)
$top=25                          Limit to 25 results (default 20)
$skip=50                         Skip first 50 results
$expand=members                  Include related/nested data
$count=true                      Include total count in response
$search="keyword"                Full-text search across content

Standard CRUD Operations:

GET /me/messages?$select=subject&$top=10        # Read
POST /me/events {"subject": "Meeting", ...}     # Create
PATCH /users/{id} {"jobTitle": "Manager"}       # Update
DELETE /me/messages/{id}                        # Delete

Pagination: Always follow @odata.nextLink in responses for complete data sets

Batch Requests: Use POST /$batch to combine 1-20 operations into single call

Delta Queries: Use GET /users/delta to track changes since last query via @odata.deltaLink

Error Response Format:

{"error": {"code": "Code", "message": "Description"}}

Common Status Codes:

• 200/201/204: Success
• 400: Invalid request
• 401: Authentication required
• 403: Insufficient permissions
• 404: Resource not found
• 429: Rate limited (check Retry-After header)
• 500-503: Server error (implement exponential backoff)

Resource File Index

File	Focus	Lines
authentication-apps.md	App registration, OAuth, credentials	350+
identity-access.md	Users, groups, organization, directory	350+
mail-operations.md	Email, folders, attachments, rules	400+
calendar-scheduling.md	Events, recurring, meetings, free/busy	350+
files-storage.md	OneDrive, SharePoint, uploads, sharing	400+
teams-communications.md	Teams, channels, chats, presence	350+
planning-notes.md	Planner, To Do, OneNote	350+
security-governance.md	Security, compliance, devices, reports	400+

Best Practices

Performance: Use $select for specific properties, implement pagination, cache tokens, use batch for bulk ops, apply delta queries for sync scenarios

Security: Store tokens securely (never in code), request least-privilege permissions, use managed identities for Azure, rotate credentials every 90 days, validate all responses

Development: Test in beta endpoint first, monitor deprecation notices, implement exponential backoff for retries, respect rate limiting, check Graph health status

Troubleshooting:

• 401 Unauthorized → Check token validity and scopes
• 403 Forbidden → Verify permissions are configured in Azure AD
• 404 Not Found → Verify resource ID and that resource exists
• 429 Too Many Requests → Implement retry with exponential backoff

Tools & SDK Resources

Interactive Testing: Graph Explorer at https://developer.microsoft.com/graph/graph-explorer

SDKs:

• .NET: Microsoft.Graph NuGet
• JavaScript/TypeScript: @microsoft/microsoft-graph-client npm
• Python: msgraph-sdk-python pip

Documentation:

• API Reference: https://docs.microsoft.com/graph/api/overview
• Permissions Reference: https://docs.microsoft.com/graph/permissions-reference
• Changelog: https://docs.microsoft.com/graph/changelog

---

Skill Version: 2.1 | API Versions: v1.0 (production), beta (preview) | Updated: December 2025