Migrating from SCP 1.x

Summary of changes

Infrastructural

Feature SCP 1.x SCP 2.x Details
Host publishing.sibelius.com api.us-east-1.everywhere.avid.com SCP is now fully integrated into the Avid Everywhere platform.
Root URL https://publishing.sibelius.com/services/avid.sibelius.publishing https://api.us-east-1.everywhere.avid.com/apis/avid.sibelius.publishing;realm=global;version=2/ Root URL now parametrized by version and realm

API

Feature SCP 1.x SCP 2.x Details
Static preview API Deprecated scores/:scoreId/preview no longer supported.
Publisher IDs Deprecated No longer required since /preview route deprecated.
Custom scoreIds Required Optional Specification of scoreId no longer required.
Purchase API Deprecated scores/:scoreId/purchase merged into GET scores/:scoreId/view. Transaction tracking model removed.
JPEG previews Deprecated All scores are now in SVG format
Score status Deprecated Replaced by GET scores/:scoreId

Migration guide

Update root URL

Cloud Publishing is now served from api.us-east-1.everywhere.avid.com.

The root URL of the API is now https://api.us-east-1.everywhere.avid.com/apis/avid.sibelius.publishing;realm=global;version=2/. You'll notice that the URL is now parametrized with version and realm. These allow us to run multiple versions of Cloud Publishing concurrently in multiple regions. For now, the values are always 2 and global respectively.

Scores root URL

  • SCP 1.x: /publishers/:publisherId/scores
  • SCP 2.0: /scores

Because the preview route is now deprecated (see below), there is no longer any need for individually assigned publisher IDs. In turn, there is no need for the publisher ID to form part of the URL, so it has been removed, thus simplifying the API.

Static preview deprecated

The static scores/:scoreId/preview route is now deprecated for two reasons:

  • Unauthenticated, static URLs represent a security risk
  • Preview route required the assignment of unique publisher IDs that have to be managed manually across multiple publishers

Instead, you should simply use the GET /scores/:scoreId/view route every time you wish to display a score. You may limit the number of pages using the pages parameter (thus mimicking the behaviour of the old preview route) like so:

1
2
3
4
5
GET /apis/avid.sibelius.publishing;version=2;realm=global/scores/:scoreId/view

{
pages: "1"
}

Custom score IDs

In SCP 1.x you always had to specify a custom scoreId when publishing a score. This parameter is now optional.

scoreId now effectively functions as an alias to your score that you can use to reference it in the future. It must be unique.

Every time you publish a score, it is automatically assigned a unique ID (a UUID) which we use to manage the score internally.

SCP 2.0 allows you to refer to a score either by custom scoreId or id, so if you're already using custom score IDs then SCP 2.0 should continue to behave as previously.

Here are two examples demonstrating the two approaches:

Publishing and referring to a score without a custom score ID

  1. Publish the score, omitting the scoreId parameter:

     POST /apis/avid.sibelius.publishing;version=2;realm=global/scores
     
     {
       "scoreUrl": "https://www.sibelius.com/my-great-score.sib"
     }
    
  2. Your newly published score is returned to you, with an id property:

     HTTP/1.1 200 OK
     
     {
       "score": {
         …
         "id": "c96db2ba-1d1f-4aa2-82fb-a2cd1848097b"
       }
     }
    
  3. You may now refer to the published score by ID. For example, when requesting a view

     
    1
    GET /apis/avid.sibelius.publishing;version=2;realm=global/scores/c96db2ba-1d1f-4aa2-82fb-a2cd1848097b/view

Publishing and referring to a score with a custom score ID

  1. Publish the score, specifying a scoreId parameter:

     POST /apis/avid.sibelius.publishing;version=2;realm=global/scores
     
     {
       "scoreUrl": "https://www.sibelius.com/my-great-score.sib",
       "scoreId": "myGreatScore"
     }
    
  2. Your newly published score is returned to you, with an id property and a score.publisher.scoreId property:

     HTTP/1.1 200 OK
     
     {
       "score": {
         "publisher": {
           "scoreId": "myGreatScore"
         },
         …
         "id": "c96db2ba-1d1f-4aa2-82fb-a2cd1848097b"
       }
     }
    
  3. You may now refer to the published score by either its id or custom scoreId:

  • By custom scoreId:

    1
    GET /apis/avid.sibelius.publishing;version=2;realm=global/scores/myGreatScore/view
  • By id:

    1
    GET /apis/avid.sibelius.publishing;version=2;realm=global/scores/c96db2ba-1d1f-4aa2-82fb-a2cd1848097b/view

Purchases and transactions

Transactions are no longer tracked in SCP 2.0, allowing us to support a wider variety of publisher business models and also allowing us to simplify the API. The old scores/:scoreId/purchase resource is now depracated and merged into the GET scores/:scoreId/view resource.

We no longer make a distinction between pre-purchase and post-purchase scores as we did in SCP 1.x - instead, we're providing more parameters to allow you to customise each view to your needs.

The newly enhanced GET scores/:scoreId/view now accepts a pages parameter, allowing you to specify the number of pages you want to display to your customer. This allows you, for example, to show only the first page of your score to your customer before they have purchased it (and in fact, the pages parameter now accepts page ranges allowing you to flexibly display excerpts of your score to your customer).

GET scores/:scoreId/view now accepts a printable parameter which works regardless of the pages parameter. This allows you to allow your customer to try out printing with an excerpt of your score - something that wasn't previously possible.

Views expire after 2 hours by default. You may customise this using either the expiresIn or the expiresAt parameters