What do ZAP's generated API client libraries cover, and which part of the control API do they miss?

## The clients are output, not a product ZAP does not maintain its client libraries by hand. Core contains a generator per target language, all descending from one base class, and each one walks the API components registered in a running build and writes out source: a module or class per component prefix, and one method per call inside it, named after the call and carrying its documented parameters. The description you read in a generated method's docstring is the same message string the program uses for its own documentation. That has a pleasant consequence and an unpleasant one. **Pleasant:** the client cannot drift from the surface in the ordinary way hand-written SDKs do. If a call exists in the build the client was generated from, the method exists, with the right parameter names in the right order. **Unpleasant:** the client is a *snapshot of one build's component set*. Components are contributed by whatever add-ons are installed, so a call that an add-on adds exists in your program and not in your client. When that happens, nothing is broken — you compose the path yourself, because the surface underneath is just HTTP. ## What the generators do not emit The generators walk views, actions and `other` endpoints. **They do not walk persistent connections.** There is no generated method for a `pconn` endpoint in any of the clients, so a streaming endpoint — one that holds the connection open and pushes events as they occur — has to be called by hand with whatever HTTP library you already have. This is the practical answer to "is the client library complete?": it covers three of the four request types, and the missing one is the only one whose responses are not a single document. | request type | generated method? | what you do instead | |---|---|---| | `view` | yes | call the method | | `action` | yes | call the method | | `other` | yes, returning raw text rather than a parsed document | call the method | | `pconn` | **no** | build the path yourself and read the stream | ## Three behaviours worth knowing before you trust one **The key is set once, on the client, and sent as a header.** The Python client's generated methods for actions and `other` endpoints carry an `apikey` parameter in their signature, and that parameter is accepted and never sent. The generator adds it because it has no way of knowing whether a given call will need one; the value that actually authenticates the request is the one passed to the client when it is constructed, which goes out as the header on every call. Passing a key to the method and not to the constructor produces an unauthenticated request, and by the rules of this surface that request is refused in silence. **The client refuses to send the key anywhere but the API.** The Python client rejects any URL that is not under the program's reserved host, with a comment saying it must never leak the key through a proxied request. The separate helper used to make an ordinary proxied request deliberately does not attach the key at all. That is a deliberate guard: the client talks to the target *through* the program, so without it a mistyped URL would send the credential to the site under test. **Status codes are not checked by default.** The Python client takes a flag for validating the response status, and it defaults to off. With it off, a `400` carrying `{"code": …, "message": …}` is parsed and handed back as though it were the result — for a method that unwraps a single-value response, what the caller receives is one of the error object's own fields where a scan identifier was expected. A step that stores that value and carries on will look successful and will be operating on nonsense. ## Choosing between the client and raw HTTP For a pipeline step, the two options trade different things: - **the generated client** gives you named methods, the documented parameter names at the call site, one place to put the credential, and a guard that stops that credential leaving for anywhere but the API; - **raw HTTP** gives you coverage of the whole surface, including the request type the generators skip and any component your client's build did not have, with no dependency to keep in step; - **either way** the response handling is yours: neither shape checks, on your behalf, that what came back is a result rather than an error document. The decision that matters more than either is what the step does with a failure. A generated client with status validation off and a `try` around the call will report success on an error document; a hand-built request that checks the status will not. Neither choice is safe by default — the check has to be yours.