Attachment files
Certain entities might have attachments associated with them. An attachment is comprised of a single file as well as additional data and derived file metadata.
At the moment there are two kinds of attachments: StanForD attachments and generic attachments.
StanForD attachments
These attachments represent forest machine data files in the StanForD format.
There are two editions of the format: the initial one retroactively called StanForD classic, based on ASCII files; and the modern one called StanForD 2010, based on XML files. Note that each edition has its own versioning and that classic is no longer being updated.
Attachments can be created with files of both editions. Based on the file extension, the boolean attribute classic will be set. In addition, and as indicated in the StanForD 2010 specification, files with the extension suffix z (zip-compressed) are also accepted, with the boolean attribute compressed being set to true.
File size limit for all StanForD files: 25 MB
The corresponding Media Types when downloading these files are the following:
| Kind | Media Type |
|---|---|
| Classic | application/octect-stream |
| 2010 (uncompressed) | text/xml |
| 2010 (compressed) | application/zip |
Other than the file extension, no further verification of StanForD files is done.
Generic attachments
Generic attachments represent a diverse set of file types that can be associated with a given resource.
Categories
These types can be grouped into the following categories:
- archive: compressed archive of one or multiple files
- data_exchange: format used mostly for data exhange
- geo_raster: geospatial raster graphic
- geo_vector: geospatial vector graphic
- image: visual representation format
- office: format mainly used in office productivity tools
File size limits are determined by category:
| Category | Limit |
|---|---|
geo_raster | 500 MB |
geo_vector | 250 MB |
| all other | 50 MB |
Types
The following are the accepted generic attachment types:
| Type | Title | Category | Extension | Media Type |
|---|---|---|---|---|
| 7z | 7z | archive | .7z | application/x-7z-compressed |
| csv | Comma-separated values | data_exchange | .csv | text/csv |
| doc | MS Word (binary) | office | .doc | application/msword |
| docx | MS Word (XML) | office | .docs | application/vnd.openxmlformats-officedocument.wordprocessingml.document |
| dwg | AutoCAD DWG | image | .dwg | image/vnd.dwg |
| geojson | GeoJSON | geo_vector | .geojson | application/geo+json |
| geotiff | GeoTIFF | geo_raster | .tiff | image/tiff; application=geotiff |
| gif | GIF | image | .gif | image/gif |
| jpeg | JPEG | image | .jpeg | image/jpeg |
| jpeg-wld | JPEG + World file | geo_raster | .zip | application/zip |
| json | JSON | data_exchange | .json | application/json |
| kml | KML | geo_vector | .kml | application/vnd.google-earth.kml+xml |
| kmz | Compressed KML | geo_vector | .kmz | application/vnd.google-earth.kmz |
| odt | Open Document Text | office | .odt | application/vnd.oasis.opendocument.text |
| Portable Document Format | office | application/pdf | ||
| png | PNG | image | .png | image/png |
| png-wld | PNG + World file | geo_raster | .zip | application/zip |
| ppt | MS PowerPoint (binary) | office | .ppt | application/vnd.ms-powerpoint |
| pptx | MS PowerPoint (XML) | office | .pptx | application/vnd.openxmlformats-officedocument.presentationml.presentation |
| rtf | Rich Text Format | office | .rtf | application/rtf |
| shz | Compressed Shapefile | geo_vector | .zip | application/zip |
| tiff | TIFF | image | .tiff | image/tiff |
| tiff-wld | TIFF + World file | geo_raster | .zip | application/zip |
| tsv | Tab-separated values | data_exchange | .tsv | text/tab-separated-values |
| txt | Plain text | office | .txt | text/plain |
| webp | WebP | image | .webp | image/webp |
| wpd | WordPerfect | office | .wpd | application/vnd.wordperfect |
| xls | MS Excel (binary) | office | .xls | application/vnd.ms-excel |
| xlsx | MS Excel (XML) | office | .xlsx | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet |
| zip | ZIP | archive | .zip | application/zip |
Verification
The first verification step is the extension of the file, which must be present in the table above. In addition, the following attachment types allow additional extensions:
- jpeg: .jpg
- tiff: .tif
Files with extension .json will have type geoson if the root is an object with the first property as follows :
"type" : "FeatureCollection"
TIFF images will have type geotiff if the required GeoTIFF GeoKeyDirectoryTag is present in the file.
Files with extension .zip will have the following types if the archive entries meet the respective conditions:
- shz: if there are three files with extensions .shp, .shx, and .dbf with the same basename
- jpeg-wld: if there are two files with the same basename, one JPEG and the other with extension .jpw, .jpgw, or .wld
- png-wld: if there are two files with the same basename, one PNG and the other with extension .pnw, .pngw, or .wld
- tiff-wld: if there are two files with the same basename, one TIFF and the other with extension .tiw, .tifw, or .wld
Finally, most type files will be verified based on the expected binary file signature.
Create attachments
Unlike most of the API, creation of attachments must be done via a POST request having content type multipart/form-data. In addition, each field must be prepended by the suffix attachment:, including the file itself which must be in the field file.
For illustrative purposes only, a possible command to create an attachment using cURL could be:
curl -F attachment:field="value" -F attachment:file=@localfilename.ext API_ENDPOINT_URL
If the name field is not present, it will be set to the filename (without extension).
For attachments with tags, upon creation they must be sent as single string separated by commas. For instance, in the case of cURL:
-F attachment:tags="tag1,tag2,tag3"
All tags will be converted to lowercase and white space will be trimmed.
Update attachments
Attachments only accept partial updates via a PATCH request with content type application/json, whose payload must have the root object attachment. This is because certain attributes of the attachment are automatically derived from the file itself.
To only update the attachment name, the request body could be:
{
"attachment": {
"name": "New Name"
}
}
To set an updatable attribute to null, you must explicitly do so. For instance, to set description to null and update tags:
{
"attachment": {
"description": null,
"tags": ["tag1", "tag2"]
}
}
If you want to replace the attachment file, you will need to delete the attachment first and create a new one.
Download attachment files
Attachments contain an attribute url to access the file URL. The file will be sent with Content-Disposition set to attachment and filename set to the attachment name plus its type extension (see table above).
As with other API endpoints, an access token with Bearer Login Auth might be needed to download attachment files (e.g., for privacy reasons). However, it might the case that setting the corresponding request header might not be feasible, such as the src attribute in img HTML elements. For these cases, there is the alternative URL Signature Auth.
This mechanism is a simplistic but similar approach to other solutions to access protected resources, such as AWS presigned URLS or Azure shared access signatures (SAS).
With URL Signature Auth, a JSON Web Token (JWT) is generated, wich must be appended to the file URL in the query parameter jwt.
To obtain such a token, you must send a POST request with no body to the following endpoint, using the normal Bearer Login Auth via a token with read scope:
/auth/url_signatures
You will receive a single string with the token.
Append this token to the attachment URLs accordingly. For illustrative purposes only:
<img src="/attachments/UUID.ext?jwt=token" />
At the moment, the same token can be used with any supported attachment file download URL —while is valid.
For security reasons these tokens are short-lived (10 minutes), but you can generate as many as needed.