@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api BC Gov News API Service 1.0
@base https://news.api.gov.bc.ca/
@version 1.0
@common_fields {api-version: str=1.0 # The requested API version}
@endpoints 27
@hint download_for_search
@toc api(27)

@endpoint GET /api/FacebookPosts/ByUri
@desc Get a Facebook post based on a Uri
@optional {uri: str=}
@returns(200) {poster: str, posterLogo: str, posterSubtitle: str, posterLikes: int(int32), content: str, postLikes: int(int32), postComments: int(int32), postShares: int(int32), facebookObjectId: int(int32), type: str, pictureUri: str} # Success

@endpoint GET /api/Home
@desc Returns the top level content for the home page
@returns(200) {liveWebcastFlashMediaManifestUrl: str, liveWebcastM3uPlaylist: str, name: str, topPostKey: str, featurePostKey: str} # Success

@endpoint GET /api/Ministries
@desc Get all ministries
@returns(200) Success

@endpoint GET /api/Ministries/{key}
@desc Get the Ministry associated with the ministry key
@required {key: str}
@returns(200) {childMinistryKey: str, parentMinistryKey: str, ministryUrl: str, displayAdditionalName: str, topicLinks: [map], serviceLinks: [map], newsletterLinks: [map], ministerName: str, contactUser: map{fullName: str, phoneNumber: str, mobileNumber: str, emailAddress: str}, secondContactUser: map{fullName: str, phoneNumber: str, mobileNumber: str, emailAddress: str}, weekendContactNumber: str, twitterFeedUsername: str, flickrUri: str, youtubeUri: str, audioUri: str, isActive: bool, name: str, topPostKey: str, featurePostKey: str} # Success

@endpoint GET /api/Ministries/{key}/Minister
@desc Get the Minister associated with the ministry key
@required {key: str}
@returns(200) {headline: str, summary: str, details: str, emailHtml: str, photo: str, post: str} # Success

@endpoint GET /api/Newsletters
@desc Get all newsletters
@returns(200) Success

@endpoint GET /api/Newsletters/{newsletterKey}
@desc Get a specific newsletter
@required {newsletterKey: str}
@returns(200) {name: str, ministryName: str, description: str, editions: [map]} # Success

@endpoint GET /api/Newsletters/{newsletterKey}/Editions/{editionKey}
@desc Returns a specific edition of a newsletter
@required {newsletterKey: str, editionKey: str}
@returns(200) {name: str, htmlBody: str} # Success

@endpoint GET /api/Newsletters/{newsletterKey}/Editions/{editionKey}/Articles/{articleKey}
@desc Get an article belonging to a Newsletter edition
@required {newsletterKey: str, editionKey: str, articleKey: str}
@returns(200) {editionName: str, htmlBody: str} # Success

@endpoint GET /api/Newsletters/Images/{guid}
@desc Get the image object reference by of a Newsletter Edition associated with the image guid
@required {guid: str}
@returns(200) {fileName: str, imageBytes: str(byte), imageType: str} # Success

@endpoint GET /api/Posts/{key}
@desc Get the post associated with the key
@required {key: str}
@returns(200) {kind: str, atomId: str, summary: str, socialMediaSummary: str, socialMediaHeadline: str, keywords: str, publishDate: str(date-time), leadMinistryKey: str, hasMediaAssets: bool, isNewsOnDemand: bool, assetUrl: str, location: str, documents: [map], reference: str, redirectUri: str, ministryKeys: [str], sectorKeys: [str], serviceKeys: [str], facebookPictureUri: str, azureAssets: [map]} # Success

@endpoint GET /api/Posts
@desc Get the posts associated with the keys in the list passed in.
@optional {postKeys: [str]=}
@returns(200) Success

@endpoint GET /api/Posts/Latest/{indexKind}/{indexKey}
@desc Get the latest posts of postKind for the specified index (default or category)
@required {indexKind: str # home or one of categories, indexKey: str # default or one key of the categories (ministries, sectors, services, tags, themes)}
@optional {postKind: str= # One of: releases, stories, factsheets, updates or default (releases+stories except top/feature), count: int(int32)= # number of posts to return, skip: int(int32)= # number of posts to skip}
@returns(200) Success

@endpoint GET /api/Posts/Keys/{indexKind}/{indexKey}
@desc Get all keys for the specified index (newsroom or category)
@required {indexKind: str # home or one of categories, indexKey: str # default or one key of the categories (ministries, sectors, services, tags, themes)}
@optional {postKind: str= # One of: releases, stories, factsheets, updates or default (releases+stories+factsheets), count: int(int32)= # number of posts to return, skip: int(int32)= # number of posts to skip}
@returns(200) Success

@endpoint GET /api/Posts/Keys/{reference}
@desc Get the post key associated with the reference.
@required {reference: str}
@returns(200) {key: str, value: str} # Success

@endpoint GET /api/Posts/LatestMediaUri/{mediaType}
@desc Gets the latest Social Media post for the social media type passed in.
@required {mediaType: str}
@returns(200) Success

@endpoint GET /api/ResourceLinks
@desc Get all resource links
@returns(200) Success

@endpoint GET /api/Sectors
@desc Get all Sectors
@returns(200) Success

@endpoint GET /api/Sectors/{key}
@desc Get the sector associated with the key
@required {key: str}
@returns(200) {twitterFeedUsername: str, flickrUri: str, youtubeUri: str, audioUri: str, isActive: bool, name: str, topPostKey: str, featurePostKey: str} # Success

@endpoint GET /api/Services
@desc Get all Services
@returns(200) Success

@endpoint GET /api/Services/{key}
@desc Get the service associated with the passed key
@required {key: str}
@returns(200) {twitterFeedUsername: str, flickrUri: str, youtubeUri: str, audioUri: str, isActive: bool, name: str, topPostKey: str, featurePostKey: str} # Success

@endpoint GET /api/Slides/{id}
@desc Get the slide associated to the id
@required {id: str}
@returns(200) {slideId: str(uuid), headline: str, summary: str, actionLabel: str, actionUri: str, image: str(byte), facebookPostUri: str, justify: str, imageType: str} # Success

@endpoint GET /api/Slides
@desc Get all Slides
@returns(200) Success

@endpoint GET /api/Tags
@desc Get all Tags
@returns(200) Success

@endpoint GET /api/Tags/{key}
@desc Get the Tag associated with the key
@required {key: str}
@returns(200) {twitterFeedUsername: str, flickrUri: str, youtubeUri: str, audioUri: str, isActive: bool, name: str, topPostKey: str, featurePostKey: str} # Success

@endpoint GET /api/Themes
@desc Get all Themes
@returns(200) Success

@endpoint GET /api/Themes/{key}
@desc Get the Theme associated with the key
@required {key: str}
@returns(200) {twitterFeedUsername: str, flickrUri: str, youtubeUri: str, audioUri: str, isActive: bool, name: str, topPostKey: str, featurePostKey: str} # Success

@end