create_generator
Saves a new JavaScript code generator.
Overview
create_generator saves a code generator written in JavaScript. Once it's saved, it appears in Relay's Preview panel and in the Exporters pane of Relay's settings, and generate_code can use it.
The source declares a top-level manifest object and a top-level generate(req, r) function that returns the code as a string. req is the request, with its variables and auth resolved, and r is Relay's helper namespace.
{
"source": "var manifest = { id: 'httpie-short', name: 'HTTPie (short)', group: 'Shell', language: 'shell', fileExtension: 'sh' };\n\nfunction generate(req, r) {\n var b = r.builder(' ');\n b.add('http').add(req.method).add(r.q.shell(req.url));\n r.allHeaders(req).forEach(function (h) { b.add(r.q.shell(h.name + ':' + h.value)); });\n return b.join();\n}\n"
}Before saving, Relay runs the generator against the same sample requests as test_generator and rejects it if it fails on any of them. It doesn't compile or run the generated code. To try a generator without saving it, use test_generator, and to start from a built-in generator's source, use get_generator.
Parameters
Prop
Type
Manifest
Prop
Type
Return Value
{
"id": "httpie-short",
"name": "HTTPie (short)",
"kind": "http",
"group": "Shell",
"language": "shell",
"fileExtension": "sh",
"replaced": false,
"shadowsBuiltIn": false,
"testOutputPreview": "http POST 'https://api.example.com/v1/items?verbose=true' 'Accept:application/json' 'User-Agent:Relay' 'Content-Type:application/json'",
"testedWith": ["JSON POST", "GET with bearer auth", "Form with Basic auth", "Multipart with cookies", "Custom method with a raw body"],
"warnings": [
"JSON POST: The request has a json body, but none of it appears in the output. …"
],
"verificationNote": "Relay ran the generator and checked the text of its output. It didn't compile or run the generated code, …"
}Prop
Type
Discussion
A WebSocket generator sets kind: 'websocket' in its manifest and is offered only for WebSocket requests. Its req has the method GET, a ws:// or wss:// URL, no body, and a webSocket object with the request's subprotocols, saved messages, selected message, ping interval and maximum message size.
To see how a built-in generator is written, call get_generator. For the full request model and helpers, see Code Generator API. The manifest and generate can be declared with var, let, const or function.
The tool returns an error when the source is empty or larger than 512 KB, when it contains [redacted] or •••••••• (the placeholders Relay shows an agent instead of a credential, which a generator never receives), when the manifest has no id or an invalid one, when id doesn't match the manifest's, when the id is already in use and overwrite isn't true (the message suggests an unused id), or when the test run fails on any request (the message names them). Nothing is saved when it returns an error.
To delete a generator, select it in the Exporters pane of Relay's settings and click the Delete Generator button (−). Deleting a generator that replaced a built-in one brings the built-in one back.
See Also
- Code Generator API: The manifest, request model and helpers for writing code generators.
- Creating a custom code generator: Write a JavaScript generator that turns requests into code in the form you need.
- test_generator: Runs a code generator's source once without saving it.
- get_generator: Returns a code generator's manifest and JavaScript source.
- list_generators: Lists the code generators that can export requests as code.