Quickstart¶

This guide shows how to create an OxideHTTP client, send an HTTP request, and process the response.

Create a client¶

OxideHTTP is an asynchronous HTTP client and supports asynchronous context management.

from oxidehttp import OxideHTTP


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

    print(response.status_code)
    print(await response.text())

The asynchronous context manager initializes the underlying HTTP client and closes it when the context exits.

Send your first request¶

The client provides convenience methods for common HTTP operations:

• get()
• post()
• put()
• patch()
• delete()

All request methods are asynchronous and return a BaseResponse instance.

GET request¶

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

print(response.status_code)
print(await response.json())

POST request¶

Use the json parameter to send a JSON request body:

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

print(response.status_code)

Handle the response¶

OxideHTTP responses expose the HTTP status code, response headers, and body-reading methods.

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

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

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

The body-reading methods are asynchronous.

• get_bytes() returns a memoryview.
• text() decodes the body as UTF-8.
• json() decodes the body as JSON using msgspec.

A response body is read and cached internally, so you can use these methods without consuming the underlying network response repeatedly.

Check HTTP status codes¶

HTTP error status codes are returned as normal responses. They do not automatically raise exceptions.

Use HTTPStatus to compare status codes:

from oxidehttp.status import HTTPStatus


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

if response.status_code == HTTPStatus.OK:
    print(await response.json())

elif response.status_code == HTTPStatus.NOT_FOUND:
    print('User not found')

else:
    print(f'Unexpected status: {response.status_code}')

What's next?¶

• Basic usage — learn about requests, parameters, headers, and response handling.
• Configuration — configure the client for your application.
• Error handling — handle transport and decoding errors.