This document explains how to work with files using the API, and we will be updating your organization profile avatar later on as a practical example of this.
The API provides endpoints for uploading and updating files associated with various entities (organizations, users, resources, etc.). You can identify the endpoints that accept files by an object that accept the following fields:
Example
{
"fileName": "string",
"resource": "string"
}Files are handled through a three-step process: retrieving a upload URL, uploading the file to a temporary storage, and then referencing the uploaded file on API calls that accept files.
To retrieve a upload URL, the following endpoint must be used: Get storage url endpoint
The endpoint returns an object containing "id" and "url" values. The "url" is a S3 signed URL which should be used to upload the file itself on the second step. The "id" is what will be referenced as "resource" value on the third step of the process. Refer to the example at the end of the page for a practical example.
This step is very straightforward since you won't be interacting with the API directly. You can use any tool you like to upload the file to the URL provided by the previous step.
Once the file is uploaded, you can reference it on the API call that accepts files. The "resource" value must be the same as the "id" value returned by the previous step. The "fileName" value can be any string you want to identify the file by.
We will be updating your organization profile avatar as a practical example of this. For this example, we will be using Javascript and Axios to make the API calls, but as long as you can make HTTP requests, you can use any programming language or tool you like. Also, make sure to create an API Key before continuing. The steps to create an API Key are provided on the Getting started page.
Example
const axios = require('axios');
const fs = require('fs');
// API Key created on Campai.
const apiKey = '--your-api-key';
// The ID of the organization. If you don't know it, you can retrieve it from the endpoint that returns the information about the API key being used (https://www.campai.com/developer/api/apikey/developer-api-getApiKeyInfo).
const organizationId = '--your-organization-id';
// The file that will be uploaded.
const file = fs.readFileSync('/path/to/file');
// Retrieves a new S3 signed upload URL.
const getUploadUrl = async () => {
const response = await axios.get('https://cloud.campai.com/api/misc/storage/uploadUrl', {
headers: {
'X-API-Key': apiKey,
},
});
return response.data;
};
// Uploads the local file to the upload URL we retrieved.
const uploadFile = (uploadUrl) => {
return axios.put(uploadUrl, file);
};
// Updates the organization profile and assigns the new avatar to it.
const updateOrganizationProfile = async (resourceId) => {
// Since the endpoint that updates the organization profile requires more than just the avatar, first we need to retrieve the current organization data
// so we can keep the other profile information unchanged.
const organizationResponse = await axios.get(
`https://cloud.campai.com/api/organizations/${organizationId}`,
{
headers: {
'X-API-Key': apiKey,
},
}
);
const organization = organizationResponse.data;
// Finally, we update the organization profile. You can see that we are providing existing values to other fields but updating the avatar with new information.
await axios.post(
`https://cloud.campai.com/api/organizations/${organizationId}/profile`,
{
name: organization.name,
brand: organization.brand,
language: organization.language,
foundingYear: organization.foundingYear,
classification: organization.classification,
website: organization.website,
avatar: {
fileName: 'avatar.png', // This can be anything you want.
resource: resourceId,
},
},
{
headers: {
'X-API-Key': apiKey,
},
}
);
};
const run = async () => {
const { id, url } = await getUploadUrl();
await uploadFile(url);
await updateOrganizationProfile(id);
};
run();