Basic Usage¶

This guide covers common HTTP operations with OxideHTTP.

The examples assume an existing client created with:

async with OxideHTTP() as client:
    ...

HTTP methods¶

OxideHTTP provides asynchronous convenience methods for common HTTP operations.

GET¶

Retrieve a resource:

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

POST¶

Create a resource:

response = await client.post(
    '/users', json={'name': 'Alice', 'email': 'alice@example.com'}
)

PUT¶

Replace a resource:

response = await client.put(
    '/users/123', json={'name': 'Alice', 'email': 'alice@example.com'}
)

PATCH¶

Partially update a resource:

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

DELETE¶

Delete a resource:

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

Query parameters¶

Pass query parameters using the params argument:

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

Values are converted to strings when added to the request.

Boolean values are serialized as lowercase strings:

true
false

Sequence values produce repeated query parameters.

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

This produces a query equivalent to:

?role=admin&role=moderator

Parameters with None values are not automatically omitted by the query builder, so avoid passing them when you don't want them in the URL.

Request headers¶

Pass request-specific headers using headers:

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

Request-specific headers are combined with the client's configured default headers.

See Configuration for setting headers globally.

Request bodies¶

OxideHTTP supports several request body formats.

JSON¶

Use json for structured JSON data:

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

Text¶

Use body_text for plain text:

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

Bytes¶

Use body_bytes for raw binary data:

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

Form data¶

Use form to send form-encoded data:

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

Reading responses¶

Every request returns a response implementing BaseResponse.

Status code¶

The status_code property returns an HTTPStatus enum:

from oxidehttp.status import HTTPStatus


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

if response.status_code == HTTPStatus.OK:
    print('Request successful')

Headers¶

Response headers are available through the headers property:

content_type = response.headers.get('content-type')

Response body¶

Use the method that matches the expected response format:

# Raw bytes
data = await response.get_bytes()

# UTF-8 text
text = await response.text()

# JSON
payload = await response.json()

get_bytes() returns a memoryview. The response body is retained internally after reading, so multiple body-reading methods can be used on the same response.

Cached responses¶

When response caching is configured, a response can indicate whether it was retrieved from the cache:

if response.is_cached:
    print('Response retrieved from cache')

See Caching for details.