Single-part Uploads

Sentera's GraphQL API supports uploading a file to Sentera's cloud storage using a single PUT request. This approach is easiest to perform and is ideal for smaller files (less than 10MB).

Uploading a file with this approach and then associating it with a FieldAgent resource requires three steps, which are illustrated in the diagram below.

sequenceDiagram
    API Client->>+GraphQL API: 1. Create File Upload
    GraphQL API-->>-API Client: file ID and upload URI
    API Client->>+AWS S3: 2. Upload the file (Upload URI)
    AWS S3-->>-API Client: Return
    API Client->>+GraphQL API: 3. Associate the file with a resource (use file ID)
    GraphQL API-->>-API Client: Return

If you prefer to just dive into some code and get going, there are working code examples that demonstrate the single PUT request file upload workflow available at GitHub.

Step 1 - Create a File Upload

The first thing you need to do is to tell Sentera's platform that you want to upload a file, by creating a file upload.

To do this, use the create_file_upload GraphQL mutation. There is also a create_file_uploads GraphQL mutation that you can use to make uploading multiple files easier. For the purpose of this guide, we'll demonstrate the use of the create_file_upload mutation.

mutation CreateFileUpload {
    create_file_upload(
            filename: "test.geojson"
            content_type: "application/geo+json"
            byte_size: 480452
            checksum: "R1DTObliXS7goESYAqrAOQ=="
            ) {
        id
            url
            headers
    }
}

Your programming language should have a library available to calculate the base64-encoded MD5 checksum of the file. For example, Digest::MD5 in Ruby or SparkMD5 in JavaScript. For more details on generating the required checksum, refer here.

Step 2 - Upload the File

The next step in this workflow is to upload the file to Sentera's cloud storage (AWS S3). The response from the create_file_upload mutation in step 1 contains a pre-signed upload URL that you will use to upload the file with a single PUT request. The response also contains headers that you must provide on your upload request.

How you upload the file to AWS S3 is up to you. AWS provides an SDK that you can use. Or, you can make a PUT request with the URL and headers to upload the file.

Step 3 - Associate the File with a FieldAgent Resource

The final step in the workflow is to use the file upload's id that you obtained in step 1 with a GraphQL mutation to associate the file with a FieldAgent resource (field, survey, feature set, mosaic, etc).

Putting It All Together

Step 1

Here's an example cURL command that demonstrates step 1 of the upload workflow. Replace the auth token with a valid auth token that you generated.

curl -i --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer abc123' \
  --data '{ "query": "mutation CreateFileUploadDemo { create_file_upload ( filename: \"test.geojson\" content_type: \"application/geo+json\" byte_size: 480452 checksum: \"R1DTObliXS7goESYAqrAOQ==\" ) { id url headers } }" }' \
  https://api.sentera.com/graphql

Tip: Here are a couple of shell commands you can run on MacOS to get you the right file size and MD5 checksum to use in the cURL command above:

# Get the size of the file in bytes
stat -f%z test.geojson

# Get the MD5 checksum in base64 encoding
cat test.geojson | openssl md5 -binary | openssl enc -base64

And the response:

{
    "data": {
        "create_file_upload": {
            "id": "apBtwFpbHMiOnsibWVzc2FnZSI6IkJBaHBBMFpLQVE9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--1cadf0aeac8ac03c730ef549710be2e79accdc6c",
            "url": "https://cloudvault-prod-import.s3.us-west-2.amazonaws.com/nj8wh5z7kema07lr011zrx58a6eb?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJOTRNP3QHKMDMNKL%2F20201106%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20201106T183828Z&X-Amz-Expires=604800&X-Amz-SignedHeaders=content-length%3Bcontent-md5%3Bcontent-type%3Bhost&X-Amz-Signature=b1eff856bf414d7a4a61e2be1efc2c62e6e45c179b8df1830bef77474ca7fe12",
            "headers": {
                "Content-Type": "application/geo+json",
                "Content-MD5": "R1DTObliXS7goESYAqrAOQ=="
            }
        }
    }
}

Step 2

Here's an example cURL command that demonstrates step 2 of the upload workflow. Replace the URL with the pre-signed upload URL you obtained in step 1.

curl -i --request PUT \
  --header 'Content-Type: application/geo+json' \
  --header 'Content-MD5: R1DTObliXS7goESYAqrAOQ==' \
  --upload-file 'test.geojson' \
    'https://cloudvault-prod-import.s3.us-west-2.amazonaws.com/nj8wh5z7kema07lr011zrx58a6eb?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJOTRNP3QHKMDMNKL%2F20201106%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20201106T183828Z&X-Amz-Expires=604800&X-Amz-SignedHeaders=content-length%3Bcontent-md5%3Bcontent-type%3Bhost&X-Amz-Signature=b1eff856bf414d7a4a61e2be1efc2c62e6e45c179b8df1830bef77474ca7fe12'

A successful response will return a 200 status code and an empty body.

Step 3

Here's an example cURL command that demonstrates step 3 of the upload workflow. It makes a request to the import_feature_set mutation, and passes the ID of the file obtained in step 1 of the file argument on the mutation. Replace the owner_sentera_id with the ID of a survey that you can access. Also, replace the file ID with the one that you obtained in step 1.

curl -i --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer abc123' \
  --data '{ "query": "mutation ImportFeatureSetDemo { import_feature_set (owner_type: SURVEY, owner_sentera_id: \"a4Rdqyc_CO_uvd2Acme_CV_deve_2d3c31f0c_200325_084220\", name: \"Test Feature Set\", type: UNKNOWN geometry_file_key: \"apBtwFpbHMiOnsibWVzc2FnZSI6IkJBaHBBMFpLQVE9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--1cadf0aeac8ac03c730ef549710be2e79accdc6c\") { status } }" }' \
  https://api.sentera.com/graphql

And the response:

{
  "data": {
    "import_feature_set": {
      "status": "QUEUED"
    }
  }
}