Richie Editions HTML5: Issue Indexes

Integrating the web version of Richie Editions with your website typically entails the following steps:

1. Download and cache a list of issues from Richie servers, and use the contents to display a link to the latest issue. You may also choose to implement an archive view on your web site based on these files, if you do not wish to use Richie Editions’s built-in archive view.

2. Implement an authentication gateway to control access to issues. See the RichieSSO authenticated sign-in documentation for details.

Richie servers should be accessed using the HTTPS protocol.

Issue indexes

The primary issue index, commonly referred to as index.json, is always available at the URL https://<hostname>/_data/index_v2.json, where hostname is your Richie Editions server name. This URL may return a redirect, which your code must follow to get the data. Note: never store or reuse the redirected location, as this will change without notice. Always use the above canonical URL.

If your Richie Editions server is configured to use per-product subdirectories, the index file will be available under the assigned product paths. The URL will be of the form https://<hostname>/<product>/_data/index_v2.json.

Examples of index URLs for a Richie Editions server called editions.richie.fi:

• Top-level index: https://editions.richie.fi/_data/index_v2.json
• Index for product daily-news: https://editions.richie.fi/daily-news/_data/index_v2.json

Your code must be prepared to handle compressed files with the corresponding Content-Encoding HTTP header set. At minimum, you should be prepared to handle files with Content-Encoding set to gzip, though supporting other common encodings such as zlib is recommended.

Index format

The index is returned as a JSON dictionary as follows:

{
  "issues": {
    "example-organization/example-product":
      [
        {
          "uuid":"2258b0e6-6748-46c2-8e67-0893c0542fbb",
          "name":"14.6.2023",
          "published_at":"2023-06-14T00:00:00.000Z",
          "product_name":"Example Product",
          "org": "example-organization",
          "product": "example-product",
          "is_available_free":false,
          "master_cover":{
            "height":2048,
            "url":"https://data.richie.app/editions-eu-images/issue/f/1/1/issue_f1148aa3-90ff-4a5d-8639-8ee2bd71ca43_issue/master_preview_master_cover.png",
            "width":1567
          },
          "external_match_tag": "example-tag",
          "featured_until":"2023-06-21T00:00:00.000Z"
        }, ...
        ]
      "example-organization/example-product-2": ...
    }
}

The top-level dictionary will always contain the issues key, which refers to a dictionary with your configured products. These keys refer to the products configured in Editions Author for your newspaper, magazine or other product. Any other keys in the top-level dictionary must be ignored.

Each product (e.g. example-organization/example-product) will refer to an array of issue data dictionaries. The keys in these dictionaries are described below. Any key not described below must be ignored by your code.

These keys will always be present:

• uuid: a unique identifier for this issue. This value is used in constructing the RichieSSO sign-in URL.
• name: the name of this issue to be displayed to users. This is assigned in Editions Author.
• published_at: the time at which this issue was published in UTC. The format follows the ISO 8601 standard.
• master_cover: issue cover thumbnail, described below.
• is_available_free: if true, this issue should be available to users who are not subscribers. This item can be configured in Editions Author. It is up to your user access validation code whether to honor this flag.

These keys may only be present if they have a non-default value:

• external_match_tag: the value of "External match tag" as set in the "Publication details" view of Editions Author. This is a free-form string that your website can use to implement custom issue sorting— it is not interpreted by Richie systems. If a value has not been set, the key will not be present in the feed.

• featured_until: a timestamp in the same format as published_at which indicates the time until when the issue should be shown as "featured". The field is only present if the "Featured until" value is set in the "Publication details" view of Editions Author.

Using the issue cover

The master_cover dictionary will contain an URL for a scalable cover thumbnail. The supported keys within the cover dictionary are as follows (your code must ignore keys not listed here):

• height and width: the height and the width of the image, respectively.
• url: the URL of the cover thumbnail.

This image is scalable, meaning that you can manipulate the URL to have the Richie image server deliver any size image (up to the maximum size given by height and width) to your users. This means that you do not need to download and scale image on your server for serving on your site: instead you only need to append a query string to the original URL and scaling will be handled transparently.

Note that you should always add scaling parameters to the URL, as the default image may be very large.

Scaling the master cover thumbnail

To scale the master cover thumbnail, add a query string to the supplied URL as in the following example:

https://data.richie.app/editions-eu-images/issue/f/1/1/issue_f1148aa3-90ff-4a5d-8639-8ee2bd71ca43_issue/master_preview_master_cover.png?width=300&height=400

By adding the width and height parameters as a query string, the Richie image server will supply an image scaled to fit the specified bounding box (size is specified in pixels); in the case of the example, this bounding box will have the size 300 x 400 pixels.

If you wish to avoid having the image fit to a bounding box and instead specify exact dimensions, add the mode=stretch parameter to the query string as follows:

https://data.richie.app/editions-eu-images/issue/f/1/1/issue_f1148aa3-90ff-4a5d-8639-8ee2bd71ca43_issue/master_preview_master_cover.png?width=300&height=400&mode=stretch

The resulting image will be scaled to exactly 300 x 400 pixels.

Index revalidation and polling

After you have downloaded the index_v2.json, your code should always store the value of the Etag response header. In subsequent requests, your code should send the previous value of the Etag header in the If-None-Match request header. The Richie server will return a not-modified HTTP status if the index_v2.json has not changed since your last request; at this point your code does not need to take any further action. If the index_v2.json has changed, it will returned in full; your code should reprocess it.

Your code may poll index_v2.json at most every 60 seconds (1 minute) per one of your backend servers. If for some reason you are not able to implement modification checking as described above and need to request the complete index_v2.json every time, your code may do this at most every 900 seconds (15 minutes) in total.

Richie servers may apply rate limiting to requests that exceed the above limits. Note that if you are running multiple backend servers for your website (i.e. for redundancy) all of which download index_v2.json, the If-None-Match polling limit is per server, but the full-data polling limit is for all of your servers.

index_v2.json may not be requested directly by end-users (i.e. by in-browser Javascript). It must be only used by your backend server(s).

Latest issue index

If you wish to show only the latest issue of your product(s) on your website, you may use the latest_v2.json index file. The URL for this index is https://<hostname>/_data/latest_v2.json. The format of this file is nearly identical to the format of index_v2.json, as seen below:

{
  "issues": {
    "example-organization/example-product": { ... }
  }
}

The only difference is that instead of an array of issues under each product, a dictionary for the latest issue by publication date is returned. The format of the issue dictionary is identical to the one described above.

latest_v2.json may be requested directly by end-users (i.e. by in-browser Javascript). For example, you may implement the dynamic part of your website entirely in Javascript by accessing latest_v2.json using XMLHttpRequest and rendering the issue cover thumbnail and link in browser-side code.

Ranged issue indexes

Index files with only a limited range of newest issues are available as options:

• https://<hostname>/_data/index_v2_<days>.json contains issues published in the last days days. As with index.json, these files are not directly accessible from browsers.
• https://<hostname>/_data/latest_v2_<n>.json contains the latest n issues for each product. As with latest_v2.json, these files may be requested directly by browsers.

The values for days and/or n must be selected in advance. Currently no limited indexes are generated by default. If your application requires either version please request a suitable set of values from Richie. Especially when accessing indexes from a browser, file sizes should be kept small to improve site responsiveness.

latest_v2_<n>.json is recommended for new applications, and may also be used to implement backend-less (client-based rendering) product sites with richer issue views than is possible with the single-issue latest_v2.json.

index_v2_<days>.json is useful primarily with traditional server-based rendering when your backend architecture is not able to process full-size index files due to database or processing capacity constraints.

Version 1 index files

Index files using the deprecated version 1 data format are available as index.json and latest.json. These files will remain available for existing users, but should not be used for new applications.