MSDN API v4.0 Documentation

Welcome to the official API documentation for MSDN (Microsoft Developer Network) version 4.0. This API provides programmatic access to a wide range of developer resources, documentation, code samples, and community content.

This version introduces several new features and improvements, including enhanced search capabilities, richer metadata for content, and a more robust error handling mechanism. We recommend all developers to upgrade to version 4.0 for the latest features and performance optimizations.

Please ensure you have read the Authentication section before making any requests.

Authentication

All API requests must be authenticated using OAuth 2.0. You will need to obtain an access token from the MSDN identity provider.

Obtaining an Access Token

Follow these steps to acquire an access token:

  1. Register your application on the Microsoft Identity Platform.
  2. Use the OAuth 2.0 client credentials flow or authorization code flow to obtain a token.

Using the Access Token

Include your access token in the Authorization header of your requests:

Authorization: Bearer YOUR_ACCESS_TOKEN
Access tokens are valid for a limited time. You will need to refresh your token periodically.

API Endpoints

This section details the available API endpoints and their usage.

GET /data

Retrieves a collection of developer resources based on specified filters.

Request

GET /api/4.0/data?query=&type=&limit=&offset=

Query Parameters

Name Type Required Description
query string No Search term for resources.
type string No Filter by resource type (e.g., "documentation", "sample", "article").
limit integer No Maximum number of results to return. Default: 20.
offset integer No Number of results to skip. Default: 0.

Response (200 OK)

JSON Example

{
    "totalResults": 150,
    "count": 10,
    "nextOffset": 10,
    "items": [
        {
            "id": "doc-12345",
            "title": "Introduction to .NET Core",
            "type": "documentation",
            "url": "https://docs.microsoft.com/en-us/dotnet/core/",
            "lastUpdated": "2023-10-26T10:00:00Z",
            "tags": ["dotnet", "core", "csharp"]
        },
        {
            "id": "sample-67890",
            "title": "Azure Functions Quickstart",
            "type": "sample",
            "url": "https://github.com/Azure-Samples/functions-dotnet-quickstart",
            "lastUpdated": "2023-10-25T14:30:00Z",
            "tags": ["azure", "functions", "serverless"]
        }
    ]
}

Example Usage (cURL)

curl -X GET "https://api.msdn.microsoft.com/api/4.0/data?query=azure&type=sample&limit=5" -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

POST /item

Creates a new developer resource entry. This endpoint is typically used for internal content management.

This endpoint is currently deprecated and not available for public use. Please refer to the documentation for supported operations.

Request Body (JSON)

Schema

{
    "title": "string (required)",
    "type": "string (required)",
    "url": "string (required)",
    "description": "string",
    "tags": ["string"]
}

PUT /resource/{id}

Updates an existing developer resource identified by its ID.

Request

PUT /api/4.0/resource/{id}

Path Parameters

Name Type Required Description
id string Yes The unique identifier of the resource to update.

Request Body (JSON)

Schema

{
    "title": "string",
    "url": "string",
    "description": "string",
    "tags": ["string"]
}

Response (200 OK)

JSON Example

{
    "id": "doc-12345",
    "title": "Updated Introduction to .NET",
    "type": "documentation",
    "url": "https://docs.microsoft.com/en-us/dotnet/",
    "lastUpdated": "2023-10-27T09:00:00Z",
    "tags": ["dotnet", "csharp", "updated"]
}

DELETE /entity/{uuid}

Deletes a specific entity. This operation is sensitive and requires appropriate permissions.

Request

DELETE /api/4.0/entity/{uuid}

Path Parameters

Name Type Required Description
uuid uuid Yes The Universally Unique Identifier of the entity to delete.

Response (204 No Content)

Indicates the entity was successfully deleted.

Example Usage (cURL)

curl -X DELETE "https://api.msdn.microsoft.com/api/4.0/entity/a1b2c3d4-e5f6-7890-1234-abcdef123456" -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of a request. Error responses will include a JSON body with more details.

Common Status Codes

Error Response Body

JSON Example

{
    "error": {
        "code": "INVALID_PARAMETER",
        "message": "The 'limit' parameter must be a positive integer.",
        "details": "Parameter: limit, Value: abc"
    }
}

Rate Limiting

To ensure fair usage and stability, the API enforces rate limits on requests.

If you exceed these limits, you will receive a 429 Too Many Requests status code. The response headers will include information about your current rate limit status:

For applications requiring higher limits, please contact our developer support team.

Changelog

Version 4.0.1 (2023-10-27)

Version 4.0.0 (2023-10-20)