Noteflight Server API Developers' Guide

Noteflight® is a registered trademark of Noteflight, LLC.

Introduction

The Noteflight website supports a number of ways for developers to make use of Noteflight in creative ways, extending its functionality.

The Noteflight Launch API allows developers of other websites to launch Noteflight with links that perform various useful functions, for example to create a new score for a user that imports MusicXML content from an external document.

The Noteflight REST API allows developers to request information from the server and to perform various actions on the server side. All API requests are signed with a unique key that identifies an authorized Noteflight account; the request is then performed on behalf of that user. There are two access levels of API usage which are separately authorized: query and domain.

• The query level of API allows users to request information from the server. In general this information is data that is available on an interactive basis to any registered Noteflight user, such as score listings, search results, user information, and so on.
• The domain level of API allows domain administrators to create and populate new communities in a Noteflight domain (which is a group of related sites administered by the same entity, not an Internet domain). It also allows querying of private information such as metadata for unshared member scores.

Terms Of Use

The Noteflight features in this document are covered by separate Terms of Use. All usage of these features should be by direct arrangement between the user and Noteflight, LLC.

Noteflight, LLC reserves the right to change the API features described in this document at any time, without prior notice.

Importing an External Document

The link /scores/create, in conjunction with the query argument scoreTemplateURL, can be used to launch the Noteflight Score Editor on a new score in the currently signed in user's account. The score is imported by the Score Editor from the given URL as soon as the editor launches. If the user is not signed in, they will be presented with the opportunity to register or sign in prior to the import. Note that the user must have the capacity in their account to actually create and save the score.

For example, this URL would have the effect of importing the document at https://mymusicapp.com/scores/323487/score.xml into a new Noteflight score: (note the query argument escaping)

    https://www.noteflight.com/scores/create?scoreTemplateURL=https%3A%2F%2Fmymusicapp.com%2Fscores%2F323487%2Fscore.xml

Scores in MusicXML and Noteflight XML may be imported in this way.

You may also import MIDI scores by adding the scoreImportType query argument and setting its value to 'midi'.

    https://www.noteflight.com/scores/create?scoreTemplateURL=https%3A%2F%2Fmydomain.com%2Fscore&scoreImportType=midi

The score is imported by the Noteflight Score Editor client in the browser, not by the server. This requires that the HTTP response for the external score content include one or more CORS headers permitting the Score Editor to access the loaded document. Specifically, Access-Control-Allow-Origin is needed with the value * or www.noteflight.com (or other private Noteflight website hostname).

Request Structure

All API requests must be HTTP POSTs with a content type of application/x-www-form-urlencoded, whose body consists of escaped key=value pairs joined by ampersands for the arguments associated with the request method. In other words, the request structure is identical to that in a typical HTML form submit.

The request path consists of the prefix /api/1.0/ followed by the name of the API method being invoked. For example, to invoke the member_scores method, the full request URL would be https://www.noteflight.com/api/1.0/member_scores.

The request hostname determines the Noteflight site or "community" against which the API request will be executed. All APIs reference a specific community containing users, scores, and so forth; there are no API calls that pertain to multiple communities. So the hostname www.noteflight.com references the public Noteflight community; if one is working against some other community, its particular hostname must be used in the request.

Request Signing

All Noteflight API requests must be signed using a secret key that Noteflight has previously issued the caller. Keys are associated with authorized Noteflight user accounts, and API requests are performed on behalf of these accounts.

The OAuth 1.0 Specification is used to create authenticated API requests, using the HMAC-SHA1 method as described in section 3.4.2. The signing process attaches a special Authorizationheader to a request which includes a cryptographic digest of the request's information along with a timestamp, the caller's Noteflight account ID and the caller's secret key.

API requests are signed with so-called "2-legged OAuth". This is a simplified variation of the OAuth protocol. OAuth normally requires a "3-legged" process in which the consumer (you) first obtains an access token from the provider (Noteflight), then performs a second request in which the consumer employs this access token to perform some function. In the 2-legged variation, the access token is not required which cuts down the process to a single signed request. The signing of requests is exactly as detailed in the specification, except that oauth_token parameter is omitted from the parameters and signature base string, as allowed in section 3.1 of the specification. This in turn causes the token secret to be taken as the empty string for signature purposes.

Here is some sample Ruby on Rails code that illustrates the overall flow of the technique for forming a request:

require 'oauth'

# make the consumer out of your secret and key
consumer_key = "bf6978128374098ad310bdeaa327a06a33f95128"  # hex ID of API user
consumer_secret = "1+p0VRglFFNzRJYX77Gsz6hn/v20mh93ki43amCayIg="
consumer = OAuth::Consumer.new(consumer_key, consumer_secret,
                               :site => "https://www.noteflight.com")

# make a 2-legged access token directly from the Consumer object
access_token = OAuth::AccessToken.new consumer

# make a signed request and print out the result
member_id = "fb1cabaa874b1b91d1f77969023022cfa6b6a6a4"  # hex ID of member whose scores to be listed
puts access_token.post("/api/1.0/members/scores",
                       { :user_id => member_id },
                       { "Accept" => 'application/xml' }).body

The actual content of the above request would look something like this (line breaks and indentation supplied for clarity):

POST /api/1.0/members/scores HTTP/1.1
Host: www.noteflight.com
Accept: application/xml
User-Agent: Mozilla/5.0
Authorization: OAuth oauth_body_hash="2jmj7l5rSw0yVb%2FvlWAYkK%2FYBwk%3D",
                     oauth_consumer_key="bf6978128374098ad310bdeaa327a06a33f95128",
                     oauth_nonce="z6nLUFt6eNeleUm3k0catUXNv2CPKY0q5OfiskgWw",
                     oauth_signature="6ntfKo%2B4RZLjpMh%2BEasWgAU5q0g%3D",
                     oauth_signature_method="HMAC-SHA1",
                     oauth_timestamp="1277218172",
                     oauth_version="1.0"
Content-Length: 48

user_id=fb1cabaa874b1b91d1f77969023022cfa6b6a6a4

Response Formats

Except where noted, all API responses can be obtained in either JSON or XML format. The HTTP Accept: header is consulted for an optional MIME type of the response; if omitted, the default response format is XML.

The JSON format is the most straightforward to describe, and will generally be used in this document to specify the data structures returned by the API. In general such a response consists of a set of JavaScript objects containing properties, i.e. key-value pairs. A property of an object may be either a JavaScript scalar data type, a nested object with its own set of properties, an array of scalars or an array of objects. Nested arrays are disallowed by API convention.

The type of an object value generally corresponds to the name of its property. Object types in the API are documented in a section at the end of this specification.

The XML format is derived from the JSON format as follows:

1. The top level JSON object in the response is always a <response> root element in the XML response.
2. A property holding an array of objects is replaced by a single container element named for the plural form of the property, that has a set of nested elements named the same as the singular form of the property.

{ count: 2, values: ["a", "b"] }

<response>
  <count>2</count>
  <values>
    <value>a</value>
    <value>b</value>
  </values>
</response>

Error Indications

An API call that encounters an error will always contain an errors value in the response, which is a list of error objects. Each of these objects contains a code (a programmatic, stable constant that represents the nature of the error) and a message (a user readable message). The HTTP status code for an error response is always 400 (Bad Request).

Thus, callers must always look for a 400 status code, then examine the top-level response for the errors list and handle these accordingly. Here is an example error response in JSON:

{"errors": [{"code": "authenticationRequired",
             "message": "Authentication is required to use the Noteflight API."}]}

A reference of the specific API methods follows. Note that each method must be invoked by a request that prepends the standard URL prefix and is properly signed as described above.

greetings

Description: Returns a test result for API verification purposes.

Parameters: None.

Return Value: An object with a version property containing the API version, and a greetings property. The greetings object is an array; each element of the array is an object with a single string property. Each property name and its value form a greeting to the caller.

Errors: None.

members/scores

Description: Returns a set of public, searchable scores belonging to a Noteflight user. This list is equivalent to what would be seen on the user's public member page.

Request Parameters:

Response Object:

members/private_scores

Description: Returns a set of all the scores belonging to a Noteflight user including both public and private, searchable and non-searchable. This list is equivalent to what would be seen on the user's private member page.

Requires the caller to possess the domain level of API usage, or to be the same as the Noteflight user whose scores are being queried.

Request Parameters:

Response Object:

members/private_statistics

Description: Returns private statistics for a user. This list is equivalent to what would be seen on the user's private member page.

Requires the caller to possess the domain level of API usage, or to be the same as the Noteflight user whose scores are being queried.

Request Parameters:

Response Object:

members/private_collections

Description: Returns the list of private score collections for a user. This list is equivalent to what would be seen on the user's private member page.

Requires the caller to possess the domain level of API usage, or to be the same as the Noteflight user whose scores are being queried.

Request Parameters:

Response Object:

members/communities

Description: Returns the list of communities to which a user belongs.

Requires the caller to possess the domain level of API usage, or to be the same as the Noteflight user whose scores are being queried.

Request Parameters:

Response Object:

members/sso

Description: Either creates or finds a Noteflight user corresponding to a set of Single Sign On (SSO) parameters that are used by Noteflight's proxy or BasicLTI authentication schemes. If the sso_user_id of the user has never been seen before, then a user with that SSO ID is created in the community being called, using the role and username request parameters to initialize it. If the sso_user_id has been seen, the user is looked up and their role and username are updated. In either case Noteflight returns information describing the user entity.

This request is only valid in communities that are enabled for SSO, and can only be performed by an API caller enabled for domain calls.

Request Parameters:

Response Object:

score/data

Description: Returns an object describing a single score, which must be accessible to the API user.

If the API user is enabled for domain operations, then any score may be queried regardless of accessibility.

Request Parameters:

Response Object:

score/content

Description: Returns the XML content of a single score, which must be accessible to the API user unless the user is specially enabled for general content access.

Request Parameters:

Response: The XML content of the score.

scores/sharing

Description: Changes the sharing permissions for a single score. Supplying any of the optional parameters to this operation will cause the corresponding attribute of the score metadata to be updated.

The API user must be enabled for domain operations to perform this operation.

Request Parameters:

Response Object:

score/copy

Description: Copies a single score to a destination user account within the community referenced by the API call. The score may optionally come from a different community. The copy operation may choose to preserve the permissions and (if copying to a different communities) the unique external ID of the original score.

This operation is restricted to API users enabled for domain operations in both the source and destination communities of the copy operation.

Request Parameters:

Response Object:

search/scores

Description: Returns a set of public, searchable scores that match a search query. This list is equivalent to what would be seen on a Noteflight Search results page.

Request Parameters:

Response Object:

members/data

Description: Returns an object describing a single member of the community. User profile information is included in the response.

Request Parameters:

Response Object:

communities/create

Description: Creates a new community in the same domain as the community referenced by the API call. The new community has the same basic characteristics as the API-referenced one in terms of score limits, SSO, etc., but its specifics may be provided as parameters to this call. Information on the new community is returned if the call is successful.

This operation is restricted to API users enabled for domain operations.

When the new community is created, the API caller is automatically added to the community as a non-SSO administrative user and enabled for domain operations. This allows any caller who creates a new community to proceed to issue domain-level API calls against that community.

Request Parameters:

Response Object:

communities/domain

Description: Queries all communities in the domain of the community referenced by the API call.

This operation is restricted to API users enabled for domain operations.

Request Parameters: None

Response Object:

These objects describe the basic data types returned by API calls describing scores, users and other objects. They are returned by a variety of different methods.

score

This object describes a Noteflight score document.

user

This object describes a Noteflight user.

profile

An optional object attached to users in circumstances where detailed information is required.

community

This object describes a Noteflight community.

collection

This object describes a Noteflight score collection.

Theis section describes the error codes returned by API calls.

© Copyright 2010- Noteflight, LLC. All Rights Reserved.

Noteflight® is a registered trademark of Noteflight, LLC.