Core Concepts

This section outlines the fundamental principles and conventions used throughout the MSDN API. Understanding these concepts will help you effectively integrate with our services.

Resources and Endpoints

The MSDN API exposes various resources, such as users, projects, and data points. Each resource is accessed via a unique endpoint URL. Endpoints follow a RESTful architecture, using standard HTTP methods (GET, POST, PUT, DELETE) to perform operations on resources.

GET: Retrieve one or more resources.
POST: Create a new resource.
PUT: Update an existing resource entirely.
PATCH: Partially update an existing resource.
DELETE: Remove a resource.

Data Format

All data exchanged with the API is in JSON (JavaScript Object Notation) format. When sending data in a POST or PUT request, ensure the Content-Type header is set to application/json.

Example Request Body (POST /users)

{
    "username": "jane_doe",
    "email": "jane.doe@example.com",
    "isActive": true
}

Identifiers

Unique resources are identified by their respective IDs. These IDs are typically integers or UUIDs and are included in the URL path.

Example: Retrieving a specific user

GET /users/{userId}

Where {userId} is the unique identifier for the user.

Versioning

The MSDN API is versioned to allow for backward-compatible changes. The API version is included in the URL path.

Example: /v1/users or /v2/users.

Important: Always use the latest stable version of the API unless you have specific compatibility requirements. Check the Overview page for the current stable version.

Authentication

All API requests must be authenticated. Refer to the Authentication section for detailed information on how to authenticate your requests.

Idempotency

Many operations in the API are designed to be idempotent. This means that making the same request multiple times will have the same effect as making it once. This is particularly useful for preventing duplicate operations in case of network errors or retries.

Common Headers

The following headers are commonly used when interacting with the API:

Authorization: Contains your API key or token for authentication.
Content-Type: Specifies the format of the request body (e.g., application/json).
Accept: Indicates the desired format of the response (e.g., application/json).

Response Codes

The API uses standard HTTP status codes to indicate the success or failure of a request:

200 OK: The request was successful.
201 Created: The resource was successfully created.
204 No Content: The request was successful, but there is no content to return (e.g., a DELETE request).
400 Bad Request: The request was malformed or invalid.
401 Unauthorized: Authentication failed or is missing.
403 Forbidden: You do not have permission to access this resource.
404 Not Found: The requested resource could not be found.
429 Too Many Requests: You have exceeded the rate limit.
500 Internal Server Error: An unexpected error occurred on the server.