GraphQL API v2

Migrates your newsletters to GraphQL API v2. 🚀

Why GraphQL API v2

The v1 was designed when Sirius GraphQL API didn't exist. Today it is easier for a developer to use the same API everywhere.

Sirius GraphQL Newsletter API v2 is an extension of Sirius GraphQL API. It means that everything accessible on the Sirius GraphQL API is accessible in addition to some special fields like metadata, articlesArea or textArea.

Migrate from v1

This guide will help you migrate your newsletters from v1 to v2.

Global IDs

Every id are now global IDs, for example, @seed directives now accept global IDs instead of numeric ids.

List of articles

To create a list of articles available in the edition interface, you must now use editionListBlock.

API v1

{
  articlesArea(name: "area", limit: 1) {
    title
    image(width: 580, height: 387, aspectRatio: ratio_3x2) {
      url
      alt
      width
      height
    }
  }
}

API v2

About feature image, in v2, you have to request URL and caption defined in the article and eventually fallback on the one defined in the image. If you need an aspect ratio, you can find the aspectRatioKey in Sirius Aspect Ratios admin.

{
  editionListBlock(key: "area", softLimit: 1, accepts: [articles]) {
    id
    items {
      id
      ... on ArticleListItem {
        id
        article {
          title
          featureImage {
            image {
              caption
            }
            caption
            url(width: 580, height: 387, aspectRatioKey: "3:2")
          }
        }
      }
    }
  }
}

ℹ️ Use @listBlockOptions(warnIfUnpublished: false) directive instead of @areaOptions(warnIfUnpublished: false) to disable warning if an unpublished content is dropped in the list block

Publication based query

API v1

query Query($digitalPublicationId: Int! = 41) {
  digitalPublication(id: $digitalPublicationId) {
    date
    articles {
      title
    }
  }
}

API v2

query Query($editionId: ID! = "bG9jYWw6UHVibGljYXRpb246Mw==") {
  node(id: $editionId) {
    ... on PeriodicalEdition {
      date
      blocks {
        ... on ListBlock {
          items {
            ... on ArticleListItem {
              article {
                title
              }
            }
          }
        }
      }
    }
  }
}

Text field in newsletter edition

To create a text field reachable on the edition panel, you must now use editionTextBlock

API v1

{
  summary: textArea(name: "summary")
    @placeholder(value: "Bienvenue sur la newsletter...")
    @label(value: "Résumé")
    @hint(value: "Entête de la newsletter")
    @textAreaOptions(multiline: true)
}

API v2

{
  summary: editionTextBlock(key: "summary")
    @editionTextBlockOptions(
      label: "Résumé"
      placeholder: "Bienvenue sur la newsletter..."
      hint: "Entête de la newsletter"
      multiline: true
    )
}

Select articles from a rubric

To create a list of articles available in the rubric edition interface. Now, you must use tag.

API v1

{
  section(slug: "my-rubric") {
    articles(area:"area" limit: 6){
      id
      url
      title
      chapo
      #....
  }
}

API v2

{
  tag(key: "my-rubric") {
    ... on Rubric {
      id
      block(key: "area") {
        ... on ListBlock {
          items(limit: 6) {
            ... on ArticleListItem {
              article {
                id
                internalId
                url
                title
                chapo
                #...
              }
            }
          }
        }
      }
    }
  }
}

ℹ️ If you would like to query multiple rubrics, you can query rubrics with in operator. rubrics(where: { key: { in: ["a-tag", "another-tag"] } }){...}

Select articles by its main and/or narrow rubric

To obtain a list of articles with a specific narrow or header rubric. Now you must use articles query

API v1

{
  section(slug: "a-tag") {
    articles(limit: 16, header: true) {
      id
      title
      url
      chapo
    }
  }
}

API v2

ℹ️ Get rubric global id in admin panel

{
  articles(limit: 16, where: { mainTagId: { eq: "<A-Tag-Global-ID>" } }) {
    nodes {
      id
      internalId
      title
      url
      chapo
    }
  }
}

Alert based query

API v1

query AlertQuery($alertId: Int! = 123) {
  alert(id: $alertId) {
    id
    title
    text
    article {
      url
    }
  }
}

API v2

query ArticleBroadcastQuery($articleBroadcastId: ID! = "bG9jYWw6QWxlcnQ6MTIz") {
  node(id: $alertId) {
    id
    internalId
    ... on ArticleBroadcast {
      title
      text
      article {
        url
      }
    }
  }
}

query Twipe & Forecast

Nothing changes other than there are under newsletter field:

API v2

{
  newsletter {
    forecast {
      forecastTopConversionArticles(
        limit: 8
        where: { since: "7d", free: false }
      ) {
        id
        #...
      }
      forecastTopPageviewArticles(limit: 8, where: { publishedSince: "7d" }) {
        id
        # ...
      }
    }
  }
}

query NewsletterQuery(
  $editionToken: String! = "X"
  $publicationDate: Date! = "2022-11-22"
) {
  newsletter {
    twipe {
      contentPackages(
        editionToken: $editionToken
        publicationDate: $publicationDate
      ) {
        id
        # ...
      }
    }
  }
}