sondahub

sondahub / OpenAPI mock server

OpenAPI mock server

Give it the address of an OpenAPI or Swagger file and it serves that API: routes matched, requests checked against the spec, answers from your examples or generated from your schemas — the same answer for the same request. No upload, no account, nothing kept.

Mock a spec

Any public OpenAPI 3 or Swagger 2 file, JSON or YAML. This one is the Store API's own.



  
The answer is the base URL to give your client and every operation the mock found. From code: GET https://api.sondahub.com/v1/mock?spec=<address>.






  
Calling the mock

  
GET/v1/mock?spec={url}What the mock read: title, version, every operation with a ready URL to try, and the base URL to use.

  
ANY/v1/mock/~{base64url of the spec URL}/{path}The mock itself, at a base URL that stays the same — put it in your client.

  
ANY/v1/mock/{path}?spec={url}The same, with the spec in the query (or the X-Sondahub-Spec header).

  

  
Describe a spec

  
curl "https://api.sondahub.com/v1/mock?spec=https%3A%2F%2Fapi.sondahub.com%2Fv1%2Fstore%2Fopenapi.json"

  



  

  
Call an operation through the mock

  
curl https://api.sondahub.com/v1/mock/~aHR0cHM6Ly9hcGkuc29uZGFodWIuY29tL3YxL3N0b3JlL29wZW5hcGkuanNvbg/v1/store/products/1

  



  

  
A body the spec does not allow — 422

  
curl -X POST https://api.sondahub.com/v1/mock/~aHR0cHM6Ly9hcGkuc29uZGFodWIuY29tL3YxL3N0b3JlL29wZW5hcGkuanNvbg/v1/store/products -H "Content-Type: application/json" -d '{"price": "free"}'

  








  
Choosing the answer

  
A real API answers more than its happy path, and a client has to handle all of it. The Prefer header picks which documented answer comes back:

  
HeaderAnswer

    
Prefer: code=404The 404 the operation documents (or its default response, with that status). Also ?_code=404.

    
Prefer: example=sold_outThat named example.

    
Prefer: dynamic=trueGenerated from the schema even when there is an example.

  

  

  
The documented 404

  
curl -i https://api.sondahub.com/v1/mock/~aHR0cHM6Ly9hcGkuc29uZGFodWIuY29tL3YxL3N0b3JlL29wZW5hcGkuanNvbg/v1/store/products/1 -H "Prefer: code=404"

  



  
Every control works on the mock too: X-Sondahub-Chaos for latency and failures, X-Sondahub-RateLimit for 429s, ?format=csv.




Questions
Which specs does it read?
OpenAPI 3.0 and 3.1, and Swagger 2.0, as JSON or YAML, up to 5 MB, fetched from a public address (the spec is cached for five minutes). $refs are followed within the document; a spec split across several files needs bundling first.
Where do the answers come from?
The response the operation documents: 201 for a POST that has one, the first 2xx otherwise. Its example if it has one, the first of its named examples next, and otherwise a body generated from the schema — types, formats, enums and bounds respected, the same answer for the same request every time. A generated body echoes the ids in the path and the fields you sent.
Does it check my requests?
Yes: required path, query, header and cookie parameters and their types, the body against its schema (422 naming each problem), the HTTP method (405 with an Allow header), and that a credential of a declared kind is present — any value passes, it is a mock.
Does it remember what I POST?
No — a spec says what an API answers, not how it stores things, so the mock answers from the spec every time. For writes that stick, use the populated APIs and a session.
Can I point a client generator or Sonda at the mock?
Yes. The base URL is stable — /v1/mock/~ followed by the spec's address in base64url — so it can go straight into a client's server setting. Import the spec into Sonda or any client and send its requests to the mock's base URL.