OpenAPI contract and source precedence
Use the Conduit OpenAPI contract for shape and Hurl behavior tests for exact runtime expectations.
Use the Conduit OpenAPI 3.1 contract to discover the public surface and generate client or server scaffolding. Use the Hurl suite to verify behavior that examples and schema alone cannot prove. The contract describes the API version, paths, parameters, security scheme, request bodies, response statuses, and reusable schemas; the tests exercise concrete requests against an implementation.
Contract boundary
The contract is titled RealWorld Conduit API, has version 2.0.0, and declares https://api.realworld.show/api as its server. Its public tags group operations into Articles, Comments, Favorites, Profile, Tags, and User and Authentication. The Token security scheme uses the Authorization header with the value form Token <jwt>.
The contract includes these operation groups:
- User registration, login, and current-user reads and updates.
- Profile reads, follow, and unfollow.
- Article listing, feed reads, creation, reads, updates, deletion, comments, and favorites.
- Tag listing.
Start with the Endpoint index to find the operation and its detailed guide. Do not infer an endpoint from an implementation route that is absent from the contract.
Decide which source answers a question
| Question | Primary source | What to read |
|---|---|---|
| Does an operation, parameter, field, or response exist? | OpenAPI contract | paths, parameters, requestBodies, responses, and components.schemas |
| What exact status and response does a scenario produce? | Hurl behavior test | The request, expected HTTP line, captures, and assertions |
| How do I run the conformance checks? | Hurl runner | The HOST, UID_VAL, file selection, and hurl --test invocation |
| How can I inspect requests interactively? | Generated Bruno collection | The collection generated from Hurl; treat Hurl as authoritative when they differ |
| How should a reader call the operation? | This documentation | Only after checking the contract and the applicable behavior test |
When the contract and a test appear to disagree, preserve the contract's declared public shape and investigate the test or implementation before documenting a guarantee. The project explicitly treats Hurl files as the source of truth for behavior; the Bruno collection is generated from Hurl and kept in sync by CI. Record an unresolved contradiction for maintainers instead of silently choosing the more convenient result.
Run Hurl against a backend
The runner defaults HOST to http://localhost:8000 and creates a unique test value for UID_VAL. It runs all Hurl files serially when you do not provide file arguments. From the API specification's Hurl directory, run:
HOST=http://localhost:3000/api ./run-hurl-tests.shThe runner prints the target host and generated UID, then invokes Hurl with --test, one job, and the host and uid variables. Set HOST to your backend's API base path; do not append another /api if your chosen value already includes it.
Use the generated Bruno collection
The repository also provides a Bruno collection generated from the Hurl suite. Run its documented script against a local API with:
HOST=http://localhost:3000/api ./run-api-tests-bruno.shYou can open the bruno/ folder in the Bruno app to inspect and run requests interactively. Use the dedicated Run Hurl tests and Run the generated Bruno collection pages for workflow details.
Keep implementations aligned
For a new backend, implement the paths and schemas from the OpenAPI contract, then run the Hurl suite against the implementation. For a client, generate or hand-write requests from the contract and use the endpoint guides for authentication, pagination, errors, and examples. Confirm successful status codes and error envelopes rather than validating only that a request returned JSON.