File Properties

Each file has the following properties and is accessed via /api/file. Complete details in FileProperties.

id: The unique id for this file. It will never change.
wing_object_type: file.
date_created: A date when the file was created.
date_updated: A date when the file was last updated.
name: The name the file is known by.
sha1_digest: A unique hash of the file. This is useful when you want to cache files locally, or avoid uploading a file you've already uploaded, because it is always unique to a file.
folder_id: A Folder id. The unique id of a Folder that this file is contained in.
file_size: The file's size in bytes.
file_type: A string representing what kind of file this is.
details: A string describing the file. If it's a PDF it will be how many pages it contains. If it's an image it will give some resolution information.
status: Either Ready or Processing. This indicates wehther the file has been processed for inclusion into The Game Crafter's file handling system. Things like generating a preview image and creating a permanent storage location are done while processing.
preview_uri: A URI to an image that shows a small representation of the original image or the first page of a PDF document.
file_uri: A URI to the permanent storage location of the file.

Related Objects

folder: The Folder that this file is contained in.
metadata: A hash providing all the extra goodies we know about the file.

File Methods

The methods used to fetch and manipulate files.

Create File

 POST /api/file

session_id: Required. The unique session id provided by a Session method.
name: Optional. If not passed in, the filename will be used as the name.
file: Required. The file that you wish to upload.
folder_id: Required. A Folder id.
watermark: Optional. Add a watermark to the thumbnail that's will be generated for an uploaded image file.

Returns:

 {
   "id" : "xxx",
   "name" : "A Card",
   ...
 }

Update File

 PUT /api/file/xxx

See Create File for details.

Delete File

 DELETE /api/file/xxx

session_id: Required. The unique session id provided by a Session method.

Returns:

 {
   "success" : 1
 }

Fetch File

 GET /api/file/xxx

session_id: Optional. The unique session id provided by a Session method.
_include_related_objects: Optional. See "Relationships" in Intro and File Relationships above for details.
_include_relationships: Optional. See "Relationships" in Intro and File Relationships above for details.

Returns:

 {
   "id" : "xxx",
   "name" : "My Game",
   ...
 }

File References

 GET /api/file/xxx/references

Return a list of all objects that use this File. Each object will have a full description of itself.

session_id

Required. The unique session id provided by a Session method.

Returns:

 {
   items : [ 
    {
       "id" : "xxx",
       "name" : "My Avatar",
       ...
    },
    {
       "id" : "xxx",
       "name" : "My Deck Card Back",
       ...
    },
    ...
   ]
 }

Grid Image Upload

 POST /api/file/grid-image

You can create a bunch of File objects all at once by uploading a grid image to this API. The image will be split into smaller images, and you'll get an array of File objects back.

The images will be extracted across and then down. So if your grid has 9 images in 3 rows of 3 then it would be like:

 1 2 3
 4 5 6
 7 8 9

If you only have 7 images, but the same grid layout then you would set quantity=7 the images extracted would be:

 1 2 3
 4 5 6
 7

For that case the last to spaces in the grid will be ignored.

session_id: Required. The unique session id provided by a Session method.
name: Optional. If not passed in, the filename will be used as the name.
file: Required. The image that you wish to upload. The image cannot exceed 5000x5000 pixels.
folder_id: Required. A Folder id.
quantity: The number of images that should be extracted from this image. Range between 1 and 100.
width: The width (in pixels) of the images to be extracted from this image.
height: The height (in pixels) of the images to be extracted from this image.

Returns:

  {
    "files" : [ 
      {
        "file_uri" : "//s3.amazonaws.com/files.dev.thegamecrafter.com/78353d61fcfba20d113cbcb91adc1153780f91b8",
        "file_type" : "PNG",
        "sha1_digest" : "78353d61fcfba20d113cbcb91adc1153780f91b8",
        "date_updated" : "2021-01-30 23:28:36",
        "date_created" : "2021-01-30 23:28:36",
        "id" : "E024AC38-6352-11EB-92B1-B403F0027F2A",
        "status" : "Processing",
        "can_edit" : 1,
        "object_name" : "File",
        "file_size" : 8294.4,
        "image_size" : "825x1125",
        "s3file_id" : "D0F0FF3E-6350-11EB-A921-E51985A17141",
        "preview_uri" : "/preview_not_ready.gif",
        "can_view" : 1,
        "object_type" : "file",
        "folder_id" : "0AFF1012-373B-11E2-B3AB-C942AB40E458",
        "_warnings" : [],
        "details" : "825x1125 pixels",
        "name" : "1_gridimage.png"
      },  
      ...
    ]
  }

Developer Documentation

Intro
Changes