Sonatype IQ Server API Client(s)

---

This repository produces generated API Clients in various languages and frameworks for use by Customers and other projects.

Supported Languages & Frameworks

Language / Framework	Sonatype IQ Version Added	Public Package Link
Golang / Go	164
Python	177
Typescript (fetch)	156

Known Issues

There are a number of known issues and changes required to the official OpenAPI spec to generate useful client libraries.

These are all codified in update-spec.py which can be used to obtain the latest OpenAPI Specification from a running Sonatype IQ Server, apply the required modifications and transform from JSON to YAML - outputting the result to spec/openapi.yml.

The below subsections document these changes and limitations - but you should rely on update-spec.py primarily.

APIs Excluded from Generation

The following API endpoints are removed from the schema prior to generation of the API Client libraries.

API Endpoint	Method	Reason
/api/v2/licenseLegalMetadata/customMultiApplication/report	POST	Relies on a schema of undefined object - generated code is invalid in Typescript.
/api/v2/product/license	POST	Relies on a schema of undefined object - generated code is invalid in Typescript.
/api/v2/product/license	DELETE	Relies on a schema of undefined object - generated code is invalid in Typescript.
/api/v2/config/saml	PUT	Relies on a schema of undefined object - generated code is invalid in Typescript.

Additional Changes to OpenAPI Schema prior to Generation

See update-spec.py for all changes.

Getting the latest OpenAPI Schema

Get it from your Sonatype IQ Server at /api/v2/endpoints/public.

Generation of API Clients

docker run --rm -v "$(PWD):/local" openapitools/openapi-generator-cli batch --clean /local/typescript.yaml

docker run --rm -v "$(PWD):/local" openapitools/openapi-generator-cli generate -i /local/spec/openapi.yaml -g typescript-fetch -o /local/out/test -c /local/openapi-config.yaml -v > out.log

Diagnosing Responses that are not Schema Compliant

In the rare event that Sonatype IQ Server provides a response that does not validate against the schema (our patched schema to be clear), things can be silent - you just never get a response in your code.

Through the use of Postman and opeapi-request-response-validation project by Beppe Catanese, we can quickly and accurately see where response validation failures occur.

1. Configure the request for which you are not getting a response in Postman exactly as it was sent
2. To that request (you can do this in a Collection if you are using Collections too), add a Test with the code:

    // define object
    openapiRequestResponseValidation = {
    // define function
    validate: function(pm) {
   
        const postRequest = {
            url: 'http://localhost:8080/validate',
            method: 'POST',
            header: {'Content-Type': 'application/json'},
            body: {
            mode: 'raw',
            raw: JSON.stringify({ 
                method: pm.request.method, 
                path: pm.request.url.getPath(),
                headers: pm.request.headers,
                requestAsJson: (pm.request.body != "") ? pm.request.body.raw : null,
                responseAsJson: pm.response.text(),
                statusCode: pm.response.code
                })
            }
        };
   
        pm.sendRequest(postRequest, (error, response) => {
            if(error != undefined) {
                pm.expect.fail('Unexpected error ' + error);
            } else {
                var data = response.json();
   
                if(data.valid == false) {
                    console.log(data.errors);
                }
   
                pm.test("OpenAPI validation", () => {
                    pm.expect(data.valid, "Invalid request/response (check Console)").to.equal(true);
                });
   
            }
        });  
      }
    };
   
    // invoke function
    openapiRequestResponseValidation.validate(pm);
   

3. Start the openapi-request-response-validation Container locally:

   docker run -p 8080:8080 -v ./spec:/openapi -it --rm gcatanese/openapi-request-response-validation
   

4. Execute the request in Postman - if the test does not show as passed then you can get details of the failure from two places:
   1. The Postman console
   2. The logs from the running Container

Changelog

See our Change Log.

Releasing

We use semantic-release to generate releases from commits to the main branch.

We aim to keep the MINOR version component in-line with the version of Nexus IQ Server for which the API Client is generated - i.e. 1.156.x are all releases generated for the API specification as shipped with Sonatype IQ Server version 156.

For example, to perform a "patch" release, add a commit to main with a comment like below. The fix: prefix matters.

fix: the problem resolved goes here

The Fine Print

Remember:

It is worth noting that this is NOT SUPPORTED by Sonatype, and is a contribution of ours to the open source community (read: you!)

• Use this contribution at the risk tolerance that you have
• Do NOT file Sonatype support tickets related to nexus-iq-api-client
• DO file issues here on GitHub, so that the community can pitch in

Phew, that was easier than I thought. Last but not least of all - have fun!