Files

Get a collection

GET /files HTTP/1.1

Query string parameters

All query string parameters are optional.

callback string

Wraps the response in a callback function of the given name. Use this parameter to facilitate JSONP requests.

excluded_ids comma-separated list of IDs

Returns files, except those with the given IDs.

ids comma-separated list of IDs

Return files with the given IDs.

order_by comma-separated list

Sort files by one or more ORDER_BY and ORDER parameter pairs. Options:

• ORDER:
  • asc: order from lowest to highest values
  • desc: order from highest to lowest values
• ORDER_BY:
  • id: order by file ID
  • list: order by the order of IDs given in the ids parameter
  • publish_date: order by publish date
  • score: order by popularity

Format: ORDER_BY|ORDER[,ORDER_BY|ORDER,...]

Default value: id|asc

page integer

Return files from a specific page of a collection.

Default value: 1

per_page integer

Number of files to return per page of a collection. Maximum: 100

Default value: 5

Response

In the example response, embedded files are truncated for illustrative purposes. In the real-world version of the response, "...file object..." is an entire file resource.

{
   "_embedded": {
      "files": [
         "...file object...",
         "...file object...",
         "...file object...",
         "...file object...",
         "...file object..."
      ]
   },
   "_links": {
      "find": {
         "href": "/files/{?id}",
         "templated": true
      },
      "next": {
         "href": "/files?page=3"
      },
      "prev": {
         "href": "/files?page=1"
      },
      "self": {
         "href": "/files?page=2"
      }
   },
   "page": 1,
   "per_page": 5,
   "return_count": 5,
   "total_available": 100
}

Attributes

_embedded hash

Embedded resources.

Toggle child attributes

_embedded.files[] array

An array of file objects.

_links hash

Links to resources associated with the file collection.

Toggle child attributes

_links.find link object

A templated link that can be used to find a specific resource in the collection.

Toggle child attributes

_links.find.href string

URI of the link.

_links.find.templated boolean

Identifies the href as a templated URI.

_links.next link object

A link to the next set of resources in the collection. If there is not a next page, this link will not be present.

Toggle child attributes

_links.next.href string

URI of the link.

_links.prev link object

A link to the previous set of resources in the collection. If there is not a previous page, this link will not be present.

Toggle child attributes

_links.prev.href string

URI of the link.

_links.self link object

A link that identifies the current resource.

Toggle child attributes

_links.self.href string

URI of the link.

page integer

The page number of the returned collection.

per_page integer

The number of files requested per page.

return_count integer

Number of files returned.

total_available integer

Total number of files available in the collection.

Get one

GET /files/:id HTTP/1.1

Endpoint parameters

id integer required

The unique identifier of the file.

Response

{
   "_embedded": {},
   "_links": {
      "self": {
         "href": "/files/40461"
      }
   },
   "alt_text": "A Native American dancer performs outside in front of a crowd",
   "caption": "\u003cp\u003eThe Fifth Annual Indigenous Peoples' Day Powwow brought the JHU community together in celebration and recognition\u003c/p\u003e\n",
   "credit": "Will Kirk / Johns Hopkins University",
   "filemime": "image/jpeg",
   "height": 3592,
   "id": 40461,
   "sizes": {
      "full_width": "https://api.hub.jhu.edu/factory/sites/default/files/styles/full_width/public/2023-10/_JHZ7784.jpg",
      "hard_crop_landscape_1005": "https://api.hub.jhu.edu/factory/sites/default/files/styles/hard_crop_landscape_1005/public/2023-10/_JHZ7784.jpg",
      "hard_crop_landscape_1230": "https://api.hub.jhu.edu/factory/sites/default/files/styles/hard_crop_landscape_1230/public/2023-10/_JHZ7784.jpg",
      "hard_crop_landscape_1380": "https://api.hub.jhu.edu/factory/sites/default/files/styles/hard_crop_landscape_1380/public/2023-10/_JHZ7784.jpg",
      "hard_crop_landscape_240": "https://api.hub.jhu.edu/factory/sites/default/files/styles/hard_crop_landscape_240/public/2023-10/_JHZ7784.jpg",
      "hard_crop_landscape_540": "https://api.hub.jhu.edu/factory/sites/default/files/styles/hard_crop_landscape_540/public/2023-10/_JHZ7784.jpg",
      "hard_crop_landscape_720": "https://api.hub.jhu.edu/factory/sites/default/files/styles/hard_crop_landscape_720/public/2023-10/_JHZ7784.jpg",
      "landscape": "https://api.hub.jhu.edu/factory/sites/default/files/styles/landscape/public/2023-10/_JHZ7784.jpg",
      "large": "https://api.hub.jhu.edu/factory/sites/default/files/styles/hub_large/public/2023-10/_JHZ7784.jpg",
      "medium": "https://api.hub.jhu.edu/factory/sites/default/files/styles/hub_medium/public/2023-10/_JHZ7784.jpg",
      "soft_crop_1030": "https://api.hub.jhu.edu/factory/sites/default/files/styles/soft_crop_1030/public/2023-10/_JHZ7784.jpg",
      "soft_crop_1300": "https://api.hub.jhu.edu/factory/sites/default/files/styles/soft_crop_1300/public/2023-10/_JHZ7784.jpg",
      "soft_crop_1600": "https://api.hub.jhu.edu/factory/sites/default/files/styles/soft_crop_1600/public/2023-10/_JHZ7784.jpg",
      "soft_crop_1800": "https://api.hub.jhu.edu/factory/sites/default/files/styles/soft_crop_1800/public/2023-10/_JHZ7784.jpg",
      "soft_crop_2000": "https://api.hub.jhu.edu/factory/sites/default/files/styles/soft_crop_2000/public/2023-10/_JHZ7784.jpg",
      "soft_crop_2400": "https://api.hub.jhu.edu/factory/sites/default/files/styles/soft_crop_2400/public/2023-10/_JHZ7784.jpg",
      "soft_crop_2880": "https://api.hub.jhu.edu/factory/sites/default/files/styles/soft_crop_2880/public/2023-10/_JHZ7784.jpg",
      "soft_crop_630": "https://api.hub.jhu.edu/factory/sites/default/files/styles/soft_crop_630/public/2023-10/_JHZ7784.jpg",
      "thumbnail": "https://api.hub.jhu.edu/factory/sites/default/files/styles/hub_thumbnail/public/2023-10/_JHZ7784.jpg",
      "xlarge": "https://api.hub.jhu.edu/factory/sites/default/files/styles/hub_xlarge/public/2023-10/_JHZ7784.jpg"
   },
   "srcsets": {
      "cropped-landscape": "https://api.hub.jhu.edu/factory/sites/default/files/styles/hard_crop_landscape_240/public/2023-10/_JHZ7784.jpg 240w, https://api.hub.jhu.edu/factory/sites/default/files/styles/hub_thumbnail/public/2023-10/_JHZ7784.jpg 360w, https://api.hub.jhu.edu/factory/sites/default/files/styles/hard_crop_landscape_540/public/2023-10/_JHZ7784.jpg 540w, https://api.hub.jhu.edu/factory/sites/default/files/styles/hard_crop_landscape_720/public/2023-10/_JHZ7784.jpg 720w, https://api.hub.jhu.edu/factory/sites/default/files/styles/landscape/public/2023-10/_JHZ7784.jpg 900w, https://api.hub.jhu.edu/factory/sites/default/files/styles/hard_crop_landscape_1005/public/2023-10/_JHZ7784.jpg 1005w, https://api.hub.jhu.edu/factory/sites/default/files/styles/hard_crop_landscape_1230/public/2023-10/_JHZ7784.jpg 1230w, https://api.hub.jhu.edu/factory/sites/default/files/styles/hard_crop_landscape_1380/public/2023-10/_JHZ7784.jpg 1380w",
      "scaled": "https://api.hub.jhu.edu/factory/sites/default/files/styles/hub_medium/public/2023-10/_JHZ7784.jpg 420w, https://api.hub.jhu.edu/factory/sites/default/files/styles/soft_crop_630/public/2023-10/_JHZ7784.jpg 630w, https://api.hub.jhu.edu/factory/sites/default/files/styles/full_width/public/2023-10/_JHZ7784.jpg 825w, https://api.hub.jhu.edu/factory/sites/default/files/styles/soft_crop_1030/public/2023-10/_JHZ7784.jpg 1030w, https://api.hub.jhu.edu/factory/sites/default/files/styles/hub_large/public/2023-10/_JHZ7784.jpg 1194w, https://api.hub.jhu.edu/factory/sites/default/files/styles/soft_crop_1300/public/2023-10/_JHZ7784.jpg 1300w, https://api.hub.jhu.edu/factory/sites/default/files/styles/hub_xlarge/public/2023-10/_JHZ7784.jpg 1440w, https://api.hub.jhu.edu/factory/sites/default/files/styles/soft_crop_1600/public/2023-10/_JHZ7784.jpg 1600w, https://api.hub.jhu.edu/factory/sites/default/files/styles/soft_crop_1800/public/2023-10/_JHZ7784.jpg 1800w, https://api.hub.jhu.edu/factory/sites/default/files/styles/soft_crop_2000/public/2023-10/_JHZ7784.jpg 2000w, https://api.hub.jhu.edu/factory/sites/default/files/styles/soft_crop_2400/public/2023-10/_JHZ7784.jpg 2400w, https://api.hub.jhu.edu/factory/sites/default/files/styles/soft_crop_2880/public/2023-10/_JHZ7784.jpg 2880w"
   },
   "type": "image",
   "width": 5392
}

Attributes

_embedded hash

Embedded resources.

_links hash

Links to resources associated with the file.

Toggle child attributes

_links.self link object

A link that identifies the current resource.

Toggle child attributes

_links.self.href string

URI of the link.

alt_text string

Describes the appearance or function of the image. Should be used to populate the alt attribute of the <img> tag. Only present on image files.

caption string

Description of the file.

credit string

The creator or source of the file.

filemime string

Media type of the file.

height integer

Height of the file, in pixels. Only present on image files.

id integer

Unique identifier of the file.

sizes hash

Available crop sizes. Only present on image files. For other types of files, see the url attribute.

Related: srcsets attribute

Toggle crop sizes

Name	Aspect ratio	Size (px)
hard_crop_landscape_240	1.5:1	240x160
thumbnail	1.5:1	360x240
hard_crop_landscape_540	1.5:1	540x360
hard_crop_landscape_720	1.5:1	720x480
landscape	1.5:1	900x600
hard_crop_landscape_1005	1.5:1	1005x670
hard_crop_landscape_1230	1.5:1	1230x820
hard_crop_landscape_1380	1.5:1	1380x920
medium	same as source image	420 wide
soft_crop_630	same as source image	630 wide
full_width	same as source image	825 wide
soft_crop_1030	same as source image	1030 wide
large	same as source image	1194 wide
soft_crop_1300	same as source image	1300 wide
xlarge	same as source image	1440 wide
soft_crop_1600	same as source image	1600 wide
soft_crop_1800	same as source image	1800 wide
soft_crop_2000	same as source image	2000 wide
soft_crop_2400	same as source image	2400 wide
soft_crop_2880	same as source image	2880 wide

srcsets hash

Compiled lists of image URLs and corresponding widths, designed to be used directly in the srcset attribute of the <img> tag to help make the image responsive. Please note that you must provide the sizes attribute in order for the image to be responsive.

Toggle child attributes

srcsets.cropped-landscape string

Source set for hard-cropped versions of the image.

srcsets.scaled string

Source set for soft-cropped versions of the image.

type hash

Type of file. Possible values:

• document: A PDF, spreadsheet, or other type of data file.
• image: generally a jpg, gif, or png file.

url string

URL of the file. Only present if the file is not an image. For images, see the sizes attribute.

width integer

Width of the file, in pixels. Only present on image files.