Introduction into REST

What is REST?

REST (Representational State Transfer) is an architectural style for designing networked applications. It builds on the stateless client-server model and uses standard HTTP methods to perform operations on resources. A RESTful API typically exposes resources (e.g. users, books, orders) through URLs and lets clients interact with them using:

  • GET - retrieve one or many resources

  • POST - create a new resource

  • PUT/PATCH - update an existing resource

  • DELETE - remove a resource

REST APIs commonly exchange data in JSON (or sometimes form-data / multipart) and return appropriate HTTP status codes together with machine-readable response bodies. Because REST is language- and platform-agnostic it has become the dominant way to expose backend services to web frontends, mobile apps, and other micro-services.

Testing REST endpoints thoroughly is essential. Small mistakes in request construction, missing validation, or incorrect error handling can lead to data corruption, security issues or bad user experience. That is why reusable, high-quality automated tests for REST APIs are extremely valuable.

Balder - reusable testing across platforms

Balder is a Python test framework that lets you write a test once and reuse it across completely different platforms, devices, or applications (web, mobile, desktop, embedded systems, APIs, databases, …).

It achieves this through a clean separation:

  • Scenarios contain the abstract test logic (the “what” should happen).

  • Setups contain the concrete implementation for your specific System Under Test (SUT) (the “how” it is done on this particular device/platform).

BalderHub packages are the community library of ready-to-use Scenarios and Features. You simply pip install them and plug in your own device-specific code.

How balderhub-rest implements REST testing

The balderhub-rest package is a BalderHub package that supplies everything you need to validate REST API endpoints with full CRUD support. It builds directly on top of balderhub-crud and adds REST-specific parsers, endpoint configuration helpers and ready-to-use setup features.

Core components

  1. Parsers (in balderhub.rest.lib.utils.parsers)

    • JsonParser, FormParser, MultipartParser and the extensible BaseParser

    • Automatic extraction of response data into the common DataItem model used by balderhub-crud

  2. CRUD Setup Features & Factories (in balderhub.rest.contrib.crud)

  3. Utilities & Response Handling

    • Field collection / filler callbacks

    • Standardised error and status-code response messages

    • Tight integration with balderhub-data for consistent data modelling and validation

How a typical test flows (high-level)

  1. You define your Devices (e.g. a REST client device and optionally a PointOfTruth database device).

  2. You attach the appropriate Features (the concrete HTTP calls and response parsing for your API).

  3. You run one of the pre-built Scenarios from balderhub-crud - Balder automatically wires everything together.

  4. The scenario performs the REST operation and verifies the result against expected data using the parsers and data models.

Because the heavy lifting (scenario logic, data validation, example generation) is already done by balderhub-crud, you only need to implement the small REST-specific parts (endpoint URLs, authentication, field mapping). The same test code works for any REST API - Django REST Framework, FastAPI, Flask-RESTful, or custom backends.

Current status & roadmap

  • Fully supported: Single Create / Read / Update, Multiple Read via REST, all triangle variants

  • The package is under active development - contributions are very welcome!

Available REST Scenarios

All scenarios are provided by the underlying balderhub-crud package. The balderhub-rest package only adds the necessary REST-specific building blocks so that those scenarios can be executed against an HTTP API.

You can find more details within the Example section of this documentation.