Superapp / Product requirements / echo

Request Echo — product requirements

Version 1.06 features21 requirements8 Must Open appJSONMarkdown

Request Echo is an HTTP request and response service for API testing. Its endpoints reflect the arguments, headers, body, form fields and cookies they receive, or produce a requested status code, delay, redirect chain, cookie or authentication challenge. A playground builds requests from method, path, query and header grids and several body types, and keeps saved requests per browser tab.

Problem. People who test HTTP clients need a service that answers exactly what was sent or exactly what was asked for. If an echo drops a value, a status is ignored or an auth check is lax, tests built on it give wrong confidence.

Users

Goals

Out of scope

Contents

Echo endpoints

Method endpoints and /anything reflect the request.

FR-ECH-01
Must
GET /get answers 200 with a JSON body that reflects the query arguments, the URL and the request headers.
  • GET /get?keval=run-4821 returns 200 with Content-Type application/json and args.keval equal to "run-4821".
  • url ends with /api/echo/get?keval=run-4821 and headers contains Host.
FR-ECH-02
Must
A query key that appears more than once is echoed as a list of all its values in order.
  • /get?keval=demo-123&tag=a&tag=b returns args.keval "demo-123" and args.tag ["a","b"].
FR-ECH-03
Must
A JSON body is echoed parsed in "json" and raw in "data", with its method and headers.
  • POST {"item":"Notebook","qty":3,"gift":false} returns json equal to that object.
  • The X-Request-Id header sent is echoed in headers; headers["Content-Type"] is application/json; method "POST".
FR-ECH-04
Should
Urlencoded form bodies arrive in "form" and leave "json" null.
  • PUT with city=Lyon and zip=69001 returns form {"city":"Lyon","zip":"69001"}, json null, method "PUT" and Content-Type application/x-www-form-urlencoded.
FR-ECH-05
Should
Each method endpoint and /anything echo the method, body, arguments and URL; an endpoint that accepts only one method answers 404 to others.
  • DELETE /delete with {"id":7} returns 200, json {"id":7} and method "DELETE".
  • PATCH /anything/a/b?x=1 with text "hi" returns data "hi", args {"x":"1"} and a url ending /anything/a/b?x=1.
  • GET /post returns 404.
  • GET /base64/UmVxdWVzdCBFY2hvIHJvY2tz returns 200 with the text "Request Echo rocks".

Status, redirects and delay

Endpoints produce a chosen status code, a redirect chain or a delayed answer.

FR-STA-01
Must
The status endpoint answers exactly the requested code, and an invalid code is refused.
  • /status/201 shows "201 Created"; /status/404 shows "404 Not Found" with an empty body.
  • /status/418 shows "418 I'm a teapot" with ASCII art containing "teapot"; /status/503 shows "503 Service Unavailable".
  • /status/abc returns 400 with the message "Invalid status code".
FR-STA-02
Should
A redirect chain is followed to /get and the final response reports that it was redirected.
  • "Redirect ×3" ends 200 OK with "Redirected → /api/echo/get" and a body url ending /api/echo/get.
FR-STA-03
Should
The delay endpoint waits the requested time before answering, and the client shows it is waiting.
  • The send button shows "Sending…" for about 2 seconds on a 2 second delay.
  • The answer is 200 OK and the displayed time is at least 2000 ms.

Authentication challenges

Basic and Bearer endpoints check the credentials sent.

FR-AUT-01
Must
The Basic auth endpoint accepts only the user and password named in its path; a wrong password or a missing Authorization header gives 401 with an empty body.
  • Correct credentials return 200 {"authenticated":true,"user":<the path user>}.
  • A wrong password returns 401 Unauthorized with an empty body.
  • Removing the Authorization header returns 401 Unauthorized.
FR-AUT-02
Should
The Bearer endpoint echoes the token of a Bearer authorization and refuses any other scheme with 401.
  • Authorization "Bearer <token>" returns 200 {"authenticated":true,"token":<that token>}.
  • Authorization "Token abc" returns 401 Unauthorized.

Cookies and response headers

Endpoints set and delete cookies and set response headers from the query.

FR-COK-01
Should
Cookies set through the cookie endpoints persist in the browser and can be deleted by name.
  • /cookies/set?flavor=oat&size=xl answers 200 after a redirect with cookies {"flavor":"oat","size":"xl"}.
  • /cookies still lists flavor and size.
  • /cookies/delete?flavor leaves cookies {"size":"xl"}.
FR-COK-02
Could
Response headers requested in the query are returned and visible in the response Headers tab.
  • /response-headers?x-trace=abc123 answers 200 OK and the Headers tab lists x-trace with value abc123.

Playground

The playground builds requests from grids and body editors and saves them per tab.

FR-PLY-01
Must
The Params grid and the Path stay in sync in both directions, with values correctly encoded and disabled rows left out.
  • Path /get?color=teal&size=9 shows Params badge 2 with rows color=teal and size=9.
  • Unticking size makes the Path /get?color=teal and the badge 1.
  • Adding key "note" with value "a b&c" makes the Path /get?color=teal&note=a%20b%26c; the response args is {"color":"teal","note":"a b&c"}.
FR-PLY-02
Should
Malformed JSON is refused before sending with a message starting "Body is not valid JSON:" and no response is shown; a valid body sends.
  • {"a": 1,} shows "Body is not valid JSON:" and no new response.
  • {"a": 1} returns 200 OK with json {"a":1}.
FR-PLY-03
Could
GET sends no body: the body settings state this and are disabled.
  • The Body tab shows "GET requests are sent without a body." and the body type radios are disabled.
FR-PLY-04
Could
Saved requests persist across reloads for the tab, can be deleted and cannot reuse an existing name.
  • Saving "Orders lookup" lists it last among 9 saved requests.
  • Saving again as "teapot" shows "A saved request named \"teapot\" already exists".
  • After a reload "Orders lookup" is still listed; deleting it leaves 8.

HTML order form and catalogue

A classic HTML order form posts to the echo, and a catalogue lists the endpoints.

FR-FRM-01
Must
The HTML order form submits urlencoded fields to /api/echo/post, with repeated checkboxes arriving as a list.
  • Submitting shows JSON whose form has custname "Rae Kim", size "medium", topping ["bacon","mushroom"], delivery "19:30" and comments "Ring twice".
FR-FRM-02
Could
The preferred delivery time must be between 11:00 and 21:00 in 15-minute steps; the browser blocks other values.
  • 22:00 is blocked with a "must be 21:00 or earlier" style message.
  • 19:10 is blocked because it is not on a 15-minute step.
FR-FRM-03
Could
The endpoint catalogue lists every endpoint and can be filtered by group and search text.
  • The page reads "21 endpoints".
  • Group "Auth" shows "2 endpoints": /basic-auth/{user}/{passwd} and /bearer.
  • All groups with search "cookie" shows "3 endpoints".

Non-functional requirements

NFR-01
Must
An echo never drops, reorders or alters data it was sent.
  • Repeated keys, JSON bodies and form fields round-trip unchanged.
NFR-02
Should
A slow response is awaited by the playground and is not treated as a failure.

Glossary and rules

EchoA response that reflects the request that was received.
Saved requestA playground request stored for the current browser tab.