Added #9413: Asset file upload from API

[Scarzy]

Description

Add support for uploading, listing, downloading, and deleting files on an asset via the API.

This is to enable automation with handling files on assets.

Fixes #9413

Type of change

Please delete options that are not relevant.

• New feature (non-breaking change which adds functionality)
• This change requires a documentation update

How Has This Been Tested?

• Upload a file

curl --request POST --url http://localhost:8080/api/v1/hardware/1/files --header "Authorization: Bearer xxxxxxxxxx" -F "file[]=@test.txt" --verbose

• List the files

curl --request GET --url http://localhost:8080/api/v1/hardware/1/files --header "Authorization: Bearer xxxxxxxxxx" --header 'accept: application/json' --verbose

• Get a file

curl --request GET --url http://localhost:8080/api/v1/hardware/1/file/1 --header "Authorization: Bearer xxxxxxxxxx" --output downloadedfile --verbose

• Delete a file

curl --request DELETE --url http://localhost:8080/api/v1/hardware/1/file/1 --header "Authorization: Bearer xxxxxxxxxx" --header 'accept: application/json' --verbose

In all cases the web GUI, the JSON response, and the downloaded file were visually inspected to ensure they were as expected.

I have tested it successfully with the following file types;

• text file
• PDF
• JPEG

I also tried with a binary file with random contents, and this didn't work. As far as I can tell the file disappeared somewhere inside laravel, and never made it to the controller. If interested, the random file was created via;

dd if=/dev/urandom of=random.bin bs=1M count=1

Test Configuration:

• PHP version: 8.1.2
• MySQL version: MariaDB 10.6.16
• Webserver version: Apache 2.4.52
• OS version: Ubuntu 22.04 LTS

Checklist:

• I have read the Contributing documentation available here: https://snipe-it.readme.io/docs/contributing-overview
• I have formatted this PR according to the project guidelines: https://snipe-it.readme.io/docs/contributing-overview#pull-request-guidelines
• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

[welcome]

💖 Thanks for this pull request! 💖

We use semantic commit messages to streamline the release process and easily generate changelogs between versions. Before your pull request can be merged, you should update your pull request title to start with a semantic prefix if it doesn't have one already.

Examples of commit messages with semantic prefixes:

• Fixed #<issue number>: don't overwrite prevent_default if default wasn't prevented
• Added #<issue number>: add checkout functionality to assets
• Improved Asset Checkout: use new notification method for checkout

Things that will help get your PR across the finish line:

• Document any user-facing changes you've made.
• Include tests when adding/changing behavior.
• Include screenshots and animated GIFs whenever possible.

We get a lot of pull requests on this repo, so please be patient and we will get back to you as soon as we can.

[what-the-diff]

PR Summary

• Added Asset Files Management Functionality
  A new file handling system has been implemented in AssetFilesController.php file, allowing for the management of file uploads and deletions.

• Enhanced Base64 Conversion
  Changes were made to the UploadFileRequest.php file, incorporating a new trait for converting Base64 formatted data into files.

• Update to CSS Files
  The CSS files, signature-pad.min.css, skin-black.css, and several skin-related CSS files, were updated to change the visual aspects of the site. This included altering the background and text colors for different areas, as well as modifying the aesthetic during hover and active states for various elements.

• Language File Adjustments
  The language resources file admin/hardware/message.php was updated to include new messages for downloading files and importing items for end users.

• API Route Enhancements
  The API routes file api.php was updated with additional routes to enable more efficient managing of asset files. This includes actions such as storing, listing, showing, and deleting files.

• CSS Files Reduction
  Non-essential lines of code in signature-pad.min.css and skin-black.css files were removed to streamline the CSS code.

• Visual Overhaul for Interface Skins
  Several CSS files, including those denoted as skin-black.css, skin-blue.css, skin-green.css, skin-orange.css, skin-purple.css, skin-red.css, skin-contrast.css and skin-yellow.css were modified to implement a visual overhaul of the platform's skins. This includes changing background and text colors to provide a new look and feel for the user interface.

[marcusmoore]

@Scarzy I'll follow up on your comment about testing here

I haven't created a test for the feature yet, as I was hoping to run the existing tests first, but I am conscious that as a new feature for the API it probably needs a new test

First off, thanks for being thorough about testing. I appreciate that 😄

What issues were you running into getting the test suite up and running? It's not part of the PR template so you might have missed it but have you seen the testing docs here?

[Scarzy]

@marcusmoore

What issues were you running into getting the test suite up and running? It's not part of the PR template so you might have missed it but have you seen the testing docs here?

I have read the testing page, yes.
My original issues with testing were that my host machine didn't have a suitable version of PHP available, and I couldn't get docker to behave with a clean copy of my branch, the docker image would refuse to start up (my original development was done using the standard docker image and copying my changes in/out, which I didn't deem to be suitable for testing before submission).

I have now got a clean copy of my branch running in an Ubuntu 22.04 VM, and my current error is;
In TestCommand.php line 62 'Class "PHPUnit\Runner\Version" not found'

phpunit (v9.5.10) is definitely installed, I had to install that through apt as a separate step

[Scarzy]

Ok, got past that issue. I'm not familiar with composer and didn't realise I needed to rerun the install step without the "--no-dev" argument.

I'm now able to run the testing, I get 12 fails 224 passes, the fails are;

FAIL Tests\Unit\CustomFieldTest
⨯ db name chinese (Failed asserting that two strings are equal.)
⨯ db name japanese (Failed asserting that two strings are equal.)
⨯ db name korean (Failed asserting that two strings are equal.)
⨯ db name non latin euro (Failed asserting that two strings are equal.)
⨯ db name turkish (Failed asserting that two strings are equal.)
⨯ db name arabic (Failed asserting that two strings are equal.)

I also had 6 failures in LDAP (primarily 'Undefined constant "App\Models\LDAP_OPT_REFERRALS"'), but as I haven't got LDAP set up, I'm now running the tests with the LDAP group excluded.
I shouldn't have gone anywhere near those languages above, is it safe for me to exclude them?

As I'm now able to run the tests, I'll get some tests for the new file uploads sorted and report back.

[marcusmoore]

@Scarzy I appreciate you pushing through this.

I'm using Herd and not docker so I'm not sure of any quirks in getting the app running for development in Docker.

I have now got a clean copy of my branch running in an Ubuntu 22.04 VM, and my current error is;
In TestCommand.php line 62 'Class "PHPUnit\Runner\Version" not found'
phpunit (v9.5.10) is definitely installed, I had to install that through apt as a separate step

I would assume that would work but ideally the composer file will get you up and running (without that --no-dev flag since that skips installing PHPUnit. Have you seen the docs at the bottom of the Docker page for developing in docker? I see you're pushing through but it might be helpful if you missed that.

If you're able to write up tests and focus on running just the ones you create you can skip the ones you mentioned giving you problems in this case.

[Scarzy]

@marcusmoore

If you're able to write up tests and focus on running just the ones you create you can skip the ones you mentioned giving you problems in this case.

Thanks, will do.

Can I just check; are there any tests for file interactions for existing functionality?

I was looking to see how they handled generating/using temporary files, e.g. for testing file upload through the GUI, or image upload via GUI or API. But I can't find any reference to any such tests in the tests directory.

I tried to sanity check myself on this, and running the following from the root of the snipe-it checkout, and ignoring any results relating solely to new files I've created, I get;

find tests/ -iname "*image*"      # No results
find tests/ -iname "*file*"      # No results
grep tests/ -R -i -e "file" -e "image"
./Feature/Api/Locations/LocationsForSelectListTest.php:    public function testLocationsAreReturnedWhenUserIsUpdatingTheirProfileAndHasPermissionToUpdateLocation()
./Feature/Api/Locations/LocationsForSelectListTest.php:            ->withHeader('referer', route('profile'))
./TestCase.php:        if (!file_exists(realpath(__DIR__ . '/../') . '/.env.testing')) {
./TestCase.php:                '.env.testing file does not exist. Aborting to avoid wiping your local database.'

[Scarzy]

Ok, tests for all features created.

I believe all I'm missing now is updating the API documentation. Is someone able to point me to this?

[snipe]

@Scarzy - Our documentation platform doesn't allow you to easily add docs to the API documentation, but if you let me know what you'd like added, I can do that for you.

[Scarzy]

@Scarzy - Our documentation platform doesn't allow you to easily add docs to the API documentation, but if you let me know what you'd like added, I can do that for you.

@snipe Basically just adding the following endpoints:

/hardware/:id/files GET -> List uploaded files for asset
/hardware/:id/files POST -> Upload new file to asset
/hardware/:id/files/:fileid GET -> Download file for asset
/hardware/:id/files/:fileid DELETE -> Delete file from asset

As I believe I have now done all of my bits for this, I will change this PR to no longer be in draft.