Assets API
Assets¶
Assets are files that you can upload to giosg system and that are publicly available. They are useful to hosts resources for your custom giosg products or your website components!
Even though asset contents are publicly available, they can only be accessed with an URL. In other words, only your organization members are able to see the list of your organization assets. When the asset is used somewhere, e.g. on your custom chat dialog or your website, anyone is (and need to be) able to download its contents and see its public attributes.
An asset resource has the following attributes.
| Attribute | Type | Editable | Description |
|---|---|---|---|
id |
UUID | read-only | UUID string identifier |
name |
string | required | Short, human-readable name. |
description |
string | optional | Human-readable description |
organization_id |
UUID | read-only | The ID of the owner organization |
file_name |
string | read-only | The original file name of the uploaded file |
url |
string | read-only | The full URL for original, uploaded file. Use this URL to link to your asset! |
size |
integer | read-only | Size of the uploaded file in bytes |
content_type |
string | read-only | Content type of the uploaded file, e.g. image/jpeg (or null if unknown) |
kind |
string | read-only | What kind of file the asset is: "image", "css", "javascript", "font" or null (unknown) |
charset |
string | optional | Character encoding for a text file, e.g. utf-8 (or null if binary or unknown). Must be a valid encoding name. |
created_at |
datetime | read-only | When the asset was created |
created_by_user_id |
UUID | read-only | The ID of the person who created this asset |
created_by_user |
object | read-only | The person resource who created this asset |
updated_at |
datetime | read-only | When the asset name or description was last time updated |
updated_by_user_id |
UUID | read-only | The ID of the person who last time updated this asset |
updated_by_user |
object | read-only | The person resource who last time updated this asset |
width |
integer | read-only | The width of an image in pixels. Available for images only. It is null for other assets. |
height |
integer | read-only | The height of an image in pixels. Available for images only. It is null for other assets. |
Upload a new asset¶
Upload a file creating a new asset for a organization.
POST /api/v5/orgs/<organization_id>/assets
Warning
IMPORTANT! In contrast to the all other API endpoints, this only accepts multipart/form-data requests, because you need to upload a file with the request. The request payload takes the following attributes.
| Attribute | Type | Editable | Description |
|---|---|---|---|
upload |
file | required | The asset file to be uploaded. File name is required. This field is optional when updating existing asset. |
name |
string | optional | Name for the newly created asset. If omitted, defaults to the file name. Otherwise, it must be a non-empty string value. |
charset |
string | optional | Character encoding for a text file, e.g. utf-8. Must be a valid encoding name. Defaults to null, meaning that the encoding is undefined. It is highly recommended to define a correct encoding for the uploaded text files if they are containing special characters, otherwise browsers might not read them correctly. |
description |
string | optional | Description for this asset. |
This endpoint returns:
- 201 if the request was successful
- 400 if required attribute is missing from the request
- 400 if the upload would exceed your organization's free asset storage space
- 401 if you are not authenticated
- 403 if you do not have active subscription
- 403 if you do not have access to the organization
List assets¶
Get a paginated collection of all the assets of your organization:
GET /api/v5/orgs/<organization_id>/assets
The endpoint accepts the following GET parameters.
| Parameter | Type | Default | Description |
|---|---|---|---|
ordering |
ordering | created_at |
Ordering of results with options created_at, updated_at, name, kind or content_type in ascending order (- for descending). |
kind |
string | (none) | If given, returns Assets with the given kind. |
content_type |
string | (none) | If given, returns Assets with the given content_type. |
description |
string | (none) | If given, returns Assets with the given description. Note: this is case sensitive. |
This endpoint returns:
- 200 if the request was successful
- 401 if you are not authenticated
- 403 if you do not have active subscription
- 403 if you do not have access to the organization
Retrieve a single asset¶
GET /api/v5/orgs/<organization_id>/assets/<asset_id>
This endpoint returns:
- 200 if the request was successful
- 401 if you are not authenticated
- 403 if you do not have active subscription
- 403 if you do not have access to the organization
Update an asset¶
You may update the name and/or description attributes of an asset. Alternatively you may also upload new file by providing upload in payload. In this case you may also change the charset attribute. Note that charset can only be changed when uploading content for the asset.
PUT /api/v5/orgs/<organization_id>/assets/<asset_id>
PATCH /api/v5/orgs/<organization_id>/assets/<asset_id>
This endpoint returns:
- 200 if the request was successful
- 400 if required attribute is missing from the request
- 401 if you are not authenticated
- 403 if you do not have active subscription
Delete an asset¶
You may delete your assets. Their size is freed for new asset uploads.
DELETE /api/v5/orgs/<organization_id>/assets/<asset_id>
NOTE: Any previous URL (the url attribute) for the asset will stop working and the files won't be available for download any more. However, this might take a while to take effect.
This endpoint returns:
- 201 if the request was successful
- 401 if you are not authenticated
- 403 if you do not have active subscription
- 403 if you do not have access to the organization
Retrieve organization's storage information¶
You may check your organization's current asset storage space usage:
GET /api/v5/orgs/<organization_id>/quota
This returns an object with the following attributes:
| Attribute | Type | Description |
|---|---|---|
free_space |
integer | Total free space for new assets, in bytes |
usage |
integer | Sum of all your organization asset sizes, in bytes |
limit |
integer | The maximun allowed sum of your organization asset sizes, in bytes |
This endpoint returns:
- 200 if the request was successful
- 401 if you are not authenticated
- 403 if you do not have active subscription
- 403 if you do not have access to the organization