Navigation

API Documentation

Files

Files are split up into meta data and file data (byte data).

Meta data consist of

  • title
  • description
  • filename
  • creator
  • created
  • modifier
  • modified
  • status
  • credits

The term file data refers to the actual file and its mimetype and size in bytes.

Use the PUT method of the /{iid}/files/{uuid} resource to add/update meta data and the POST method of the same resource to add/update file data.

Note

File Download URL

A file's download url may change at any time, so to make sure you have the correct url, retrieve the file meta data using the PUT /{iid}/files/{uuid} resource and get the current download url from the returned data.

/{iid}/files

GET

Additional Information

Roles:

Retrieve a batched collection of files.

This resource returns a batched list of files. The file information returned depends on the fields parameter.

Using the groups parameter, you can restrict items to specific groups of MIME types, i.e. all images or application types. You can also retrieve files with a specific MIME type using the mimetypes parameter.

Sample Call

Get images:

>>> GET("/123/files?groups=image&fields=title-url-mimetype-filename&order=title&rpp=2")
{'items': [['Abstract Art',
            'https://api.metropublisher.com/123/files/4f305f88-27de-39f1-9e08-790cc30b1454',
            'image/jpeg',
            'abstract_art.jpg'],
           ['City Lights Book Store',
            'https://api.metropublisher.com/123/files/186fa89b-1ecf-3e94-a144-0603362ed675',
            'image/jpeg',
            'city_lights_book_store.jpg']],
 'next': 'fields=title-url-mimetype-filename&groups=image&order=title&page=2&rpp=2'}

Parameters

page:

The page number to retrieve.

optional

Default: 1

Values must not be lower than 1
rpp:

The number of results per page.

optional

Default: 20

Values must not be lower than 1 or higher than 100
groups:

A dash-separated list of MIME type groups to retrieve (if not specified, return files of all groups).

optional

Default: None

Example value: 'image-text'

Every element of the list must be any of the following

application:

Application
audio:

Audio
image:

Images
text:

Text
unknown:

Unknown
video:

Video
mimetypes:

An underbar-separated list of MIME types to retrieve (if not specified, return files of all MIME types).

optional

Default: None

Example value: 'image/jpeg_image/png'

Every element of the list must match the following regular expression:

^[-\w]+/[-\w\+\.]+$

Info: The regular expression checks the following pattern:

<words (with dashes)>/<words (with dashes, plus-signs or dots)>
fields:

A dash-separated list of fields to return.

optional

Default: ['url']

Example value: 'filename-uuid'

Every element of the list must be any of the following

filename:The filename
mimetype:The file's mimetype.
title:The title
url:URL to the file
uuid:The UUID of the file
order:

A dash-separated list of orderings to apply

optional

Default: []

Example value: 'created-title.desc'

Every element of the list must be any of the following

created:Sort by created ascending
created.asc:Sort by created ascending
created.desc:Sort by created descending
filename:Sort by filename ascending
filename.asc:Sort by filename ascending
filename.desc:Sort by filename descending
title:Sort by title ascending
title.asc:Sort by title ascending
title.desc:Sort by title descending
uuid:Sort by UUID ascending
uuid.asc:Sort by UUID ascending
uuid.desc:Sort by UUID descending

/{iid}/files/{uuid}

DELETE

Additional Information

Roles:

Deletes a file.

Sample Call

>>> DELETE("/123/files/12345678-1234-1234-1234-123456789abc")
{'msg': 'deleted'}

GET

Additional Information

Roles:
  • public_user

    Access is restricted to certain attributes of the file object.

  • super

Retrieve one file.

This resource returns information about one specific file. What information is returned depends on the role of the API key. Some attributes are not publicly available.

Sample Call

>>> GET("/123/files/4f305f88-27de-39f1-9e08-790cc30b1454")
{'byte_size': 244014,
 'created': '2010-12-05T14:27:47.739437',
 'credits': 'iStock Photo ',
 'description': 'This is the master caption.',
 'download_url': 'https://api.metropublisher.com/123/files/4f305f88-27de-39f1-9e08-790cc30b1454/download/1291555667',
 'filename': 'abstract_art.jpg',
 'mimetype': 'image/jpeg',
 'modified': '2010-12-05T14:27:47.739437',
 'title': 'Abstract Art',
 'uuid': '4f305f88-27de-39f1-9e08-790cc30b1454'}

Return Value

byte_size:

The file's size in bytes.
created:

The file's creation date/time.

Access is restricted to users with these roles:
credits:

The file's credits, e.g. the person who shot an image.
description:

The file's description, e.g. the caption of an image.
download_url:

The url to the file itself. See also Retrieving a File.
filename:

The filename.
mimetype:

The file's mimetype, e.g. 'image/jpg'.
modified:

The file's modification date/time.

Access is restricted to users with these roles:
title:

The file's human readable title.
uuid:

The file's uuid.

POST

Additional Information

Roles:

Add/update file data.

Posting to this resource adds/updates the actual file data (binary data) as well as the file's MIME type and byte size.

The headers of the request sent to this resource must contain 'Content-Type' defining the file's MIME type. The request body must not be empty.

Sample Call

>>> POST("/123/files/12345678-1234-1234-1234-123456789abc",
...      REQUEST_BODY_CONTAINING_FILEDATA,
...      content_type='image/jpeg')
{'download_url': 'https://api.metropublisher.com/123/files/12345678-1234-1234-1234-123456789abc/download/946717200',
 'url': 'https://api.metropublisher.com/123/files/12345678-1234-1234-1234-123456789abc',
 'uuid': '12345678-1234-1234-1234-123456789abc'}

PUT

Additional Information

Roles:

Create/update a file's metadata.

Sending data to this resource does one of two things:

  • creates a new file object and sets its meta data if no file object with the given UUID was found, or
  • updates the file object's meta data if a file object with the given UUID exists.

Sample Call

>>> PUT("/123/files/12345678-1234-1234-1234-123456789abc", {"title": "New File Title",
...                                                         "filename": "new_filename.jpg",
...                                                         "description": "New file description",
...                                                         "created": "2000-01-01T10:30:58",
...                                                         "modified": "2000-01-01T10:30:58"})
{'url': 'https://api.metropublisher.com/123/files/12345678-1234-1234-1234-123456789abc',
 'uuid': '12345678-1234-1234-1234-123456789abc'}

Parameters

title:

The file title

required

Example value: "Restaurant Interior"

Values must not be longer than 255
description:

A short description of the file.

optional

Default: ''

Example value: "Interior view of the restaurant"
filename:

The filename.

required

Example value: "restaurant_interior.jpg"

Values must not be longer than 255
created:

The creation date/time in ISO 8601 format. See Dates and Times.

optional

Default: <current timestamp>

Example value: '2012-01-01T11:30:45'

Values must restricted to users with these roles:
modified:

The date/time of last modification in ISO 8601 format. See Dates and Times.

optional

Default: <current timestamp>

Example value: '2012-01-01T11:30:45'

Values must restricted to users with these roles:
credits:

The credits, e.g. copyright information for the file.

optional

Default: None

Example value: "(c) 2010 P. Petersen"

/{iid}/files/{uuid}/tags

GET

Additional Information

Roles:
  • public_user

    Access is restricted to certain attributes of the file object.

  • super

Get all tags for a file.

Sample Call

>>> GET("/123/files/12345678-1234-1234-1234-123456789abc/tags")
{'items': [{'predicate': 'describes',
            'title': 'Sample Tag',
            'url': 'https://api.metropublisher.com/123/tags/60183d70-a998-11e1-afa6-0800200c9a66',
            'uuid': '60183d70-a998-11e1-afa6-0800200c9a66'}]}

Parameters

state:

optional

Default: 'approved' if the user is a public user else None.

Values must be any of the following

internal:

Only internal tags

Access is restricted to users with these roles:
approved:

Only approved tags
provisional:

Only provisional tags

Access is restricted to users with these roles:

/{iid}/files/{uuid}/tags/{predicate}

GET

Additional Information

Roles:
  • public_user

    Access is restricted to certain attributes of the file object.

  • super

Get the tags for a file that represent a specific tag/file relationship, defined by 'predicate'.

See also tag predicates.

Sample Call

>>> GET("/123/files/12345678-1234-1234-1234-123456789abc/tags/describes")
{'items': [{'predicate': 'describes',
            'title': 'Sample Tag',
            'url': 'https://api.metropublisher.com/123/tags/60183d70-a998-11e1-afa6-0800200c9a66',
            'uuid': '60183d70-a998-11e1-afa6-0800200c9a66'}]}

Parameters

state:

optional

Default: 'approved' if the user is a public user else None.

Values must be any of the following

internal:

Only internal tags

Access is restricted to users with these roles:
approved:

Only approved tags
provisional:

Only provisional tags

Access is restricted to users with these roles:

Table Of Contents

Previous topic

Events

Next topic

Homepages

Navigation

© Copyright 2021, Vanguardistas LLC. Created using Sphinx 1.1.3.