Publications

List the publication styles available to the organisation

Publication styles are tightly coupled to publications. A style must be provided when creating a publication, therefore it would be sensible to query this endpoint once in a while to sync which publication types are available to the organisation. It's unlikely a style would ever be revoked from an organisation, but new ones might be added.

Endpoint

GET v1/organisations/{id}/styles

Response Codes

200 OK	Listed the styles successfully
403 Not Authorised	Not allowed to list the styles - probably not allowed to deal with publications in the organisation

Response Body

An array of publication styles. A style consists of:

field	type	description
id	string	The unique ID of the style
name	string	The name of the style
description	string	The description of the style
preview_url	string	The URL to preview the style on a publication
available	boolean	Whether the style is available to use (yet)

Example Response Body

[
    {
        "id": "magazine",
        "name": "Magazine",
        "description": "A photographic awesomeness",
        "preview_url": "http:\/\/google.com",
        "available": true
    },
    {
        "id": "yearbook",
        "name": "Yearbook",
        "description": "Great for large publications, including tag-based browsing and more",
        "preview_url": "http:\/\/google.com",
        "available": false
    }
]

Note that publications that are not available should be considered "coming soon" - that is, they will be available to the user, once it's ready for use.

List an organisation's publications

Endpoint

GET v1/organisations/{id}/publications

Request Parameters

field	required	type	description
search	no	string	Filter results based on a search string
status	no	string	Filter on the status of the publication, either published or unpublished
limit	no	number	How many records to return
offset	no1	number	If limiting, how many records to offset by. Combined with limit, this is useful for pagination
order	no	string	The field and optional direction to order on. Fields that can be ordered on are title, due_date and created_date. To specify with a direction, use a pipe e.g. ?order=due_date|desc

¹An offset can only be supplied with a limit.

Response Codes

200 OK	Listed the publications successfully
403 Not Authorised	Not allowed to list that organisation's publications

Response Body

An array of publications. See "Get a publication" for a description of the fields.

Count an organisation's publications

Endpoint

GET v1/organisations/{id}/publications/count

Request Parameters

This endpoint accepts the same parameters as listing an organisation's publications, except there are no limit, offset or order fields.

Response Body

field	type	description
count	number	The number of publications matched by the query

Example Response Body

{
    "count": 8
}

Create a publication in an organisation

Endpoint

POST v1/organisations/{id}/publications

Request Body

field	required	type	description
title	no1	string	A title for the publication
editorial	no1	string	The HTML text for the editorial. Allows tags: b, i, p, a[href], h3, h4, blockquote, ul, li, br
due_date	no	string	The date (in format YYYY-MM-DD, UTC timezone) when the publication is due to be published
status	yes	string	The status of the publication, in the set {unpublished, published)
style_id	yes	string	The ID of the style to use

¹These fields aren't required so that the publication object can be persisted without needing a title or editorial up front, this method is used by our JavaScript app. However, the publication should have a good title and editorial before it's published.

It's recommended to always add publications as unpublished so there's time to select articles and a featured article before the publication goes into the public domain.

Response Codes

201 Created	Publication created successfully
403 Not Authorised	Not allowed to create a publication in this organisation

Response Body

The newly created publication object. See "Get a publication" for details on the fields.

Get a publication

Endpoint

GET v1/publications/{id}

Response Codes

200 OK	Publication retrieved successfully
403 Not Authorised	Not allowed to get the publication

Response Body

field	type	description
id	string	The unique identifier for the publication
title	string	The title of the publication
editorial	string	The HTML text editorial for the publication
due_date	string	The date the organisation is aiming to publish the publication on
custom_css_url	string	A URL to additional CSS to load into the frontend, will usually be null unless the organisation has arranged with Hail to make modifications to their publication
status	string	The status of the publication - either "unpublished" or "published". Published publications should be considered in the public domain
number_of_articles	number	The number of articles in the publication. Saves having to query the /articles endpoint and counting the number of objects
style	object	The chosen style for the publication, an entity in itself.
featured_article	object	The featured article object, or null if no featured article has been chosen yet
created_date	string	The date the publication was created on
url	string	The URL to view the publication once it's published
watch_status	string	The watch status of the requesting user, in the set {watching, not_watching, unwatched}

Example Response Body

{
    "id": "tukep50",
    "title": "Year 9 Camp",
    "editorial": "<p>We had the best time!<\/p>",
    "due_date": "2015-01-01 01:01:01",
    "custom_css_url": null,
    "status": "unpublished",
    "number_of_articles": 6,
    "url": "http:\/\/dev.hail.to\/p\/tukep50",
    "style": {
        "id": "yearbook",
        "name": "Yearbook",
        "description": "Great for large publications",
        "preview_url": "http:\/\/google.com",
        "available": false
    },
    "featured_article": null,
    "created_date": "2014-05-19 01:24:03",
    "url": "https:\/\/hail.to\/org\/publication\/tukep50",
    "watch_status": "watching"
}

Edit a publication

Endpoint

PUT v1/publications/{publication_id}

Request Body

The same fields (or any subset of) as when creating a publication

Response Codes

200 OK	The publication was updated successfully
403 Not Authorised	Not allowed to update the publication

Response Body

The updated publication, see "Get a publication" for response details.

Watch an article

Endpoint

POST v1/publications/{id}/watch

Response Codes

204 No Content	Watched the publication successfully
403 Not Authorised	Not allowed to watch the publication

Unwatch a publication

Endpoint

DELETE v1/publications/{id}/watch

Response Codes

204 No Content	Unwatched the publication successfully
403 Not Authorised	Not allowed to unflag the publication

Preview a publication

If a publication is not yet published, a one-time URL can be requested which allows the user to load up the publication and circumvent the usual access restrictions for a short period. Once the initial URL is visited, a session will be created (facilitated by the hail cookie) that allows the user in without the access token tacked on the end.

Endpoint

GET v1/publications/{publication_id}/preview

Response Codes

201 Created	The one-time publication preview URL was created successfully
403 Not Authorised	Not allowed to preview the publication, probably because you aren't a member of the organisation

Response Body

field	type	description
url	string	The URL the user should visit to access the publication

Example Response Body

{
    "url": "https:\/\/hail.to\/some-organisation\/publication\/afelhd4?access=5d4w5E2t2FhkOHmetx3wvjXWhif6yXBqHk7yYw8Hr7VJCeAHHglPf7AbbmhNTSQWuEMzxMW5SpBimLaAQu8h5DmcUswkJAQ62f5EPxV8I42bm5AZeGXt69et"
}

Get a publication's connections

Endpoint

GET v1/publications/{id}/connections

Response Body

An array of connections. Each connection consists of:

field	type	description
id	string	The ID of the connection
name	string	The name of the connection1
authorised	boolean	Whether the connection has been authorised
authorised_name	string	The full name of the remote user who authorised the connection
exception	boolean	Whether the connection is in exception2
configured	boolean	Whether the connection has been configured
service	object	The service this connection is for
status	string	The status of the most recent post to the connection. One for pending, posted, failed, retrying3
last_successful_post	string	The date and time of when the publication was last successfully posted to the connection

¹ The name of the connection is relative to the service, so for a Facebook page, the name would be the name of the Facebook page, for example 'Summer Heights High School'. For Twitter, it would be the username of the account, for example 'HailSays'. It's up to the client to determine how to render these in the context of the service (you might want to append 'Facebook page' to the end of the Facebook page name, or prepend a '@' for a Twitter account).

² A connection in exception is a connection that was once authorised and configured, but has encountered a problem since, most likely due to authorisation being revoked or something critical being deleted on the remote service. A connection in exception cannot be posted to, and must be reauthorised and configured by the user.

³ A pending post is queued up ready to post to the remote service, usually within a few seconds. A posted post was successfully posted. A failed post is when a hard-failure result is returned from the remote service, but can be rectified without the whole connection being reauthorised by fixing something and trying again later. A retrying post can occur when a rate limit has been reached at the remote service, or some other error which we can recover from automatically.

Push a publication to a connection

Endpoint

POST v1/publications/{id}/connections

Request Body

field	required	type	description
connection_id	yes	string	The ID of the connection to post to
comment	no	string	For services that support it (e.g. Facebook and Twitter), an optional message to include with the post

Response Codes

202 Accepted	The post job was accepted on to the queue for processing
403 Not Authorised	Not allowed to push the publication to the connection
400 Bad Request	The connection is in exception, isn't authorised or configured, or is already pending processing

Response Body

The updated connection reflecting its new status.