REST API behaviour template

Copy the block below into a .feature file and replace the <placeholders>.

@api @orders
Feature: Manage orders

  Background:
    Given an authenticated customer "C-88"
    And order "A-1042" exists with status "new"
    And order "A-1043" exists with status "new"
    And order "A-1044" exists with status "shipped"

  @happy-path
  Scenario: Listing orders returns the customer's orders
    When the customer requests their orders
    Then the response status is 200
    And the response contains orders "A-1042" and "A-1043"
    And the response does not contain order "A-1044"

  @pagination
  Scenario: Listing orders paginates
    Given the customer has 25 orders
    When the customer requests their orders with a page size of 10
    Then the response status is 200
    And the response contains 10 orders
    And the response reports 25 orders in total
    And the response reports 3 pages in total

  @pagination
  Scenario: Requesting a page beyond the last page returns an empty list
    Given the customer has 25 orders
    When the customer requests their orders with a page size of 10 and page number 4
    Then the response status is 200
    And the response contains 0 orders
    And the response reports 25 orders in total

  @errors
  Scenario: Requesting an unknown order returns not found
    When the customer requests order "A-9999"
    Then the response status is 404
    And the response body contains error code "ORDER_NOT_FOUND"

  @errors
  Scenario: Requesting an order belonging to another customer is refused
    When the customer requests order "A-7777"
    Then the response status is 403
    And the response body contains error code "ORDER_ACCESS_DENIED"

  @errors
  Scenario: Requesting an order without authentication is refused
    Given an unauthenticated request
    When the request is made for order "A-1042"
    Then the response status is 401
    And the response body contains error code "AUTHENTICATION_REQUIRED"

  @validation
  Scenario: A page size above the maximum is refused
    When the customer requests their orders with a page size of 500
    Then the response status is 422
    And the response body contains error code "PAGE_SIZE_TOO_LARGE"
    And the response body states the maximum page size is 100

Notes on each part

The @tags carry meaning. They drive targeting, traceability to requirements, and severity. A tag that references a requirement ID is what turns "we have nine scenarios" into "requirements R-1 through R-9 each have a scenario and R-10 does not".

Background holds state, not actions. Every Given there is true before each scenario. If you find yourself adding a When to a Background, the scenarios have hidden their actual sequence and you should split them.

The pagination scenarios are the ones worth keeping. Two details are usually missing from a team’s own feature file:

  • The empty page beyond the last one. Almost every implementation gets this right by accident and a few get it wrong by returning a 404. Specify it.
  • The maximum page size. A limit that is not specified is a limit that does not exist until someone adds one. And when they do, the refusal is a breaking change for every client that was relying on the larger value.

The 403 and the 404 are different scenarios. Not-found and access-denied are different answers with different information leakage implications. A service that returns 404 for both is a deliberate choice, and it should be written down as one rather than as an accident.

The error codes are literal. ORDER_NOT_FOUND is checkable. "an appropriate error" is not — and it is exactly the kind of phrase that turns into an assertion-free scenario.

Pair it with an OpenAPI document

This template covers behaviour. The interface — paths, parameters, response schemas — belongs in the OpenAPI document, and the platform checks the two against each other. The error codes above must appear as operationId-scoped error responses in the document, or the cross-format consistency check will fail the build.

See OpenAPI contract testing for the contract side.

Next