Developer Platform (July 2017)

News service (news items, user feed)

«  Discussions (forums, topics, posts)   ·  [   home  ·   reference  ·   community   ·  search   ·  index   ·  routing table   ·  scopes table   ]   ·  Calendar (Events and scheduling)  »

Contents

Attributes

Feed.UserFeedResource

The feed service returns generically formed blocks that wrap around particular kinds of resources. For example, a UserFeedResourceNewsItem variant of the generic container contains a Resource composite that’s actually a NewsItem structure.

{
    "Type": <string>,
    "MessageMetaData": {
        "Identifier": <string>,
        "Title": <string>,
        "Summary": { <composite:RichText> },
        "Date": <string:UTCDateTime>,
        "ApiViewUrl": <string:URL>,
        "WebViewUrl": <string:URL>
    },
    "Resource": { <composite> }  // Generic resource composite wrapper
}
News.NewsItem

If you use an action that retrieves News Item data from the service, it sends the data back to you in a block like this:

{
    "Id": <number:D2LID>,
    "IsHidden": <boolean>,
    "Attachments": [ // Array of File blocks
        {
            "FileId": <number:D2LID>,
            "FileName": <string>,
            "FileSize": <number>
        },
        { <composite:File> }, ...
    ],
    "Title": <string>,
    "Body": { <composite:RichText> },
    "StartDate": <string:UTCDateTime>|null,
    "EndDate": <string:UTCDateTime>|null,
    "IsGlobal": <boolean>,
    "IsPublished": <boolean>,
    "ShowOnlyInCourseOfferings": <boolean>,
}
News.NewsItemData

If you use an action where you must provide News Item data, then the service expects you to send it in a block like this:

{
    "Title": <string>,
    "Body": { <composite:RichText> },
    "StartDate": <string:UTCDateTime>,
    "EndDate": <string:UTCDateTime>|null,
    "IsGlobal": <boolean>,
    "IsPublished": <boolean>,
    "ShowOnlyInCourseOfferings": <boolean>
}

Note

When you provide a RichText composite Body in a NewsItemData structure, you should not provide an empty-string “Html” property field if your intention is to provide a text-only news body. Rather, you should pass in an explicit NULL for the field.

Actions

DELETE /d2l/api/le/(version)/(orgUnitId)/news/(newsItemId)

Delete a particular news item from an org unit.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId – Org unit ID.
  • newsItemId (D2LID) – News Item ID.
Status Codes:
API Versions:
  • 1.12+ – Route first appears in LMS v10.6.0.
  • 1.5-1.11Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.
DELETE /d2l/api/le/(version)/(orgUnitId)/news/(newsItemId)/attachments/(fileId)

Delete an attachment from an org unit’s news item.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId – Org unit ID.
  • newsItemId (D2LID) – News Item ID.
  • fileId (D2LID) – File attachment ID.
Status Codes:
  • 200 OK – Action succeeded.
  • 403 Forbidden – No permission to see news for this org unit.
  • 404 Not Found – News item not found, or file attachment not found.
API Versions:
  • 1.12+ – Route first appears in LMS v10.6.0.
  • 1.5-1.11Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.
GET /d2l/api/lp/(version)/feed/

Fetch the feed for the current user context.

Parameters:
Query Parameters:
 
  • since (UTCDateTime) – Optional. Earliest publication time to retrieve.
  • until (UTCDateTime) – Optional. Latest publication time to retrieve.
Status Codes:
API Versions:
  • 1.9+ – Route first appears in LMS v10.6.0.
  • 1.5-1.8Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

This call retrieves and aggregates a list of user messages gathered from various sources in the back-end service. The original sources for those messages determine when a user event message gets made available for aggregation, and when the events expire from the pool available to this API call.

Note that, unlike many Brightspace APIs, there is currently no direct functional equivalent for this API call in the web UI.

since and until

You can use these query parameters to time-box the list of things returned in the feed list with this call.

If you do not provide a since value, this call returns only a list of “recent” feed items: those with a publication time sometime within the twenty-four hours preceding the time when the back-end service handles your call.

If you provide a since value, and do not provide an until value, this call returns all the feed items from your provided since time up until the time when the back-end service handles your call.

If you provide a since value, and do provide an until value, this call returns all the feed items between your two provided time parameters. Note that, if your since parameter is more recent than your until parameter, this action returns success and an empty feed list.

Return. This action returns a JSON array of UserFeedResource data blocks. Note that each element in this list will be named appropriately for the kind of resource it envelops.

GET /d2l/api/le/(version)/(orgUnitId)/news/

Retrieve a list of news items for an org unit.

Parameters:
Query Parameters:
 
  • since (UTCDateTime) – Optional. Earliest publication time to retrieve.
Status Codes:
API Versions:
  • 1.12+ – Route first appears in LMS v10.6.0.
  • 1.5-1.11Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Return. This action returns a JSON array of NewsItem data blocks containing news items’ properties.

Changed in version 1.5: Note that, as of v1.5+ of the API, this call will include news items in the list that have the IsHidden property set to true; v1.4 of the API and prior do not include hidden news items in the returned list.

GET /d2l/api/le/(version)/(orgUnitId)/news/deleted/
Parameters:
Query Parameters:
 
  • global (boolean) – Optional. Show only global news items if present and true; otherwise, show no global items.
Status Codes:
  • 200 OK – Action succeeded.
  • 403 Forbidden – No permission to see news items of requested type.
API Versions:
  • unstable – Route first appears in LMS v10.5.2.

Return. This action returns a JSON array of NewsItem data blocks containing the properties of deleted news items. Note that this action will also retrieve deleted news item that have the IsHidden property set to true.

GET /d2l/api/le/(version)/(orgUnitId)/news/(newsItemId)

Retrieve a particular news item for an org unit.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId – Org unit ID.
  • newsItemId (D2LID) – News Item ID.
Status Codes:
API Versions:
  • 1.12+ – Route first appears in LMS v10.6.0.
  • 1.5-1.11Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Return. This action returns a NewsItem JSON data block containing the news item’s properties.

GET /d2l/api/le/(version)/(orgUnitId)/news/(newsItemId)/attachments/(fileId)

Retrieve an attachment for an org unit’s news item.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId – Org unit ID.
  • newsItemId (D2LID) – News Item ID.
  • fileId (D2LID) – File attachment ID.
Status Codes:
  • 200 OK – Action succeeded.
  • 403 Forbidden – No permission to see news for this org unit.
  • 404 Not Found – News item not found, or file attachment not found.
API Versions:
  • 1.12+ – Route first appears in LMS v10.6.0.
  • 1.5-1.11Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Return. This action returns a file stream containing the attachment file data.

POST /d2l/api/le/(version)/(orgUnitId)/news/

Create a news item for an org unit.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId – Org unit ID.
JSON Parameters:
 
  • NewsItemData (News.NewsItemData) – Data for new news item (see input description).
Status Codes:
API Versions:
  • 1.12+ – Route first appears in LMS v10.6.0.
  • 1.5-1.11Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Input. Provide a multipart/mixed POST body: the first part must be the news item data JSON; other parts may include file attachments to go along with the news item.

If you want to create a new item as a draft, make sure to set the news item’s IsPublished property to false. In order to publish such a created news item, you must then use the Publish action.

Return. Returns a NewsItem JSON data block for the newly created news item.

POST /d2l/api/le/(version)/(orgUnitId)/news/deleted/(newsItemId)/restore
Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId (D2LID) – Org unit ID.
  • newsItemId (D2LID) – News Item ID.
Status Codes:
API Versions:
  • unstable – Route first appears in LMS v10.5.2.

Return. Returns a NewsItem JSON data block for the newly restored news item.

POST /d2l/api/le/(version)/(orgUnitId)/news/(newsItemId)/attachments/

Add an attachment to a news item for an org unit.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId – Org unit ID.
  • newsItemId (D2LID) – News Item ID.
Status Codes:
API Versions:
  • 1.12+ – Route first appears in LMS v10.6.0.
  • 1.5-1.11Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Input. Use a multipart/form-data POST body to provide the attachment data to add to the news item, with the part’s Content-Disposition header’s name field set to “file”.

POST /d2l/api/le/(version)/(orgUnitId)/news/(newsItemId)/dismiss

Dismiss (hide) a news item for an org unit.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId – Org unit ID.
  • newsItemId (D2LID) – News Item ID.
Status Codes:
API Versions:
  • 1.12+ – Route first appears in LMS v10.6.0.
  • 1.5-1.11Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.
POST /d2l/api/le/(version)/(orgUnitId)/news/(newsItemId)/publish

Publish a draft news item for an org unit.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId – Org unit ID.
  • newsItemId (D2LID) – News Item ID.
Status Codes:
API Versions:
  • 1.12+ – Route first appears in LMS v10.6.0.
  • 1.5-1.11Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.
POST /d2l/api/le/(version)/(orgUnitId)/news/(newsItemId)/restore

Restore (unhide) a news item for an org unit.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId – Org unit ID.
  • newsItemId (D2LID) – News Item ID.
Status Codes:
API Versions:
  • 1.12+ – Route first appears in LMS v10.6.0.
  • 1.5-1.11Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.
PUT /d2l/api/le/(version)/(orgUnitId)/news/(newsItemId)

Update a news item for an org unit.

Parameters:
  • version (D2LVERSION) – API version.
  • orgUnitId – Org unit ID.
  • newsItemId (D2LID) – News Item ID.
JSON Parameters:
 
Status Codes:
  • 200 OK – Action succeeded.
  • 400 Bad Request – Invalid news item data provided, or attempt to provide a draft news update to a published news item.
  • 403 Forbidden – No permission to update news items for this org unit.
  • 404 Not Found – News item not found.
API Versions:
  • 1.12+ – Route first appears in LMS v10.6.0.
  • 1.5-1.11Deprecated as of LMS v10.7.0.
  • 1.4-Obsolete as of LMS v10.7.0.

Note

If the org unit’s news item has already been published, then you may not provide an update with the IsPublished property set to false (i.e. once an item is no longer a draft item, you can’t turn it back into a draft item). However, if the org unit’s news item is in draft state, you can publish it with this action by setting the IsPublished property to true.

«  Discussions (forums, topics, posts)   ·  [   home  ·   reference  ·   community   ·  search   ·  index   ·  routing table   ·  scopes table   ]   ·  Calendar (Events and scheduling)  »