TNS Bynder API Documentation

Documentation for the TNS Bynder Middleware API for submitting media to Bynder and retrieving media information for display on sites. The repo is hosted in the Online Strategy account at Bitbucket.

Configuration Options

Configuration settings are in /config.php.

bynderAuth
The path to file that contains authorization credentials for the Bynder account.
uploadDirectory
The path to the parent directory under which all files uploaded from forms will be temporarily stored until uploading to Bynder is complete.
uploadRetryCount
The number of times to attempt to upload each file to Bynder before throwing an error message.
submissionsDirectory
The path to the directory where in-progress form submissions are stored. They will be removed after successful upload to Bynder.
dataDirectory
The path to the directory where the complete set of Bynder metadata is stored. There is a method below that can be used to update the metadata and store it here, but it is not yet working due to issues with the Bynder API.
cacheDirectory
The path to the directory where cached responses are stored. The paths that are cached are: /media/{id}, /media?param1=value1&param2=value2, and /media/{version}/{id}.
cacheExpiresInSeconds
Time in seconds that the Media Info requests are cached.
allowedMediaTypesAndAssetTypeMap
A map of MIME types to the Bynder Asset Type metaproperty value. Not currently in use because the TNS server does not have the fileinfo PHP extension installed.
fileExtensionToAssetTypeMap
A map of file extensions to the Bynder Asset Type metaproperty value.
bynderMediaSearchAllowedParams
The list of URL parameters that are allowed when using the Get Media Info Objects by parameters methof described below. This list matches the complete list of parameters documented in Bynder's API docs. See the parameters documented in the right column.
adminEmails
Array of email addresses which are sent emails when errors occur.
emailFrom
The path to the parent directory under which all files uploaded from forms will be temporarily stored until uploading to Bynder is complete.
emailSubjectSuccess
The Subject line for the email sent to admins when there is an error in the upload process.
emailBodySuccess
The path to the php template used for the email sent to the user after successful upload of their files to Bynder. The path begins from inside the /template directory.
emailSubjectErrors
The Subject line for the email sent to admins when there is an error in the upload process.
emailBodyErrors
The path to the php template used for the email sent to admins when there is an error in the upload process. The path begins from inside the /template directory.

API Methods

Hello World Test Method

Method to test that the server is responding

Type: Get

Syntax: /hello/{name}

Example: /hello/Marlon

Return: string

"Hello, Marlon"

Get the URL of an Image by ID

Bynder generates several versions of each image. Specify which version you want by name. You can see the names of all available versions in the "thumbnails" field of the JSON results in the Get Media Info Objects methods below.

Type: Get

Syntax: /media/{version}/{id}

Example: Get the "Web_Version" URL > /media/url/Web_Version/3A9D028E-7533-4E5C-97B028CFB18CD104

Return: URL string

"https://d3cy9zhslanhfa.cloudfront.net/media/F3E6ADE2-8E6B-4562-A1E8850B41A37768/3A9D028E-7533-4E5C-97B028CFB18CD104/E3FE5407-2F43-4A22-AB1783EBA4450848/Web_Version-20170519_PVN_Commencement_152.jpg"

Get a Single Media Info Object by ID

Type: Get

Syntax: /media/{id}

Example: /media/3A9D028E-7533-4E5C-97B028CFB18CD104

Return: a media info JSON object

{
    "dateModified": "2017-05-26T21:31:55Z",
    "propertyOptions": [
        "26D2DFEB-646E-47E3-83DFC8324E13C717",
        "67A8DAAE-0D17-49B9-89B4B5F7842B5AD0",
        "AF46FFB7-5C47-4B2C-A3C2F0FB21F5F37B",
        "E881113E-354B-40E8-9A2AD26265C48DD6"
    ],
    "type": "image",
    "brandId": "95E9C4D6-A53F-4576-9579EFF875D6026E",
    "fileSize": 6691688,
    "id": "3A9D028E-7533-4E5C-97B028CFB18CD104",
    "height": 3467,
    "description": "The New School Celebrates its 2017 Commencement Exercises on May 19th at Arthur Ashe Stadium in Queens.",
    "idHash": "6911e34c14fd3bfc",
    "name": "20170519_PVN_Commencement_152",
    "orientation": "landscape",
    "width": 5200,
    "datePublished": "2017-05-19T11:22:12Z",
    "isPublic": 0,
    "copyright": "The New School",
    "extension": [
        "jpg"
    ],
    "userCreated": "Matthew Mathews",
    "dateCreated": "2017-05-26T21:31:55Z",
    "archive": 0,
    "property_assettype": [
        "photography"
    ],
    "property_photographer": [
        "Phillip_Van_Nostrand"
    ],
    "property_schoolcollege": [
        "thenewschool"
    ],
    "watermarked": 0,
    "limited": 0,
    "thumbnails": {
        "mini": "https://d3cy9zhslanhfa.cloudfront.net/media/F3E6ADE2-8E6B-4562-A1E8850B41A37768/3A9D028E-7533-4E5C-97B028CFB18CD104/mini-779935BD-ABF9-4314-B6566150536A565F.jpg",
        "webimage": "https://d3cy9zhslanhfa.cloudfront.net/media/F3E6ADE2-8E6B-4562-A1E8850B41A37768/3A9D028E-7533-4E5C-97B028CFB18CD104/webimage-96C6BD0E-FC5A-4493-950C9F18C4CB16F5.jpg",
        "thul": "https://d3cy9zhslanhfa.cloudfront.net/media/F3E6ADE2-8E6B-4562-A1E8850B41A37768/3A9D028E-7533-4E5C-97B028CFB18CD104/thul-599E802B-C62B-4666-A73111897FC00D6B.jpg",
        "Web_Version": "https://d3cy9zhslanhfa.cloudfront.net/media/F3E6ADE2-8E6B-4562-A1E8850B41A37768/3A9D028E-7533-4E5C-97B028CFB18CD104/E3FE5407-2F43-4A22-AB1783EBA4450848/Web_Version-20170519_PVN_Commencement_152.jpg"
    },
    "views": 6,
    "downloads": 0,
    "activeOriginalFocusPoint": {
        "y": 1733.5,
        "x": 2600
    }
}

Search For a Set of Media Info Objects by Parameter(s)

See Bynder API docs for the complete list of attributes that can be searched. The parameters are documented in the right column.

Type: Get

Syntax: /media/?attribute1=value&attribute2=value

Example: /media?collectionId=7091C321-823D-46C9-85371EFC63D10AE3

Return: an array of media info JSON objects. The result below shows a set with one media object.

[
    {
        "dateModified": "2017-05-26T21:31:55Z",
        "propertyOptions": [
            "26D2DFEB-646E-47E3-83DFC8324E13C717",
            "67A8DAAE-0D17-49B9-89B4B5F7842B5AD0",
            "AF46FFB7-5C47-4B2C-A3C2F0FB21F5F37B",
            "E881113E-354B-40E8-9A2AD26265C48DD6"
        ],
        "type": "image",
        "brandId": "95E9C4D6-A53F-4576-9579EFF875D6026E",
        "fileSize": 6691688,
        "id": "3A9D028E-7533-4E5C-97B028CFB18CD104",
        "height": 3467,
        "description": "The New School Celebrates its 2017 Commencement Exercises on May 19th at Arthur Ashe Stadium in Queens.",
        "idHash": "6911e34c14fd3bfc",
        "name": "20170519_PVN_Commencement_152",
        "orientation": "landscape",
        "width": 5200,
        "datePublished": "2017-05-19T11:22:12Z",
        "isPublic": 0,
        "copyright": "The New School",
        "extension": [
            "jpg"
        ],
        "userCreated": "Matthew Mathews",
        "dateCreated": "2017-05-26T21:31:55Z",
        "archive": 0,
        "property_assettype": [
            "photography"
        ],
        "property_photographer": [
            "Phillip_Van_Nostrand"
        ],
        "property_schoolcollege": [
            "thenewschool"
        ],
        "watermarked": 0,
        "limited": 0,
        "thumbnails": {
            "mini": "https://d3cy9zhslanhfa.cloudfront.net/media/F3E6ADE2-8E6B-4562-A1E8850B41A37768/3A9D028E-7533-4E5C-97B028CFB18CD104/mini-779935BD-ABF9-4314-B6566150536A565F.jpg",
            "webimage": "https://d3cy9zhslanhfa.cloudfront.net/media/F3E6ADE2-8E6B-4562-A1E8850B41A37768/3A9D028E-7533-4E5C-97B028CFB18CD104/webimage-96C6BD0E-FC5A-4493-950C9F18C4CB16F5.jpg",
            "thul": "https://d3cy9zhslanhfa.cloudfront.net/media/F3E6ADE2-8E6B-4562-A1E8850B41A37768/3A9D028E-7533-4E5C-97B028CFB18CD104/thul-599E802B-C62B-4666-A73111897FC00D6B.jpg",
            "Web_Version": "https://d3cy9zhslanhfa.cloudfront.net/media/F3E6ADE2-8E6B-4562-A1E8850B41A37768/3A9D028E-7533-4E5C-97B028CFB18CD104/E3FE5407-2F43-4A22-AB1783EBA4450848/Web_Version-20170519_PVN_Commencement_152.jpg"
        },
        "views": 6,
        "downloads": 0,
        "activeOriginalFocusPoint": {
            "y": 1733.5,
            "x": 2600
        }
    }
]

File Upload (to local storage)

Upload one or more files and store them on the local TNS server for later submission to Bynder

Type: Post

Syntax: /file/upload

Set form-data params of request as follows:

awesomeThings[submittername] = First Last
targetPath = (folder name the files will be saved under)
type = other
file[0] = (file to upload)

Example: /file/upload

Return: an JSON array of filepaths for the images

[
    "testsubmit/John-Berger.jpg",
    "testsubmit/e-kelly-1.jpg"
]

File Delete (from local storage)

Delete a file from the local TNS server

Type: Post

Syntax: /file/delete

Set form-data params of request as follows:

awesomeThings[filename] = subfoldername/filename.ext

Example: /file/delete

Return: 200 OK

Form Submission

Submit form data after uploading files with all file information and the necessary fields for populating Bynder metadata fields.

Type: Post

Syntax: /submit

Set the body of the request as a JSON object as follows:

{
  "awesomeThings": {
  	"sendEmail": true,
    "submittername": "Greg Simsic",
    "details": {
      "description": "Description",
      "ISOPublicationDate": "2017-06-07T04:00:00.000Z",
      "copyright": "Greg Simsic"
    },
    "files": [
      "1496940319381GregSimsic/John-Berger.jpg"
    ],
    "copyrightfiles": "",
    "metaData": {
      "assettype": [
        "Photography"
      ],
      "assetsubtype": "Faculty Work",
      "usagerights": [
        "Promotional non-paid",
        "Paid Media incl. paid social"
      ],
      "photographer": "Greg Simsic",
      "schoolcollege": "The New School for Social Research NSSR",
      "degreeprogramname": "Creative Publishing and Critical Journalism MA",
      "worktitle": "Title",
      "email": "simsicg@newschool.edu",
      "phone": "6462587514",
      "submittername": "Greg Simsic",
      "submitteremail": "greg@gregsimsic.com,simsicg@newschool.edu",
      "submitterphone": "6462587514"
    }
  },
  "targetPath": "1496940319381GregSimsic"
}

Example: This can only be tested via a form (or application like Postman). The upload form is here.

Return: (The upload process is very slow. Eventually, this will return a 200 OK message if all of the files were uploaded successfully to Bynder or an array of errors if not.

An example error array:

[
    {
        "file": "1496940319381GregSimsic/John-Berger.jpg",
        "message": "File not found on server"
    }
]

Get Saved Submission Data for a Submitted Form

Submissions data is saved on the TNS server until the upload process is complete. The id is the value of 'targetPath' from the original submission.

Type: Get

Syntax: /submission/{id}

Example: /submission/testsubmit

Return: JSON object

{
    "id": "testsubmit",
    "directory": "logs/submissions/",
    "status": "errors uploading to Bynder",
    "dateCreated": "2017-07-12 14:40:55",
    "dateUpdated": "2017-07-12 14:40:55",
    "submitterName": "Greg Simsic",
    "files": [
        "testsubmit/John-Berger.jpg"
    ],
    "copyrightFiles": "",
    "errors": [
        {
            "file": "testsubmit/John-Berger.jpg",
            "message": "File not found on server"
        }
    ],
    "metadata": {
        "brandid": "95E9C4D6-A53F-4576-9579EFF875D6026E",
        "description": "Description",
        "ISOPublicationDate": "2017-06-07T04:00:00.000Z",
        "copyright": "Greg Simsic",
        "metaproperty.67982A0C-9D21-4B63-B75C6792DD12573A": "Photography",
        "metaproperty.FCE01666-AE1F-48AA-AAEA0792B6993058": "Faculty Work",
        "metaproperty.6483BBB8-0B7D-42BF-8EB1C6F6A30B611D": "Promotional non-paid,Paid Media incl. paid social",
        "metaproperty.BEDF1506-80B3-4D5C-8ABAA83E8D8C3B94": "Greg Simsic",
        "metaproperty.CB205B76-B0B1-4FF7-A0322EDA1DE78E04": "The New School for Social Research NSSR",
        "metaproperty.6131D2CC-64A3-45E9-AEF227800220CD0C": "Creative Publishing and Critical Journalism MA",
        "metaproperty.FFE29AC1-AB87-4F58-B0787AC8892C0F01": "Title",
        "metaproperty.D7ECEDB6-57C1-4D18-AB89AC1B78C3BAB7": "simsicg@newschool.edu",
        "metaproperty.1C6C1F5D-6F98-45D0-B6D4442F597027EC": "6462587514",
        "metaproperty.BB643940-E4AC-4045-9C5B500B2F638FA3": "Greg Simsic",
        "metaproperty.2C825C1E-B2E6-4214-82962ABEC083E70C": "greg@gregsimsic.com,simsicg@newschool.edu",
        "metaproperty.C51708B7-038B-4791-A2F3CF3BF53C8AFD": "6462587514",
        "audit": true
    }
}

Resubmit a Form Submission that had Failed File Uploads

If a form submission contains errors, this method can be used to attempt to re-upload the files that failed the initial submission. The id is the value of 'targetPath' from the original submission.

Type: Get

Syntax: /media/{id}

Example: /resubmit/1496940319381GregSimsic

Return: JSON object

The returned JSON object is the same as shown in the Form Submission 'submit' method above.

Delete a Form Submission

Deletes only the files associated with a form submission. The submission data is retained and the status is set to "submission deleted." The id is the value of 'targetPath' from the original submission.

Type: Get

Syntax: /submission/delete/{id}

Example: /submission/delete/1496940319381GregSimsic

Return: 200 OK

Flush the Cache

Responses to the /media methods are cached. This method flushes the cache for those reponses. The cache defaults to one hour but can be changed in /config.php.

Type: Get

Syntax: /cache/flush

Example: /cache/flush

Return: 200 OK

API Methods In Progress:

In Progess > Do not use:
Refresh Bynder Metadata

The Bynder metadata fields are stored on the server in static files saved in the /data folder. This method will retrieve new metadata from Bynder, but is not yet working due to issues with the Bynder API.

Type: Get

Syntax: /metadata/refresh

Example: /metadata/refresh

Return: 200 OK