REST API: A Basic Example

After the release of version 3.4.0, the project has added a REST API to FOSSology. This allows for a number of use cases, such as:

  • Integration of FOSSology into the CI/CD environments
  • Upload packages and trigger their scanning from other applications
  • Get SPDX files just by using tools from the command line (which can issue https requests, such as curl or wget)

Getting Started: Getting Access

While first versions of contributions of the REST API implementation were providing basic authentication (username and password), the revised version allows for managing API access keys, configured either to have read access only or read write access, set invalidation or delete access keys when they get compromised. A user can obtain tokens in the Admin menu and then use the Edit User page (editing the own user account). The Interface looks as follows:

A Simple Flow example

The following example we present the following  calls:

  1. List folders
  2. Create one folder
  3. List folder (again)
  4. Upload some package to analyse
  5. Trigger analyses
  6. Trigger SPDX report generation
  7. Download generated SPDX report

For the initial call, when fossology has been setup, a simple functional test can be done as following – it is assumed that FOSSology runs on the same machine, either using deployment by vagrant, docker, or by source code. Maybe, for own deployments, host name and port needs to be modified. The given curl options deisable secruity checks

List all folders

$ curl -k -s -S -X GET http://localhost:8081/repo/api/v1/folders
  -H "Authorization: Bearer eyJ0eXAi…"
-> [{"id":1,"name":"Software Repository","description":"Top Folder"}]

Add one folder

$ curl -k -s -S -X POST http://localhost:8081/repo/api/v1/folders
  -H 'parentFolder: 1'
  -H 'folderName: rest'
  -H "Authorization: Bearer eyJ0eXAi…"
-> {"code":201,"message":4,"type":"INFO"}

List all folders (again)

§ curl -k -s -S -X GET http://localhost:8081/repo/api/v1/folders
  -H "Authorization: Bearer eyJ0eXAi…"
-> [{"id":1,"name":"Software Repository","description":"Top Folder"},{"id":4,"name":"rest","description":""},{"id":3,"name":"test","description":""}]

Upload a package

Now we need to take the folder id, here “4”, where we would like to upload the package to and the package (in this case “time-1.7.tar.gz”)

§ curl -k -s -S -X POST http://localhost:8081/repo/api/v1/uploads \
   -H "folderId: 4" \
   -H 'uploadDescription: created by REST' \
   -H 'public: public' -H 'Content-Type: multipart/form-data' \
   -F 'fileInput=@"time-1.7.tar.gz";type=application/octet-stream' \
   -H "Authorization: Bearer eyJ0eXAi…"
 -> {"code":201,"message":3,"type":"INFO"}

Trigger analyses jobs

In the next step, the analyses jobs are triggered, note that folder id and upload id needs to be inserted:

$ curl -k -s -S -X POST http://localhost:8081/repo/api/v1/jobs \
  -H "folderId: 4" \
  -H "uploadId: 3" \
  -H "Authorization: Bearer eyJ0eXAi..." \
  -H 'Content-Type: application/json'
    --data '{
      "analysis": {
        "bucket": true,
        "copyright_email_author": true,
        "ecc": true, "keyword": true,
        "mime": true,
        "monk": true,
        "nomos": true,
        "package": true
      },
      "decider": {
        "nomos_monk": true,
        "bulk_reused": true,
        "new_scanner": true
      }
    }
-> {"code":201,"message":5,"type":"INFO"}

Trigger report generation

After the analyses has been done, you can trigger the reporting generation, for example, for generating an SPDX report:

$ curl -k -s -S -X GET http://localhost:8081/repo/api/v1/report \
    -H "uploadId: 3" -H 'reportFormat: spdx2' \
    -H "Authorization: Bearer eyJ0eXAi…" \
  -> {"code":201,"message":"localhost\/repo\/api\/v1\/report\/6","type":"INFO"}

Download generated report

At final call, the report file is downloaded, note that this call must include the report id, returned from the previous call:

$ curl -k -s -S -X GET http://localhost:8081/repo/api/v1/report/6 \
    -H "Authorization: Bearer eyJ0eXAi…" \
    -H 'accept: text/plain' > report.rdf.xml

Which downloads the document right onto your hard drive with the name report.rdf.xml.

Getting Documentation

For full documentation, you could use the editor of the Swagger project at http://editor.swagger.io/

Using this editor, you can choose to import an API description by importing from a URL (In the menu “file”). The FOSSology API description file is provided in the source tree at https://raw.githubusercontent.com/fossology/fossology/master/src/www/ui/api/documentation/openapi.yaml