Understanding Cosmos DB REST API in Simple Terms

on
Azure Cosmos DB is a cloud-based NoSQL database service developed by Microsoft for managing data in modern, distributed applications.

It supports multiple data models like document, key-value, graph, and column-family, offering flexible storage for various application needs.

Cosmos DB REST API methods:

Cosmos DB REST API allows developers to interact with the database service over HTTPS using standard HTTP methods like GET and POST.

This API enables CRUD (Create, Read, Update, Delete) operations on databases, containers, documents, users, and permissions within Cosmos DB. Using the REST API, you can integrate Cosmos DB into services or applications without using any SDK or programming libraries directly.

The API communicates using JSON (JavaScript Object Notation), a lightweight data format ideal for web applications and mobile platforms.

Every request sent to the REST API must include authentication headers and a valid master or resource token for secure access.

The Cosmos DB REST API uses a resource model that organizes data into databases, collections (containers), and JSON-based documents.

Request Reader Access to Azure Portal 👇

Cosmos DB Resources

Below are links to articles that explain the available REST APIs for each Cosmos DB resource type. For an overview of the resource structure, refer to the Resource Model and Cosmos DB Resource URIs documentation.
  • Databases
  • Containers (Collections)
  • Documents
  • Attachments
  • Stored Procedures
  • User-Defined Functions (UDFs)
  • Triggers
  • Users
  • Permissions
  • Offers
Watch the below video, to know more about how Cosmos DB REST API works.


An example of Python script which gets list of databases in a cosmos db account.

import requests
import datetime
import hashlib
import hmac
import base64
import urllib.parse

# Your Cosmos DB credentials
account = 'your-account-name'
master_key = 'your-primary-key'
host = f'https://{account}.documents.azure.com:443/'
resource_type = 'dbs'
resource_link = ''
verb = 'GET'
x_ms_version = '2018-12-31'

# Get the current HTTP date in RFC1123 format
x_ms_date = datetime.datetime.utcnow().strftime('%a, %d %b %Y %H:%M:%S GMT')

# Build the signature string
def build_auth_signature(verb, resource_type, resource_link, date, key):
    text = f'{verb.lower()}\n{resource_type.lower()}\n{resource_link}\n{date.lower()}\n\n'
    body = text.encode('utf-8')
    key = base64.b64decode(key)
    signature = hmac.new(key, body, hashlib.sha256).digest()
    signature = base64.b64encode(signature).decode()
    return urllib.parse.quote(f'type=master&ver=1.0&sig={signature}')

auth_header = build_auth_signature(verb, resource_type, resource_link, x_ms_date, master_key)

# Set headers
headers = {
    'Authorization': auth_header,
    'x-ms-date': x_ms_date,
    'x-ms-version': x_ms_version,
    'Content-Type': 'application/json'
}

# Make the request to list databases
url = host + 'dbs'
response = requests.get(url, headers=headers)

# Output the result
print('Status Code:', response.status_code)
print('Response Body:', response.text)


Note: Building signature string varies for other authentication methods.

The sample code gives us all the dbs present in the cosmos db account. 

Microsoft Docs

Learn about Cosmos DB REST API

Access Control:

Status codes of Cosmos DB RESR API

Comments

Post a Comment