Requests¶

OxideHTTP provides asynchronous methods for making HTTP requests. Each method returns a response object that can be used to inspect the status code, headers, and response body.

Making Requests¶

Create an OxideHTTP client and use it as an asynchronous context manager:

from oxidehttp import OxideHTTP

async with OxideHTTP() as client:
    response = await client.get('https://api.example.com/users')
    print(response.status_code)

The client supports the following convenience methods:

For streaming and Server-Sent Events, OxideHTTP also exposes stream() and sse(). See Streaming and Server-Sent Events.

GET¶

Use get() to retrieve resources.

response = await client.get('https://api.example.com/users')

The method accepts the following arguments:

Example with query parameters:

response = await client.get('/users', params={'page': 1, 'limit': 20})

POST¶

Use post() to create resources or submit data.

response = await client.post('/users', json={'name': 'Miwowy', 'active': True})

The method accepts:

JSON Body¶

Use json to send JSON data:

response = await client.post('/users', json={'name': 'Alice', 'age': 25})

Text Body¶

Use body_text to send a text payload:

response = await client.post('/messages', body_text='Hello, world!')

Bytes Body¶

Use body_bytes to send raw bytes:

response = await client.post('/files', body_bytes=b'\x00\x01\x02')

Form Data¶

Use form to submit form fields:

response = await client.post(
    '/login', form={'username': 'alice', 'password': 'secret'}
)

PUT¶

Use put() to replace or update a resource.

response = await client.put(
    '/users/123', json={'name': 'Alice', 'active': True}
)

The method accepts:

PATCH¶

Use patch() to partially update a resource.

response = await client.patch('/users/123', json={'active': False})

The method accepts:

DELETE¶

Use delete() to delete a resource.

response = await client.delete('/users/123')

The method accepts:

Query Parameters¶

Pass query parameters using the params argument:

response = await client.get(
    '/search', params={'query': 'python', 'page': 1, 'limit': 10}
)

Values are converted to strings when constructing the query string.

Boolean values are serialized as lowercase strings:

params = {'enabled': True, 'archived': False}

Resulting query parameters:

enabled=true&archived=false

Multiple Values¶

Pass a sequence to provide multiple values for the same parameter:

response = await client.get('/users', params={'role': ['admin', 'moderator']})

This produces repeated query parameters:

role=admin&role=moderator

Values set to None are not automatically omitted. Filter optional values before passing them if you want to exclude them from the query string.

Headers¶

Use headers to provide request-specific headers:

response = await client.get(
    '/users',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Accept': 'application/json',
    },
)

Headers configured in OxideHTTPConfig are used as defaults. Request-specific headers are merged with the configured defaults.

See Configuration for configuring default headers.

Middleware¶

Middleware can be applied to individual requests through the middlewares argument:

response = await client.get(
    '/users',
    middlewares=(
        # Middleware instances
    ),
)

You can also configure middleware globally through RequestConfig.

See Middleware for details and available middleware implementations.

Extensions¶

Use extensions to pass additional request extensions:

response = await client.get(
    '/users',
    extensions={
        # Extension values
    },
)

The accepted extension type is defined by OxideHTTP's public types.

Response Handling¶

Every convenience request method returns a response object.

response = await client.get('/users')

print(response.status_code)
print(response.headers)

body = await response.get_bytes()
text = await response.text()

For JSON responses:

data = await response.json()

OxideHTTP uses msgspec for JSON decoding. See Responses for response handling details.

Related Documentation¶

• Configuration
• Responses
• Middleware
• Caching
• Streaming
• Server-Sent Events