StediDOCS
GuidesAPI Reference
This product is in Developer Preview

Documents

Documents is a product that serves as a repository for storing documents and their associated metadata. Documents can be of any type, so long as they are smaller than 5GB. Documents themselves are immutable once uploaded; however, it is possible to delete them. This behavior allows duplicate detection when required. It also guarantees that once a document is uploaded, it is not overwritten or modified unless it is explicitly deleted beforehand. To facilitate the handling of large files with potentially long timeouts, Documents does not allow the direct posting or getting of documents. Any operation that results in the transfer of the actual document is done using multiple steps which are explained below.

Using Documents

Manually checking document existence by name

Documents does not support idempotency checking by default. In order to avoid creating a duplicate document, Documents provides an endpoint where a document's existence can be checked before proceeding with document creation. A response with a 204 status code signifies that a document with the supplied name already exists in Documents.

  1. Check for existence of document with desired name. It takes a document name as the last portion of the URL.
    curl --request HEAD \
      --url 'https://documentstore.prod.documents.stedi.com/v0/documents/name/file-name-to-check'
    

Manually creating documents

To facilitate handling large files with potentially long timeouts, Documents does not allow the direct posting of documents. Instead, the process of uploading a document has three steps.

  1. Calculate the md5 hash of the file that you intend to upload.
    md5 example-file.json
    
  2. Create a placeholder for the document in Documents.
    • This POST call will require you to pass in a hash and a name where hash is the MD5 checksum of the file to be uploaded, and name is a unique name for the file.
    • The uniqueness of this document name will be enforced for the lifetime of the document. Once the document is deleted, the name can be reused. The name passed in does not need to match the name on disk. It can be used as a mechanism to keep another file with the same name from being uploaded.
    curl --request POST \
    --url 'https://documentstore.prod.documents.stedi.com/v0/documents' \
    --data '{"hash": "example-file-hash", "name": "example-file.json"}' \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/json'
    
  3. Upload the document to the upload_url returned by the previous API call.
    curl --request PUT \
      --url 'upload-url-returned-in-previous-step'  \
      -T example-file.json
    

Manually downloading documents by id

To facilitate handling large files with potentially long timeouts, Documents does not allow the direct downloading of documents. Instead, the process of downloading a file has two steps.

  1. Pull the metadata associated with the file you want to download. It takes a document id as the last portion of the URL.
    curl --request GET \
      --url 'https://documentstore.prod.documents.stedi.com/v0/documents/file-id-to-download'
    
  2. Download the payload of the document from the download_url returned by the previous step.
    curl --request GET \
      --url 'download-url-returned-in-previous-step'
    

Manually downloading documents by name

To facilitate handling large files with potentially long timeouts, Documents does not allow the direct downloading of documents. Instead, the process of downloading a file has two steps.

  1. Pull the metadata associated with the file you want to download. It takes a document name as the last portion of the URL.
    curl --request GET \
      --url 'https://documentstore.prod.documents.stedi.com/v0/documents/name/file-name-to-download'
    
  2. Download the payload of the document from the download_url returned by the previous step.
    curl --request GET \
      --url 'download-url-returned-in-previous-step'
    

Manually deleting documents by id

  1. Delete a document using the document id.
    curl --request DELETE \
      --url 'https://documentstore.prod.documents.stedi.com/v0/documents/file-id-to-delete'
    

Manually deleting documents by name

  1. Delete a document using the document name.
    curl --request DELETE \
      --url 'https://documentstore.prod.documents.stedi.com/v0/documents/name/file-name-to-delete'
    

Manually listing documents

Listing documents returns lists up to 1MB in payload size. This means that the result set will have an indeterminate number of results when called with no arguments. This allows it to be optimal for the network. If you prefer to get a defined number of results back, you can specify page_size in your request. To get the next set of results, use the last_index returned in the result set as your next_page_token in a subsequent request to get the next page of documents. A paginated set of results with a page_size of 2 will look something like this:

{
  "documents": [
    {
      "createdAt": "2021-04-19T18:28:04.556Z",
      "downloadUrl": "https://example-download-url",
      "hash": "DmiOHBU1o8J3Khm+o5JUPA==",
      "id": "1rOpFIQiQcBwhzOnckE3Jwu3nZj",
      "name": "674a9ea9fa5a79689e340dd4eebd3805d169b9aaf23b47f3",
      "state": "uploaded"
    },
    {
      "createdAt": "2021-04-19T18:29:02.115Z",
      "downloadUrl": "https://example-download-url",
      "hash": "8pdROsvMJWe5C6GlvSMKAw==",
      "id": "1rOpMZwHBWnCPeSMYiu9xsP7RDX",
      "name": "1313f95d255288ed517c8b0735b23d72d636fc682c4ef945",
      "state": "uploaded"
    }
  ],
  "lastIndex": "eyJQSyI6eyJTIjoiT1JHI2IzMWI3M2JkLWM2ZGMtNDExMS1iNTcyLTVlZDBhNTVhZDAyMiJ9LCJTSyI6eyJTIjoiSUQjS1NVSUQgeyAxck9wTVp3SEJXbkNQZVNNWWl1OXhzUDdSRFggfSJ9fQ=="
}
  • List a full page of documents
    curl --request GET \
      --url 'https://documentstore.prod.documents.stedi.com/v0/documents'
    
  • List a full page of 25 documents
    curl --request GET \
      --url 'https://documentstore.prod.documents.stedi.com/v0/documents?page_size=25'
    
  • List a second page of 25 documents
    curl --request GET \
      --url 'https://documentstore.prod.documents.stedi.com/v0/documents?page_size=25&next_page_token=eyJQSyI6eyJTIjoiT1JHI2IzMWI3M2JkLWM2ZGMtNDExMS1iNTcyLTVlZDBhNTVhZDAyMiJ9LCJTSyI6eyJTIjoiSUQjS1NVSUQgeyAxck9wTVp3SEJXbkNQZVNNWWl1OXhzUDdSRFggfSJ9fQ=='
    

API Reference

Using DocumentsManually checking document existence by nameManually creating documentsManually downloading documents by idManually downloading documents by nameManually deleting documents by idManually deleting documents by nameManually listing documents