API Internals

Important things to note regarding the actual implementation of contentapi (IE things not exposed to the users but just part of the implementation)

Image Manipulator

We've had various problems using the popular image manipulation libraries for resize/crop etc. We need such a library to generate the arbitrary thumbnails on request, and to auto-resize images that are too large on upload. The library, https://github.com/SixLabors/ImageSharp, is still used by default in the API, and works just fine for many workloads. However, it is unsuitable for a long running process on a critical production server, as their memory usage model is just incompatible with our needs. You may find it perfectly acceptable when running yourself, so don't fret about changing away from it.

You can change the image manipulation method using the ImageManipulator setting in appsettings.json. The default, called "direct", manipulates images directly within contentapi using the ImageSharp library, and is the fastest way we have available. The alternative is ImageManipulator_IMagick (called "imagick"), which requires an installation of ImageMagick to function. This is significantly slower, as it has to spawn and wait for at least one additional process for every image manipulation, and potentially more for certain filetypes. However, by taking the work out of contentapi, we avoid the dotnet memory model, and it makes the memory usage on the server SIGNIFICANTLY more stable. Thus, the IMagick manipulator trades better memory usage for slower execution.

Email service

By default, no email sender is configured. This is because it requires secrets that aren't available by default, such as the smtp server and particularly the username and password. Furthermore, emails are not necessarily integral to contentapi usage, so we simply dump the emails to the filesystem for debugging purposes. This is controlled by the EmailSender setting in appsettings.json, using the default value of "file". Change the setting to "functional" and set the appropriate settings in the EmailConfig section to set up real emails if you wish.

Image uploads + S3

By default, we simply put uploaded files into an "uploads" folder next to contentapi. This is fine for running locally, and is probably perfectly fine for most needs, however we also include a special "S3" upload store which is able to upload AND serve files to an S3 bucket, without the users knowing or changing the URLs. If you wish to use this functionality, you will need to configure a shared AWS credentials file (a system created by AWS, not me, see https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/net-dg-config-creds.html) and configure the appropriate settings in the AWS section of appsettings.json. It's a bit involved, and you should read through the configuration sections of the AWS dotnet documentation thoroughly. Again, you don't need to do any of this, it's just an option if you need it (we use it on our production servers).