/
REST Other File Object APIs
Document toolboxDocument toolbox

REST Other File Object APIs

Owned by Andrew Hill (Deactivated)
Last updated: Feb 05, 2024 by Jason Andrew

5.4.6 5.6.0 5.8.0

The File Object REST APIs provide a mechanism to manage the storage of certain "types" of file-based data associated with Work Items.

Specifically: 

  • Work Item Photos - photos taken by the Worker that relate to a Work Item.   
  • Worker Photos - photos of the Worker (e.g. to help customers identify the Worker).
  • Customer Photos - photos taken by the customer that relate to a Work Item.
  • Claims Data - documentation relating to the process of claiming for the cost of performing the work (e.g. a servicing company's claim documentation to go to the insurer of a product).
  • Authorization Requests - documentation relating to requesting authorization to carry out work and/or documentation relating to approval to carry out work.

On this page:

Related pages:

Resource URL Summary

Retrieve metadata for all Files of a given type

GET /up/v5/object/${objectType}/${typeId}/${segment1*}/${segment2*}?metadata=true
* the query parameter metadata is options, when it presents, the response will include the metadata info from here

Upload one or more Files of a given type

POST /up/v5/object/${objectType}/${typeId}/${segment1*}/${segment2*}
--header 'obj-meta-title: titleFromMetadata' \
--header 'obj-meta-cc: j.zhang@sp.com' \
* there header parameters are optional, when they presents, they will be sent to s3 object metadata, and retrieved with GET call with metadata query parameters.

Delete a File

DELETE /up/v5/object/${objectType}/${typeId}/{segment1}/{segment2*}

HTTP Headers

This API uses the standard ServiceBroker HTTP Headers.

API Specific Parameters

ParameterTypeRequired?Description

${objectType}

string

Yes

The type of file-based data being managed. Must be one of the following values:

  • 10: The files being managed are of the Work Item Photos type.
  • 20: The files being managed are of the Worker Photos type.
  • 30: The files being managed are of the Customer Photos type.
  • 40: The files being managed are of the Claims Data type.
  • 50: The files being managed are of the Authorization Requests type.
${typeId}stringYesThe unique string ID value of the Work Item that the File object is associated with.
${segment1}stringNosegment of File Object s3 key
${segment2}stringNosegment of File Object s3 key

API Specifics

Retrieve metadata for all Files of a given type

This REST API will return the metadata for all File objects of a given type that are associated with a given Work Item.

URL

GET /up/v5/object/${objectType}/${typeId}

HTTP Request Body

This request does not require a request body. 

HTTP Response

Success

On success, an HTTP response code of 200 will be returned, and the response body will be a JSON object of the following format:

{
  "Type": "10",
  "FileObjects": [
    {
      "Fieldname": "The name of the field specified in the multipart/form-data request when uploaded",
      "OriginalName": "Original name of the File when uploaded",
      "Encoding": "Encoding type of the File",
      "Mimetype": "Mime type of the File",
      "Size": "Size of the File in bytes",
      "UploadDTM": "Date/Time the File was uploaded",
      "PhotoURL": "URL to the File contents",
      "ThumbnailURL": "URL to a thumbnail version of the File contents",
      "Metadata": { // this will be present when the query parameter metadata=true presents.
                "cc": "j.zhang2@sp.com",
                "title": "titleFromMetadata1"
       }
    }
  ]
}


Error

Otherwise, on error, the API will:

  • Return an HTTP response code of 400, if the request was invalid;
  • Return an HTTP response code of 401, if the request was not authorized; or
  • Return an HTTP response code of 500, if something else went wrong.

Both HTTP 400 and 500 responses will contain a REST Integration Standard Response Object with appropriate values for the Code and/or Message fields, describing the error, in the response body.

Upload one or more Files of a given type

This REST API allows one or more File objects to be uploaded and associated with the given Work Item.

URL

POST /up/v5/object/${objectType}/${typeId}

--header 'obj-meta-title: titleFromMetadata1' \
--header 'obj-meta-cc: j.zhang2@sp.com' 

HTTP Request Body

A standard multipart/form-data body must be included with the request. 

The multipart/form-data body specification can be found in RFC 2388, however, the following links may also be of assistance:

HTTP Request Header

The optional request headers MUST starts with 'object-meta-', which will be store as s3 object metadata.

HTTP Response

Success

On success, an HTTP response code of 200 will be returned.

Error

Otherwise, on error, the API will:

  • Return an HTTP response code of 400, if the request was invalid;
  • Return an HTTP response code of 401, if the request was not authorized; or
  • Return an HTTP response code of 500, if something else went wrong.

Both HTTP 400 and 500 responses will contain a REST Integration Standard Response Object with appropriate values for the Code and/or Message fields, describing the error, in the response body.

Delete a File

This REST API deletes all File objects from the specified Work Item.

There is currently no support for deleting a single File object.

URL

DELETE /up/v5/object/${objectType}/${typeId}

HTTP Request Body

This request does not require a request body. 

HTTP Response

Success

On success, an HTTP response code of 200 will be returned.

Error

Otherwise, on error, the API will:

  • Return an HTTP response code of 400, if the request was invalid;
  • Return an HTTP response code of 401, if the request was not authorized; or
  • Return an HTTP response code of 500, if something else went wrong.

Both HTTP 400 and 500 responses will contain a REST Integration Standard Response Object with appropriate values for the Code and/or Message fields, describing the error, in the response body.