Announcements

Get a collection

      Endpoint
    
GET /announcements HTTP/1.1

Query string parameters

All query string parameters are optional.

announcement_categories comma-separated list of IDs

Return announcements assigned to the given announcement categories.

audience comma-separated list

Return announcements assigned to the specified audience(s). Options: faculty, staff, students

callback string

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

divisions comma-separated list of IDs

Return announcements assigned to the given divisions.

excluded_ids comma-separated list of IDs

Returns announcements, except those with the given IDs.

ids comma-separated list of IDs

Return announcements with the given IDs.

order_by comma-separated list

Sort announcements 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 announcement 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 announcements from a specific page of a collection.

Default value: 1

per_page integer

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

Default value: 5

tags comma-separated list of IDs

Return announcements assigned to the given tags.

Response

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

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

Attributes

_embedded hash: Embedded resources.
_links hash: Links to resources associated with the announcement collection.
page integer: The page number of the returned collection.
per_page integer: The number of announcements requested per page.
return_count integer: Number of announcements returned.
total_available integer: Total number of announcements available in the collection.

Get one

      Endpoint
    
GET /announcements/:id HTTP/1.1

Endpoint parameters

id integer required: The unique identifier of the announcement.

Response

      GET /announcements/12973
    
{
   "_embedded": {
      "announcement_categories": null,
      "divisions": null,
      "image_thumbnail": null,
      "tags": null
   },
   "_links": {
      "self": {
         "href": "/announcements/12973"
      }
   },
   "alt_headline": "Workshop: Surviving and Thriving in an Academic Career",
   "audience": [
      "faculty",
      "staff",
      "students"
   ],
   "author": "Hub staff report",
   "excerpt": "This multidisciplinary workshop, hosted by the School of Nursing, will be held June 1-3 at the Bloomberg School",
   "headline": "Save the date: Surviving and Thriving in an Academic Career workshop, June 1-3",
   "id": 12973,
   "publish_date": 1457928000,
   "short_url": "http://bit.ly/2mFh2En",
   "slug": "save-the-date-surviving-and-thriving-in-an-academic-career-workshop-june-1-3-2016",
   "teaser_kicker": "SAVE THE DATE",
   "type": "announcement",
   "url": "https://hub.jhu.edu/announcements/2016/03/14/save-the-date-surviving-and-thriving-in-an-academic-career-workshop-june-1-3-2016/"
}

Attributes

_embedded hash: Embedded resources.
_links hash: Links to resources associated with the announcement.
alt_headline string: A shorter version of the headline, generally displayed alongside the teaser_kicker attribute.
audience array: Audience(s) that the announcement is targeted to. Possible values: faculty, staff, and/or students
author string: The name of the author.
excerpt string: A short summary of the announcement.
headline string: The title of the announcement.
id integer: Unique identifier of the announcement.
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.
teaser_kicker string: A very short headline that compliments the headline or alternative headline.
type string: Type of resource.
url string: Full URL of the announcement.

Get a subcollection

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

      Endpoint
    
GET /announcements/:id/:subcollection HTTP/1.1

Endpoint parameters

id integer: The unique identifier of the announcement.
subcollection string: The name of the subcollection to retrieve. Options: announcement_categories, divisions, or tags

Query string parameters

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

Response

See the response associated with the chosen subcollection: