Swagger: UUID required on project creation

[stboissdev]

Why the uuid is required on create project via API ?

it could be generated by the application as by the GUI and return on response

[stevespringett]

The UUID is not required on project creation. If it's supplied, it will be ignored.

A valid request to create a project would like like:

curl -X "PUT" "http://localhost:8080/api/v1/project" \
     -H 'X-API-Key: Tq1TOYF5GuUCJoUYS1NALfwASrXOw75O' \
     -H 'Content-Type: application/json' \
     -d $'{
  "name": "My Project",
  "version": "1.0.0",
  "description": "Sample project"
}'

[stboissdev]

with Swagger UI Console in chrome, Model isn't clear.

Project {
name (string),
description (string, optional),
version (string, optional),
purl (string, optional),
uuid (string),
...

[stevespringett]

I had a feeling you were referencing Swagger.

The Swagger spec, while a step in the right direction, isn't capable of accurately documenting many modern APIs, including the ones defined in Dependency-Track. Per spec, there are some things the spec simply ignores or makes false assumptions about. Many of these have been corrected in OpenAPI 3, which Dependency-Track will eventually upgrade to. See stevespringett/Alpine#1

The second issue with Swagger isn't the spec, rather the various implementations. In this case, the Java implementation is half-baked at best. In JAX-RS it's common to have automatically deserialized pojos enter a method when the resource is called. What you're seeing in the Swagger doc is a result of that - the entire object (and possibly all child objects) without any indication of what is required or not. The Swagger Java implementation does not support the Bean Validation API starting with JSR 303 and including all the newer JSRs built on top of it. If Swagger supported it, it would see the @NotNull annotation only on the project name and UUID. This would indicate that these two fields are the only required ones. Swagger also doesn't support JDO annotations. It if did, it would have identified the UUID field as being auto generated by the persistence layer, leaving only the project name field as required - which would be an accurate representation of the API.

I haven't looked at the new OpenAPI implementation. Hopefully it solves all/most of this. If not, the only alternative would be to rip out all automated Swagger support and replace it with manually created JSON or YAML. This would be a huge effort and involve removing a lot of Swagger code (which I'm in favor of since in many of the methods Swagger is documenting contain more lines of Swagger code than actual implementation code), and ensuring that any API changes are made in two places potentially creating situations where the two will diverge over time.

The common REST Javascript functions defined in https://github.com/stevespringett/dependency-track/blob/master/src/main/webapp/assets/rest.js should help make better sense of the API. This is what the UI uses when interfacing with the server.

As a final though, use Swagger as guidance rather than an exact API specification. The spec limitations and implementation issues prevent it from being used as an exact API specification. Hopefully with the help of the community, this will improve over time.

[eoftedal]

@stevespringett It would actually be nice if it used the UUID if provided. For each buildconfig in our CI-system, we could automate creating a UUID, and posting the buildconfig to dependency-track as a project. Duplicate UUIDs should result in 409 conflict.

[stevespringett]

Closing

[lock]

This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.