Articles

Get a collection

GET /articles 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.

channels comma-separated list of IDs

Return articles assigned to the given channels.

divisions comma-separated list of IDs

Return articles assigned to the given divisions.

excluded_ids comma-separated list of IDs

Returns articles, except those with the given IDs.

ids comma-separated list of IDs

Return articles with the given IDs.

include_subterms comma-separated list of IDs

Works in conjunction with hierarchical taxonomy parameters to ensure returned articles are assigned to either the specified term(s) or the children of the specified term(s). Hierarchical taxonomy parameter(s) available on articles: topics

For example, /articles?topics=3158&include_subterms=3158 will return articles assigned to term #3158 (At Work) and any other topic whose parent is At Work.

order_by comma-separated list

Sort articles 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 article 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: publish_date|desc,id|asc

page integer

Return articles from a specific page of a collection.

Default value: 1

per_page integer

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

Default value: 5

source comma-separated list

Return articles published by the specified source(s). Options:

• atwork: articles published in the At Work section of the Hub
• hub: articles not published in At Work or Johns Hopkins Magazine
• magazine: articles published in Johns Hopkins Magazine

Default value: hub,magazine

tags comma-separated list of IDs

Return articles assigned to the given tags.

topics comma-separated list of IDs

Return articles assigned to the given topics.

Response

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

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

Attributes

_embedded hash

Embedded resources.

Toggle child attributes

_embedded.articles[] array

An array of article objects.

_links hash

Links to resources associated with the article 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 articles requested per page.

return_count integer

Number of articles returned.

total_available integer

Total number of articles available in the collection.

Get one

GET /articles/:id HTTP/1.1

Endpoint parameters

id integer required

The unique identifier of the article.

Response

{
   "_embedded": {
      "divisions": null,
      "image_thumbnail": null,
      "tags": null,
      "topics": null
   },
   "_links": {
      "galleries": [
         {
            "href": "/galleries/8884"
         }
      ],
      "related_content": [
         {
            "_embedded": [],
            "href": "/articles/8887"
         },
         {
            "_embedded": [],
            "href": "/articles/8880"
         },
         {
            "_embedded": [],
            "href": "/articles/8810"
         }
      ],
      "self": {
         "href": "/articles/8893"
      }
   },
   "alt_headline": "Flyby launches 'new era of solar system exploration'",
   "author": "Hub staff report",
   "excerpt": "New Horizons phones home following historic Pluto flyby, continues deeper into Kuiper belt",
   "headline": "Still going: New Horizons phones home following historic Pluto flyby",
   "id": 8893,
   "publish_date": 1436963940,
   "short_url": "http://bit.ly/2jvvmBa",
   "slug": "new-horizons-phones-home",
   "source": null,
   "teaser_kicker": "Pluto and beyond",
   "type": "article",
   "url": "https://hub.jhu.edu/2015/07/15/new-horizons-phones-home/"
}

Attributes

_embedded hash

Embedded resources.

Toggle child attributes

_embedded.divisions[] array|null

An array of divisions assigned to the article or null if none are assigned.

_embedded.image_thumbnail[] array|null

An array containing the file assigned as the thumbnail image of the article or null if not assigned

_embedded.tags[] array|null

An array of tags assigned to the article or null if none are assigned.

_embedded.topics[] array|null

An array of topics assigned to the article or null if none are assigned.

_links hash

Links to resources associated with the article.

Toggle child attributes

_links.galleries[] array of link objects

An array of links to galleries related to the article. Omitted if there are no related galleries.

Toggle child attributes

_links.galleries[].href string

URI of the link.

_links.related_content[] array of link objects

An array of links to resources related to the article. Omitted if there are no related resources.

Toggle child attributes

_links.related_content[].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.

alt_headline string

A shorter version of the headline, generally displayed alongside the teaser_kicker attribute.

author string

The name of the author.

excerpt string

A short summary of the article.

headline string

The title of the article.

id integer

Unique identifier of the article.

publish_date timestamp

The date of publication as a Unix timestamp in seconds.

short_url deprecated

slug string

The last part of the URL that identifies the resource.

source hash|null

Only present on summaries (see type attribute). Information about the article summarized.

Toggle child attributes

source.date date

Date of publication. Format: YYYY-MM-DD

source.name string

The name of the publication the article is published in.

source.url string

URL of the summarized article.

teaser_kicker string

A very short headline that compliments the headline or alternative headline.

type string

Type of article. Possible values:

• article: the standard Hub article.
• magazine_article: an article published in Johns Hopkins Magazine.
• summary: an article that summarizes and links to an external article.

url string

Full URL of the article.

Get a subcollection

A subcollection is a collection of objects contained within an article.

GET /articles/:id/:subcollection HTTP/1.1

Endpoint parameters

id integer

The unique identifier of the article.

subcollection string

The name of the subcollection to retrieve. Options: channels, divisions, tags, or topics

Query string parameters

To filter the subcollection, see the list of available parameters associated with the chosen subcollection:

• channels
• divisions
• tags
• topics

Response

See the response associated with the chosen subcollection:

• channels
• divisions
• tags
• topics