MSDN Develop API Reference

Overview

The Data Storage API provides a robust set of endpoints for interacting with your application's persistent data. It supports various data types, from simple key-value pairs to more complex structured objects. Security and scalability are paramount, ensuring your data is safe and accessible when you need it.

Core Concepts

Data Items: Individual pieces of data stored under a unique identifier.
Collections: Logical groupings of data items.
Schema: (Optional) Defines the structure and types of data within a collection.
Access Control: Fine-grained permissions for reading and writing data.

Endpoints

1. Storing Data

Use this endpoint to create or update a data item.

POST /data/{collection}/{itemId}

Creates or updates a data item within a specified collection.

Parameters

collection (string, required): The name of the collection to store the data in.
itemId (string, required): A unique identifier for the data item. If the item already exists, it will be overwritten.
data (object, required): The JSON object representing the data to be stored.

Example Request Body

{
    "userName": "jane.doe",
    "preferences": {
        "theme": "dark",
        "notificationsEnabled": true
    },
    "lastLogin": "2023-10-27T10:00:00Z"
}

Example Response (Success)

{
    "status": "success",
    "message": "Data item 'user-profile-jane.doe' created/updated successfully."
}

2. Retrieving Data

Fetch a specific data item by its ID.

GET /data/{collection}/{itemId}

Retrieves a data item from a specified collection.

Parameters

collection (string, required): The name of the collection containing the data item.
itemId (string, required): The unique identifier of the data item to retrieve.

Example Response (Success)

{
    "status": "success",
    "data": {
        "userName": "jane.doe",
        "preferences": {
            "theme": "dark",
            "notificationsEnabled": true
        },
        "lastLogin": "2023-10-27T10:00:00Z"
    }
}

Example Response (Not Found)

{
    "status": "error",
    "message": "Data item 'user-profile-jane.doe' not found in collection 'users'."
}

3. Deleting Data

Remove a data item.

DELETE /data/{collection}/{itemId}

Deletes a data item from a specified collection.

Parameters

collection (string, required): The name of the collection containing the data item.
itemId (string, required): The unique identifier of the data item to delete.

Example Response (Success)

{
    "status": "success",
    "message": "Data item 'user-profile-jane.doe' deleted successfully."
}

Advanced Features

Listing Items in a Collection

Retrieve a list of item IDs within a collection, with optional filtering and pagination.

GET /data/{collection}

Lists data items within a specified collection.

Query Parameters

limit (integer, optional): The maximum number of items to return (default: 100).
offset (integer, optional): The number of items to skip (for pagination).
filter (string, optional): A query string for filtering items (e.g., "userName=john.smith").

Example Response (Success)

{
    "status": "success",
    "items": [
        {"itemId": "user-profile-jane.doe", "createdAt": "2023-10-27T09:00:00Z"},
        {"itemId": "user-settings-bob", "createdAt": "2023-10-26T15:30:00Z"}
    ],
    "totalItems": 2,
    "limit": 100,
    "offset": 0
}

Data Schemas

Define and enforce data structure using schemas for improved data integrity.

Visit the Schema Management section for details on creating and managing schemas.

Schema Example (JSON Schema)

{
    "type": "object",
    "properties": {
        "userName": {"type": "string"},
        "email": {"type": "string", "format": "email"},
        "createdAt": {"type": "string", "format": "date-time"}
    },
    "required": ["userName", "email"]
}