Add example to use API with curl

[mdouchin]

I all,

I know there is the excellent qfieldcloud-sdk written in Python to make requests to QFieldCloud API.

I would like to propose a way to test it with CURL. I have managed to test many requests, by failed to upload a JPG image

Do you think this curl examples can benefit for other users ?

# Params
QFIELDCLOUD_URL=https://your.qfieldcloud.yop/api/v1/
QLOGIN=some_user
QPASSWORD=your_password

# Authentication : get token
TOKEN=$(curl -X 'POST' \
  ${QFIELDCLOUD_URL}auth/login/ \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d "{\"username\": \"${QLOGIN}\", \"password\": \"${QPASSWORD}\"}"  | jq -r '.token'
) && echo $TOKEN

# Get user info
echo $(curl -X 'GET' ${QFIELDCLOUD_URL}auth/user/ -H "Authorization: Token ${TOKEN}" -H 'accept: application/json')

# Get user projects
echo $(curl -X 'GET' ${QFIELDCLOUD_URL}projects/ -H "Authorization: Token ${TOKEN}" -H 'Content-Type: application/json' -d '{"limit": "2"}')

# Get files from a given project
PROJECT_ID=072c0a9b-4d45-4a65-8fdb-9c871ca90c8b
echo $(curl -X 'GET' ${QFIELDCLOUD_URL}files/${PROJECT_ID}/ -H "Authorization: Token ${TOKEN}" -H 'Content-Type: application/json' -d '{"skip_metadata": "1"}')

# Download a project file locally
REMOTE_FILE_NAME="media/photos/my_layer/observation_20251013155218713.jpg"
LOCAL_FILE_NAME=/tmp/test.jpg
curl -X GET -L ${QFIELDCLOUD_URL}files/${PROJECT_ID}/${REMOTE_FILE_NAME} -H "Authorization: Token ${TOKEN}" --output "$LOCAL_FILE_NAME" && ls -lh $LOCAL_FILE_NAME

# Upload a file to a project
LOCAL_FILE_NAME=/tmp/test.jpg
REMOTE_FILE_NAME="media/photos/my_layer/test.jpg"
curl -X POST -L ${QFIELDCLOUD_URL}files/${PROJECT_ID}/${REMOTE_FILE_NAME} -H "Authorization: Token ${TOKEN}"  -H "Accept: application/json" --form file=@"${LOCAL_FILE_NAME}"

# THE LATTER DOES NOT WORK
# Logs reports the following error : The key \"file\" was not found in `request.data`. Sending report to Sentry.
# I tried with --data-binary or --data with no success
# I tried without the -L with no success
# I also tried without the BASH variable with the real file name like file=@/tmp/test.jpg

The upload failed with returned message {"code":"empty_content","message":"Empty content"}

[suricactus]

Hi @mdouchin , thanks for the suggestion.

There are a few notes which will allow the documentation team to make informed decision:

1. I still think the Python SDK can be used as a reference implementation how to use the API. If we describe each and every endpoint in the static docs will duplicate the effort which IMO is not something we can afford now.
2. Automated tools like https://app.qfield.cloud/swagger should be the ones that actually show usage in different languages/frameworks. The Swagger UI already has the functionality to output curl commands.
3. Currently due to hard to explain bug in the upstream module that autogenerates the OpenAPI (swagger) schema, we do not show the files endpoints. This is going to be fixed in the next few months when we finally drop support for legacy storage.
4. All that said, a hardcoded static example in the markdown docs for 1. login 2. create project 3. upload project file would not be terrible idea. It's more do we want to maintain such thing when the Swagger UI should usually take care of it.

If we have a question "how to use curl?" like this issue, I guess there are others struggling with curl and our files endpoint. Also curl is a universal request language.

FYI @SeqLaz @beanzmo

[mdouchin]

Hi @mdouchin , thanks for the suggestion.

There are a few notes which will allow the documentation team to make informed decision:

1. I still think the Python SDK can be used as a reference implementation how to use the API. If we describe each and every endpoint in the static docs will duplicate the effort which IMO is not something we can afford now.

I full agree !

2. Automated tools like https://app.qfield.cloud/swagger should be the ones that actually show usage in different languages/frameworks. The Swagger UI already has the functionality to output `curl` commands.

Yes, I used it to add the correct headers in some of the curl requests written above. Very handy indeed !

3. Currently due to hard to explain bug in the upstream module that autogenerates the OpenAPI (swagger) schema, we do not show the `files` endpoints. This is going to be fixed in the next few months when we finally drop support for legacy storage.

Oh, I did not guess a bug had prevented the files endpoint to be documented. I wondered why it was not exposed. Great news, it will be present when the legacy storage will be dropped.

4. All that said, a hardcoded static example in the markdown docs for 1. login 2. create project 3. upload project file would not be terrible idea. It's more do we want to maintain such thing when the Swagger UI should usually take care of it.

Ok, please tell me if you want me to create a PR in this direction.

If we have a question "how to use curl?" like this issue, I guess there are others struggling with curl and our files endpoint. Also curl is a universal request language.

I search among the github issues, but could not find any curl example here.

Thanks for your detailed answer

[suricactus]

If we have a question "how to use curl?" like this issue, I guess there are others struggling with curl and our files endpoint. Also curl is a universal request language.

I search among the github issues, but could not find any curl example here.

I meant that this issue is the first one, but more would come.

Ok, please tell me if you want me to create a PR in this direction.

@beanzmo and @SeqLaz will follow-up on this. I am here just to help with technical answers and reviews, but content and organization-wise it is with them.