Tutorial: Create a file
This tutorial shows you how to create a file in the cloud via the File Management Service.
Prerequisites
-
You must have a service access key that provides access to the File Management Service. More specifically, your service access key’s scope must include the following permissions:
file-management-api:query:* file-management-api:mutation:*, which would provide access to all queries and mutations of the File Management Service. If you followed the Getting Started chapter, you should already have a service access key with full access to all SBS APIs. Otherwise, see Generate a service access key. -
This tutorial uses cURL (https://curl.se) to initiate HTTP requests. Therefore, cURL must be installed and available in your terminal. You can easily check if that is the case by running the following command in your terminal:
curl --version
As an alternative to using cURL, you could also use a REST client such as Postman or Fiddler and achieve the same result.
Step 1: Authorization
To access the File Management Service, you must populate the x-api-key HTTP header of each request with your secret service access key.
The following example illustrates a cURL request that calls the File Management API to retrieve the API version. If the cURL request returns a version number, your call to the respective API endpoint is authorized. Make sure to replace YOUR_ACCESS_KEY with your actual SBS service access key.
If you have a bash terminal, run:
curl --request POST \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR_ACCESS_KEY' \
--url 'https://file-management-api.socrate.io/graphql' \
--data-binary '@body.json'
If you have a Windows terminal, run:
curl --request POST ^
--header "Content-Type: application/json" ^
--header "x-api-key: YOUR_ACCESS_KEY" ^
--url "https://file-management-api.socrate.io/graphql" ^
--data-binary "@body.json"
Importantly, the cURL requests references a file called body.json, which is in the same directory as the current working directory of the curl script. The body.json file looks as follows:
{
"query": "query version { version }",
"variables": {}
}
In the body.json file, the “query” attribute contains the GraphQL query that you are sending to the API, in this case:
query version {
version
}
Likewise, the “variables” attributes stores the variables accompanying the query. In this example, the variables are empty, since none are required.
To keep things simple, all subsequent GraphQL samples in this tutorial illustrate the GraphQL “query” part and the “variables” part without the cURL call that wraps them. The syntax of the cURL call is the same as already presented above.
Step 2: Create a file
To create a new file in the cloud, run the following mutation:
mutation create_file($input:CreateFileInput) {
createFile(input: $input) {
id
}
}
{
"input": {
"name": "file1.txt"
}
}
Once you run the mutation, the result will contain the unique ID of the created file. Take notice of this ID; you will need it in subsequent steps.
Step 3: Generate the upload URL
So far, the file created in the cloud has no content. To create some file content, you must first generate a temporary URL at which you can upload the content. Run the following GraphQL query to obtain the upload URL:
query($filter:FilesFilter, $sec:Int) {
files(filter:$filter){
items {
id
name
status
uploadUrl(expiresIn: $sec)
}
}
}
In variables, make sure to replace the file ID with the one you obtained previously. Also, note that the URL expiration period is set to 5 minutes (300 seconds); feel free to change this value as required.
{
"filter": {
"id": "YOUR_FILE_ID"
},
"sec": 300
}
The result is similar to the one below:
{
"data": {
"files": {
"items": [
{
"id": "cf0c9840-ce2e-11ed-b8cc-afe40ad143c4",
"name": "file1.txt",
"status": "uploading",
"uploadUrl": "SOME_GENERATED_UPLOAD_URL"
}
]
}
}
}
In the code listing above, notice that the file status is “uploading”. The reason is that the file has no content yet, and it awaits file content to be uploaded. The uploadURL field of the response contains the generated URL that you will need in the next step.
Step 4: Upload the file content
To simulate the upload of the actual file content, we will use cURL in this example. If you are using a tool like Postman or Fiddler, or perhaps program code written in a language of your choice, the upload operation consists of initiating a PUT request that takes content from a local .txt file and sends it to the upload URL obtained previously.
-
Create a test.txt file on your local computer and edit it so that it contains some dummy text that you want to use as file content.
-
Do one of the following:
- If you have a bash terminal, run:
curl --location --request PUT 'YOUR_UPLOAD_URL' --header 'Content-Type: text/plain' --data '@/path/to/your/test.txt' - If you have a Windows terminal, run:
curl --location --request PUT "YOUR_UPLOAD_URL" --header "Content-Type: text/plain" --data "@C:\test.txt"
View the updated file content
To view or download the file, you must create a temporary download URL, as illustrated in the code listing below.
query($filter:FilesFilter, $sec:Int) {
files(filter:$filter){
items {
id
name
status
downloadUrl(expiresIn: $sec)
}
}
}
Note that in the code listing below the URL is set to expire in 5 minutes (300 seconds); you can change this value as required.
{
"filter": {
"id": "YOUR_FILE_ID"
},
"sec": 300
}
The result will include the generated download URL, for example:
{
"data": {
"files": {
"items": [
{
"id": "cf0c9840-ce2e-11ed-b8cc-afe40ad143c4",
"name": "file1.txt",
"status": "done",
"downloadUrl": "YOUR_DOWNLOAD_URL"
}
]
}
}
}
You can now use cURL (or another REST client) to check that the new file content is available at the download URL.
For bash terminals, run:
curl --location 'YOUR_DOWNLOAD_URL'
For Windows terminals, run:
curl --location "YOUR_DOWNLOAD_URL"