Bondi Admin API Documentation

Introduction

Welcome to the Admin API for Bondi. This is an API that will be used by the Bondi Admin website to access and update data.

This documentation is for API Version 0.8.1.21

OData URL Query Options

The Admin API will work with OData URL Query options (not full OData - just the query options). This will allow you to ask the server to send back a limited set of data. For example, you might want to implement paging and ask for the first 10 Issues (/api/v1/Issue?$top=10), then make another request to get the following 10 issues (/api/v1/Issue?$top=10&$skip=10). Or you might want to filter to only show Issues where Year = 2008 (/api/v1/Issue?$filter=year(GoLiveDate) eq 2008). Using the OData URL Query options will allow for this type of filtering to be calculated on the database but controlled by the application calling the API. This can be done for all of the API endpoints listed below. The documentation for these options is at http://docs.oasis-open.org/odata/odata/v4.0/os/part2-url-conventions/odata-v4.0-os-part2-url-conventions.html#_Toc372793790. Another resource is at section 5 of http://www.odata.org/documentation/odata-version-3-0/url-conventions/.

Extracted Data and Enhanced Data

There are two types of data in the Admin API - Extracted Data and Enhanced Data. Extracted data has been automatically ingested from XML and PNG files by a tool called Scamp. Some of the Extracted data can be edited with the API. Enhanced Data is data that is not ingested at all but is instead entered by hand. All of the data in the API is Extracted Data except for the data related to Custom Fields.

Limitations

This API provides for editing data for existing archive issues, both extracted and enhanced. This API does not include the ability to edit or view users or user data, subscription setup information, subscription and authentication handshake settings for NATS or the ability to edit operational settings for the archive (e.g. home site url for the archive home page). Those settings require direct viewing and editing using SQL scripts specific to each client.

The administrative features of the API are not yet available. As such, there is no ability to create Custom Fields for an article or Media, create Suggested Description templates based off those fields, create Document Types, assign custom fields to document types, add items to lookup list or approve items for a lookup list, etc.

Security

When making a request to the Admin API, you will need to set HTTP headers as follows:

UserName: johnsmith - the current user, used for logging/auditing
UserRoles: editor, admin - the roles the current user has
ApiKey: abcdefg - a shared key that allows an authorized website to use the API
ClientPrefix: CW - a two letter prefix representing the magazine

Users with the 'admin' role can do anything. Users with only the 'editor' role are limited in what they can do.

Errors

HTTP 400 - If you try to call the API without including one of the required HTTP headers, or if one of the headers has an invalid value. The text of the HTTP response will provide details of the problem.
HTTP 401 - If you try to call an API method that a user is not authorized to use, such as calling an admin-only method for a user that is not an admin.
Other HTTP errors are listed with each API endpoint

Issue

An Issue corresponds to a single, physical magazine. An issue has multiple articles. An issue has multiple pages. An article will be printed on a subset of the issue's pages.

API	Description
GET v1/Issue/Years	Get a list of years that the magazine has issues for, along with some summarized data for each year. It will return one record for each year that the magazine published at least one issue.
GET v1/Issue	This will return all issues for the magazine.
GET v1/Issue/Featured	This will return all featured issues for the magazine.
GET v1/Issue/{issueKey}	This will return a single issue matching the IssueKey provided.
PUT v1/Issue/{issueKey}	Update an Issue
PUT v1/Issue/{issueKey}/Live/{isLive}	Change the Issue IsLive status
GET v1/Issue/{issueKey}/Articles	This will return all articles for a single issue matching the IssueKey provided.
GET v1/Issue/{issueKey}/Articles/Attributes	This will return all articles for a single issue matching the IssueKey provided.
GET v1/Issue/{issueKey}/Pages	This will return all pages for a single issue matching the IssueKey provided.
GET v1/Issue/{issueKey}/Media	This will return all media for a single issue matching the IssueKey provided.
POST v1/Issue/{issueKey}/Attributes/Featured	Finds the issue matching the specified issueKey and updates the "featured" attributes.
GET v1/Issue/{issueKey}/Attributes	This will return attrubutes for a single issue matching the IssueKey provided.

Article

Methods for working with Articles. A magazine issue will have multiple articles in it. The Genre of an article determines whether it is an article, advertisement, etc.

API	Description
GET v1/Article/{articleKey}	Finds the article matching the specified articleKey.
PUT v1/Article/{articleKey}	Update an article.
GET v1/Genre	Finds all Genres
GET v1/Article/{articleKey}/Attributes	Finds the article matching the specified articleKey and grabs the attributes.
POST v1/Article/{articleKey}/Attributes	Finds the article matching the specified articleKey and grabs the attributes.
POST v1/Article/{articleKey}/Attributes/Featured	Finds the article matching the specified articleKey and updates the "featured" attributes.
POST v1/Article/{articleKey}/Attributes/Text	Finds the article matching the specified articleKey and updates the body text.
POST v1/Article/{articleKey}/Attributes/EditorNotes	Finds the article matching the specified articleKey and updates the body text.
POST v1/Article/{articleKey}/IsPublished/{isPublished}	Finds the article matching the specified articleKey and updates the IsPublished flag.
GET v1/Article/{articleKey}/DynamicAttributes	This will return attrubutes for a single issue matching the IssueKey provided.
POST v1/Article/{articleKey}/Attributes/ImageUrl	Finds the article matching the specified articleKey and updates the body text.

Subtitle

API	Description
POST v1/Article/{articleKey}/Subtitle	Create a Subtitle for an article.
PUT v1/Article/{articleKey}/Subtitle/{subtitleKey}	Update a subtitle.
DELETE v1/Article/{articleKey}/Subtitle/{subtitleKey}	Delete a subtitle.

Creator

Methods for working with Creators. There are multiple creators for a project.

API	Description
POST v1/Article/{articleKey}/Creator	Create a creator for an article. There can be multiple creators for an article.
PUT v1/Article/{articleKey}/Creator/{creatorKey}	Update an existing Creator.
DELETE v1/Article/{articleKey}/Creator/{creatorKey}	Delete a Creator.
GET v1/Article/Creator/Count	Get a list of all creators currently assigned to articles

Contributor

Methods for working with Contributors. There are multiple contributors for an article.

API	Description
POST v1/Article/{articleKey}/Contributor	Create a contributor for an article. There can be multiple contributors for an article.
PUT v1/Article/{articleKey}/Contributor/{contributorKey}	Update a Contributor.
DELETE v1/Article/{articleKey}/Contributor/{contributorKey}	Delete a Contributor.
GET v1/Article/Contributor/Count	Get a list of all contributors currently assigned to articles

Type

API	Description
POST v1/Article/{articleKey}/Type	Create a type for an article. To see the list of possible types, visit the ElementTypes controller.
PUT v1/Article/{articleKey}/Type/{typeKey}	Update a Type. To see the list of possible types, visit the ElementTypes controller.
DELETE v1/Article/{articleKey}/Type/{typeKey}	Delete an Article Type. To see the list of possible types, visit the ElementTypes controller.

ElementType

Methods for working with Elements Types. These are used for assigning multiple types to an Article via ArticleTypes and a single type to each Media via the MediaTypeId field.

API	Description
GET v1/ElementType	Get a list of all Element Types. These are used for assigning multiple types to an Article via ArticleTypes and a single type to each Media via the MediaTypeId field.

ObjectReview

Methods for working with ObjectReviews.

API	Description
POST v1/Article/{articleKey}/ObjectReview	Create an objectReview for an article.
POST v1/Article/{articleKey}/ObjectReview/{objectReviewKey}	Update a ObjectReview.
DELETE v1/Article/{articleKey}/ObjectReview/{objectReviewKey}	Delete a ObjectReview.

Zone

API	Description
PUT v1/ZoneJump/{zoneJumpKey}	Update a ZoneJump.

Paragraph

Methods for working with paragraphs. There are multiple paragraphs to an article. Some paragraphs contain text, in which case the ParagraphContent/ParagraphText fields will contain data. Some paragraphs contain images, in which case the ParagraphContent/ParagraphText fields will be empty and there will be a related Medias record.

API	Description
GET v1/Paragraph/ParagraphTypes	Get a list of all valid paragraph types.
GET v1/Article/{articleKey}/Paragraph	Get a list of paragraphs in a specific article. Note that due to the implementation, you cannot call this with any server-side paging, filtering, or sorting.
GET v1/Article/{articleKey}/Paragraph/{paragraphKey}	Get a single paragraph using the paragraphKey
PUT v1/Article/{articleKey}/Paragraph/{paragraphKey}	Update a paragraph

Media

Methods for working with Media. Media is a specific kind of paragraph that has an image instead of text. When a paragraph is media, the text fields on the paragraph object will be blank.

API	Description
PUT v1/Media/{mediaKey}	Update a Media record.
PUT v1/Media/{mediaKey}/IsReviewed/{isReviewed}	Update a Media -> IsReviewed record.
GET v1/Media/{mediaKey}	Finds the media matching the specified mediaKey.
GET v1/Article/{articleKey}/Media	Get a list of media in a specific article. Note that due to the implementation, you cannot call this with any server-side paging, filtering, or sorting.

CustomFields

Methods for working with Custom Fields. Custom fields can be part of articles or part of Media. The values currently set for custom fields will be returned when an article or media are returned from other API methods.

API	Description
POST v1/CustomField/{customFieldId}/Lookup	Adds an approved custom field lookup to the specified custom field. The user is only allowed to do this if the 'CanAddLookup' property on the CustomField is true. When added, the ApprovedBy and ApprovedDate fields will be set to the current date and the current username. If the call is successful, the field value can be used immediately.
POST v1/CustomField/{customFieldId}/LookupSuggestion	Adds an unapproved custom field lookup to the specified custom field. The user is only allowed to do this if the 'CanSuggestLookup' property on the CustomField is true. When added, the ApprovedBy and ApprovedDate fields will both be null. The custom field lookup cannot be used on an article or media until it has been approved by an administrator.
GET v1/CustomField/Lookup	Retrieves a list of all custom fields with their lookups.
GET v1/CustomFields/{customFieldID}/Lookups	Get a list of all creators currently assigned to articles
GET v1/Genre/{genreId}/Article/CustomFields	Finds the custom fields available for articles with a specified genre. This returns information about the fields that an article of a specified genre is allowed to use - it does not return the values that are set for the article's custom fields.
GET v1/Genre/{genreId}/Article/CustomFields/WithLookups	Finds the custom fields available for articles with a specified genre, and returns all lookup values for the fields. This returns information about the fields that an article of a specified genre is allowed to use - it does not return the values that are set for the article's custom fields.
GET v1/Genre/{genreId}/Media/CustomFields	Finds the custom fields available for media related to articles with a specified genre. This returns information about the fields that a media related to an article of a specified genre is allowed to use - it does not return the values that are set for the article's custom fields.
GET v1/Genre/{genreId}/Media/CustomFields/WithLookups	Finds the custom fields available for media with a specified genre, and returns all lookup values for the fields. This returns information about the fields that an media of a specified genre is allowed to use - it does not return the values that are set for the media's custom fields.
GET v1/Article/{articleKey}/CustomFields	Finds the custom fields available for the article matching the specified articleKey. This returns information about the fields that an article is allowed to use given it's current genre - it does not return the values that are set for the article's custom fields.
GET v1/Article/{articleKey}/CustomFields/WithLookups	Finds the custom fields available for articles matching the specified articleKey, and returns all lookup values for the fields. This returns information about the fields that an article of a specified genre is allowed to use - it does not return the values that are set for the article's custom fields.
GET v1/Article/{articleKey}/Media/CustomFields	Finds the custom fields available for media related to the article matching the specified articleKey. This returns information about the fields that an media is allowed to use given the genre of it's article - it does not return the values that are set for the article's custom fields.
GET v1/Article/{articleKey}/Media/CustomFields/WithLookups	Finds the custom fields available for media related to the article matching the specified articleKey, and returns all lookup values for the fields. This returns information about the fields that an article of a specified genre is allowed to use - it does not return the values that are set for the article's custom fields.
PUT v1/Article/{articleKey}/media/{mediaKey}/CustomFieldValues	Updates the values in the custom fields for the media matching the specified mediaKey related to the article matching the specified articleKey. This will completely replace all custom field values for the specified media. Any custom fields not listed in fieldValues will have their values removed from the Media.
PUT v1/Article/{articleKey}/CustomFieldValues	Updates the values in the custom fields for the article matching the specified articleKey. This will completely replace all custom field values for the specified article. Any custom fields not listed in fieldValues will have their values removed from the Article.

DocumentDescription

Methods for working with Document Descriptions. Document Descriptions can be associated with either an Article or a Media. There can be multiple Document Descriptions per Article/Media. You can add arbitrary Document Descriptions to a media or article or use some of the suggested document descriptions.

API	Description
GET v1/Article/{articleKey}/Descriptions	Get the document descriptions for an article.
GET v1/Article/{articleKey}/Media/{mediaKey}/Descriptions	Get the document descriptions for a media on an article.
POST v1/Article/{articleKey}/Description	Create a document description for an article. There can be multiple document descriptions for an article.
POST v1/Article/{articleKey}/Media/{mediaKey}/Description	Create a document description for a media. There can be multiple document descriptions for a media.
PUT v1/Article/{articleKey}/Description/{docDescriptionId}	Updates a document description for an article. There can be multiple document descriptions for an article.
PUT v1/Article/{articleKey}/Media/{mediaKey}/Description/{docDescriptionId}	Updates a document description for a media. There can be multiple document descriptions for a media.
DELETE v1/Article/{articleKey}/Description/{docDescriptionId}	Deletes a document description for an article. There can be multiple document descriptions for an article.
DELETE v1/Article/{articleKey}/Media/{mediaKey}/Description/{docDescriptionId}	Deletes a document description for a media. There can be multiple document descriptions for a media.
GET v1/Article/{articleKey}/Description/Suggest	Based on an article's Genre and the Custom Field Values currently assigned to the article, provide a list of suggested document descriptions. If a user wants to assign a document description to an article, there is a separate API endpoint for creating a document description.
GET v1/Article/{articleKey}/Media/{mediaKey}/Description/Suggest	Based on an article's Genre and the Custom Field Values currently assigned to a related media, provide a list of suggested document descriptions. If a user wants to assign a document description to a media, there is a separate API endpoint for creating a document description.

DocumentType

Methods for working with Document Types. Document Types can be associated with either an Article or a Media.

API	Description
GET v1/DocumentTypes/Article	Get a list of document types that are valid for articles
GET v1/DocumentTypes/Media	Get a list of document types that are valid for media

SampleData

Methods for finding interesting sample data to work with

API	Description
GET v1/Sample/CustomFieldValues/Article/min/{minFieldValueLength}/max/{maxFieldValueLength}	Get sample data for Article Custom Field Values where the length of the internal representation of the custom field values is in the specified range
GET v1/Sample/CustomFieldValues/Media/min/{minFieldValueLength}/max/{maxFieldValueLength}	Get sample data for Media Custom Field Values where the length of the internal representation of the custom field values is in the specified range

Version

API	Description
GET Version	Returns version of the API

Topic

API	Description
POST v1/Topic/Update	Updates the Topic
GET v1/Topic/{topicId}/Articles	Get a list of all Sections. These are used for assigning multiple sections to an Article via Sections.
GET v1/Topic/{topicId}/Modules	Get a list of all Sections. These are used for assigning multiple sections to an Article via Sections.
GET v1/Topic/{topicId}/Module/Articles	Get a list of all Sections. These are used for assigning multiple sections to an Article via Sections.
GET v1/Topic/{topicId}/Articles/Count	Get a list of all Sections. These are used for assigning multiple sections to an Article via Sections.
POST v1/Topic/Update/Relationships	Get a list of all Sections. These are used for assigning multiple sections to an Article via Sections.
POST v1/Topic/Insert/Relationship
POST v1/Topic/Delete/Relationship
POST v1/Topic/Module/Article/Insert	No documentation available.
POST v1/Topic/Module/Article/Delete	No documentation available.
POST v1/Topic/Module/Articles/Update	No documentation available.
POST v1/Topic/Module/Update	No documentation available.
GET v1/Topics/ByTypeName/{name}
GET v1/Topics/ByTypeName/{name}/Article/{articleKey}
POST v1/Topic/{topicId}/ImageUrl	Finds the article matching the specified articleKey and updates the body text.

Section

API	Description
POST v1/Article/{articleKey}/Section	Create a Section for an article.
PUT v1/Article/{articleKey}/Section/{sectionKey}	Update a section.
DELETE v1/Article/{articleKey}/Section/{sectionKey}	Delete a section.
GET v1/Section	Get a list of all Sections. These are used for assigning multiple sections to an Article via Sections.
GET v1/Section/{section}/Articles	Get a list of all Sections. These are used for assigning multiple sections to an Article via Sections.

Image

API	Description
GET v1/Image/VerificationKey	Finds the image verification key of the client.

Tag

API	Description
GET v1/Article/{articleKey}/Tags	Tag an Article
POST v1/Tag/Add	Tag an Article
POST v1/Tag/Delete	Tag an Article

Batch

API	Description
POST v1/Batch/Add	Finds the article matching the specified articleKey.
GET v1/Batch/{batchId}	Get batch by BatchID
GET v1/Batches	Get all Batches
GET v1/Batch/IssueProcesses	Get all IssueProcesses
GET v1/Batch/Latest	Finds the last batch matching the specified publication prefix.
GET v1/Batch/{batchId}/Messages	Get all messages associated with a batch
GET v1/Batch/Settings	Get TitleSettings for this publication
POST v1/Batch/Settings/Update	Get TitleSettings for this publication