[Microsoft.DevCenter] [Dataplane] New 2025-07-01-preview API version

[ArberH]

Data Plane API Specification Update Pull Request

Tip

Overwhelmed by all this guidance? See the Getting help section at the bottom of this PR description.

PR review workflow diagram

Please understand this diagram before proceeding. It explains how to get your PR approved & merged.

API Info: The Basics

Most of the information about your service should be captured in the issue that serves as your API Spec engagement record.

• Link to API Spec engagement record issue:

Is this review for (select one):

• a private preview
• a public preview
• GA release

Change Scope

^{This section will help us focus on the specific parts of your API that are new or have been modified.
Please share a link to the design document for the new APIs, a link to the previous API Spec document (if applicable), and the root paths that have been updated.}

• Design Document:
• Previous API Spec Doc:
• Updated paths:

Viewing API changes

For convenient view of the API changes made by this PR, refer to the URLs provided in the table
in the Generated ApiView comment added to this PR. You can use ApiView to show API versions diff.

Suppressing failures

If one or multiple validation error/warning suppression(s) is detected in your PR, please follow the
Swagger-Suppression-Process
to get approval.

Release planner

A release plan should have been created. If not, please create one as it will help guide you through the REST API and SDK creation process.

❔Got questions? Need additional info?? We are here to help!

Contact us!

The Azure API Review Board is dedicated to helping you create amazing APIs. You can read about our mission and learn more about our process on our wiki.

• 💬 Teams Channel
• 💌 email

Click here for links to tools, specs, guidelines & other good stuff

Tooling

• Open API validation tools were run on this PR. Go here to see how to fix errors
• Spectral Linting

Guidelines & Specifications

• Azure REST API Guidelines
• OpenAPI Style Guidelines
• Azure Breaking Change Policy

Helpful Links

• Schedule a data plane REST API spec review

Getting help

• First, please carefully read through this PR description, from top to bottom.
• If you don't have permissions to remove or add labels to the PR, request write access per aka.ms/azsdk/access#request-access-to-rest-api-or-sdk-repositories
• To understand what you must do next to merge this PR, see the Next Steps to Merge comment. It will appear within few minutes of submitting this PR and will continue to be up-to-date with current PR state.
• For guidance on fixing this PR CI check failures, see the hyperlinks provided in given failure
  and https://aka.ms/ci-fix.
• If the PR CI checks appear to be stuck in queued state, please add a comment with contents /azp run.
  This should result in a new comment denoting a PR validation pipeline has started and the checks should be updated after few minutes.
• If the help provided by the previous points is not enough, post to https://aka.ms/azsdk/support/specreview-channel and link to this PR.

[openapi-pipeline-app]

Next Steps to Merge

Next steps that must be taken to merge this PR:

• ❌ Your PR requires an API stewardship board review as it introduces a new API version (label: new-api-version). Schedule the review by following aka.ms/azsdk/onboarding/restapischedule.
• ❌ The required check named Automated merging requirements met has failed. This is the final check that must pass. Refer to the check in the PR's 'Checks' tab for details on how to fix it and consult the aka.ms/ci-fix guide. In addition, refer to step 4 in the PR workflow diagram

[openapi-pipeline-app]

PR validation pipeline restarted successfully. If there is ApiView generated, it will be updated in this comment.

[github-actions]

API Change Check

APIView identified API level changes in this PR and created the following API reviews

Language	API Review for Package
Swagger	Microsoft.DevCenter
TypeSpec	DevCenterService
JavaScript	@azure-rest/developer-devcenter
Python	azure-developer-devcenter
Java	com.azure:azure-developer-devcenter

[mikekistler]

Review comments from Copilot (run in VSCode locally):

Azure DevCenter REST API Review

API Version: 2025-04-01-preview
Review Date: July 1, 2025
File: devcenter.json

Executive Summary

The Azure DevCenter REST API specification demonstrates strong adherence to Azure REST API Guidelines with an overall compliance score of approximately 85%. The API structure, resource modeling, HTTP semantics, and core patterns are well-implemented. The primary areas for improvement focus on documentation quality and API organization rather than fundamental design issues.

---

✅ Strengths & Compliant Areas

Basic Structure & Metadata

• OpenAPI Version: ✅ Uses Swagger 2.0 appropriately
• Service Information: ✅ Clear title "DevCenter" with appropriate preview version
• TypeSpec Generated: ✅ Properly marked as generated from TypeSpec
• Protocol: ✅ Correctly uses HTTPS only
• Content Types: ✅ Properly specifies application/json for both consumes and produces

Authentication & Security

• OAuth2 Implementation: ✅ Correctly implements Azure OAuth2 with proper scope

  "scopes": {
    "https://devcenter.azure.com/.default": ""
  }

• Security Definition: ✅ Follows Azure standards with implicit flow and correct authorization URL

Resource Naming & URI Structure

• Consistent Patterns: ✅ Follows hierarchical resource patterns

  /projects/{projectName}/users/{userId}/devboxes/{devBoxName}
  

• Noun-based URIs: ✅ Uses nouns for resources rather than verbs
• Parameter Naming: ✅ Consistent parameter naming patterns

HTTP Methods & Status Codes

• Proper HTTP Methods: ✅ Correctly maps CRUD operations to HTTP verbs
• Status Codes: ✅ Appropriate use of 200, 201, 202, 204, and error responses
• Long-Running Operations: ✅ Properly implements LRO pattern with x-ms-long-running-operation: true

Pagination

• Consistent Pagination: ✅ Uses x-ms-pageable with nextLink pattern consistently
• Standard Parameters: ✅ Implements Azure Core pagination parameters (top, skip, maxpagesize)

---

⚠️ Areas for Improvement

1. Tags Organization (Major Issue)

Current State:

"tags": []

Issue: Empty tags array reduces organization and discoverability.

Recommendation: Organize operations into logical groups:

"tags": [
  {
    "name": "DevBoxes",
    "description": "Operations for managing Dev Boxes"
  },
  {
    "name": "Projects", 
    "description": "Operations for managing projects"
  },
  {
    "name": "Environments",
    "description": "Operations for managing environments"
  },
  {
    "name": "Catalogs",
    "description": "Operations for managing catalogs"
  },
  {
    "name": "Pools",
    "description": "Operations for managing Dev Box pools"
  },
  {
    "name": "Schedules",
    "description": "Operations for managing schedules"
  }
]

2. Action-Based Endpoints (Design Inconsistency)

Current Pattern: Multiple endpoints use action-based patterns with colons:

• /devboxes/{devBoxName}:start
• /devboxes/{devBoxName}:stop
• /devboxes/{devBoxName}:restart
• /devboxes/{devBoxName}:approve
• /pools/{poolName}:align

Assessment: While Azure allows action-based endpoints for operations that don't fit CRUD, the pattern should be consistently applied.

Recommendation: These are acceptable for state-changing operations that don't map to standard CRUD. Ensure they're documented as non-CRUD operations.

3. Parameter Consistency

Issue: Some operations inline parameter definitions instead of using references:

// ❌ Inconsistent - inline definition
{
  "name": "projectName",
  "in": "path",
  "description": "Name of the project.",
  "required": true,
  "type": "string",
  "minLength": 3,
  "maxLength": 63,
  "pattern": "^[a-zA-Z0-9][a-zA-Z0-9-_.]{2,62}$"
}

// ✅ Should reference the parameter definition
{
  "$ref": "#/parameters/ProjectNameParameter"
}

Recommendation: Consistently use parameter references to avoid duplication.

4. API Description Completeness

Current:

"description": "DevCenter service"

Issue: Too brief and uninformative.

Recommended:

"description": "Azure DevCenter provides developers with self-service access to preconfigured development environments, enabling faster development cycles and consistent development experiences across teams."

5. Operation Summaries

Issue: Many operations lack summary fields, which are important for API documentation clarity.

Example Improvement:

{
  "operationId": "DevBoxes_ListAllDevBoxes",
  "summary": "List all Dev Boxes", // ← Add this
  "description": "Lists Dev Boxes that the caller has access to in the DevCenter."
}

6. Error Response Documentation

Current State: Uses Azure.Core.Foundations.ErrorResponse consistently ✅

Enhancement Opportunity: Add more specific error response documentation for common scenarios:

• 404 for not found resources
• 409 for conflicts
• 403 for authorization failures
• 400 for validation errors

---

📊 Compliance Assessment

Azure REST API Guideline	Compliance Level	Status
Resource-based URLs	🟢 High	Compliant
HTTP Method Usage	🟢 High	Compliant
Status Code Usage	🟢 High	Compliant
Error Response Format	🟢 High	Compliant
Pagination Pattern	🟢 High	Compliant
Long-Running Operations	🟢 High	Compliant
Security Implementation	🟢 High	Compliant
API Versioning	🟢 High	Compliant
Documentation Quality	🟡 Medium	Needs Improvement
Organization (Tags)	🔴 Low	Needs Improvement

---

🎯 Priority Recommendations

High Priority

1. Add comprehensive tags for better API organization and developer experience
2. Enhance service description to be more informative and comprehensive

Medium Priority

3. Standardize parameter references to eliminate duplication and ensure consistency
4. Add operation summaries for better documentation clarity
5. Enhance error response documentation with specific scenarios

Low Priority

6. Review action-based endpoints for consistency (current implementation is acceptable)

---

📈 Detailed Findings

Positive Patterns Observed

1. Consistent Resource Hierarchy

   /projects/{projectName}/users/{userId}/devboxes/{devBoxName}
   /projects/{projectName}/pools/{poolName}/schedules/{scheduleName}
   

2. Proper Long-Running Operation Implementation

   • Correct use of 202 status codes
   • Appropriate Operation-Location headers
   • Consistent x-ms-long-running-operation marking

3. Standard Azure Extensions

   • x-ms-pageable for pagination
   • x-ms-examples for all operations
   • x-ms-parameter-location for parameters

Areas Needing Attention

1. Documentation Gaps

   • Missing operation summaries
   • Brief service description
   • Limited error scenario documentation

2. Organization Issues

   • Empty tags array
   • No logical grouping of operations

3. Minor Inconsistencies

   • Mixed use of parameter references vs. inline definitions
   • Some operations have summaries while others don't

---

🔍 Examples of Best Practices Found

Pagination Implementation

"x-ms-pageable": {
  "nextLinkName": "nextLink"
}

Long-Running Operations

"responses": {
  "202": {
    "description": "The request has been accepted for processing, but processing has not yet completed.",
    "headers": {
      "Operation-Location": {
        "type": "string"
      }
    }
  }
}

Parameter Reuse

{
  "$ref": "#/parameters/Azure.Core.Foundations.ApiVersionParameter"
}

---

📝 Conclusion

The Azure DevCenter REST API specification is well-designed and follows Azure REST API Guidelines effectively. The core architecture, resource modeling, and HTTP semantics are implemented correctly. With the recommended improvements to documentation and organization, this API would achieve excellent compliance with Azure standards.

Overall Grade: B+ (85% compliance)

The API is production-ready but would benefit from the documentation and organizational enhancements outlined above to improve developer experience and maintainability.