Noteflight Server API Developers' Guide

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

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.

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.

Noteflight Launch API

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).

Noteflight REST API

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.
For example, this JSON response:
{ count: 2, values: ["a", "b"] }
would be represented as follows in XML:
<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."}]}

Server API Methods

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:

Name Type Req'd Description
user_id string no The unique hexadecimal ID of the user whose scores are to be listed. Defaults to invoking user
order string no Sort order of returned scores; choice of "most_recent", "title", "composer", "favorites". Default value is most_recent.
max_count integer no Maximum number of results that will be returned. Default value is 100, which is also the largest allowed value.
start_index integer no Starting index of the first returned result. Default value is 0.

Response Object:

Property Value Type Description
count integer The total number of scores that can be listed for this user.
remaining integer The number of scores following the last score returned in this response, or zero if none remain.
scores Array of score objects Data describing the returned list of scores.

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:

Name Type Req'd Description
user_id string no The unique hexadecimal ID of the user whose scores are to be listed. Defaults to invoking user
order string no Sort order of returned scores; choice of "most_recent", "title", "composer", "favorites". Default value is most_recent.
max_count integer no Maximum number of results that will be returned. Default value is 100, which is also the largest allowed value.
start_index integer no Starting index of the first returned result. Default value is 0.
query string no Substring matching filter applied to returned scores.

Response Object:

Property Value Type Description
count integer The total number of scores that can be listed for this user.
remaining integer The number of scores following the last score returned in this response, or zero if none remain.
scores Array of score objects Data describing the returned list of scores.

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:

Name Type Req'd Description
user_id string no The unique hexadecimal ID of the user whose scores are to be listed. Defaults to invoking user

Response Object:

Property Value Type Description
private_scores_count integer The total number of private scores for this user.
public_scores_count integer The total number of public, searchable scores for this user.
favorites_count integer The total number of scores faved by this user.
shared_scores_count integer The total number of others' scores shared privately with this user.
archived_scores_count integer The total number of archived scores for this user following an account downgrade.

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:

Name Type Req'd Description
user_id string no The unique hexadecimal ID of the user whose scores are to be listed. Defaults to invoking user

Response Object:

Property Value Type Description
collections Array of collection objects The set of private score collections for this user.

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:

Name Type Req'd Description
user_id string no The unique hexadecimal ID of the user whose communities are to be listed. Defaults to invoking user

Response Object:

Property Value Type Description
communities Array of community objects The set of community to which this user belongs.
active_scc_count integer The number of managed communities that this user has created.
creatable_scc_count integer The number of additional managed communities that this user can create.

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:

Name Type Req'd Description
sso_user_id string yes The unique, opaque ID of a user in the Noteflight tool consumer.
sso_username string yes A human-readable name to be used for this user within Noteflight.
sso_user_role string yes One of these values:
  • admin
  • instructor
  • student

Response Object:

Property Value Type Description
user user object Data describing the user.

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:

Name Type Req'd Description
score_id string yes The unique hexadecimal ID of the score.

Response Object:

Property Value Type Description
score score object Data describing the score.

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:

Name Type Req'd Description
score_id string yes The unique hexadecimal ID of the score.
version string no The version number of the score to access. If omitted defaults to the latest version available.
community_id string no The database ID of the community containing the score (defaults to the community for the site whose API is being accessed). This parameter may only be provided if the API user has general content access

Response: The XML content of the score.

score/change_metadata

Description: Changes the metadata 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:

Name Type Req'd Description
score_id string yes The unique hexadecimal ID of the score.
title string no The updated title of the score
composer string no The updated composer of the score
description string no An updated description of the score
tags string no An updated tag list associated with the score
template boolean no Updated flag indicating that the score is an activity template
searchable boolean no Updated flag indicating the score is publicly searchable and browseable.
everyone_role Choice of "none", "reader", "reviewer", "coauthor" no Updated sharing role to be assigned to the community at large.

Response Object:

Property Value Type Description
score score object Data describing the score following application of the requested changes.

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:

Name Type Req'd Description
score_id string yes The unique hexadecimal ID of the score to be copied.
score_hostname string no The Noteflight hostname of the community containing the score to be copied; if omitted, the community referenced by the API call is assumed.
user_id string yes The unique hexadecimal ID of the user into whose account the score is to be copied.
clone_permissions boolean yes If true, indicates that the score's sharing permissions (other than to specific users) should be copied to the new score.
clone_score_id boolean yes If true, indicates that the score's hexadecimal external ID should be copied to the new score. May not be used for copies within the same community as this would lead to conflicting IDs.

Response Object:

Property Value Type Description
score score object Data describing the score.

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:

Name Type Req'd Description
query string yes A search query, which consists of terms taking a number of forms:
  • A single keyword that can match a word in a score's title, composer, author, tags or description
  • A space-delimited list of terms that are implicitly ANDed.
  • A list of terms joined by the operator OR.
  • A parenthesized term.
  • A keyword type followed by a colon (:) and a term, e.g. composer:Bach or composer:(Miles OR Coltrane). Keyword types include title, composer, tags, username, or description.
order string no Sort order of returned scores; choice of "most_recent", "title", "composer", "favorites". Default value is most_recent.
max_count integer no Maximum number of results that will be returned. Default value is 100, which is also the largest allowed value.
start_index integer no Starting index of the first returned result. Default value is 0.

Response Object:

Property Value Type Description
count integer The total number of scores that can be listed for this user.
remaining integer The number of scores following the last score returned in this response, or zero if none remain.
scores Array of score objects Data describing the returned list of scores.

members/data

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

Request Parameters:

Name Type Req'd Description
user_id string yes The unique hexadecimal ID of the user.

Response Object:

Property Value Type Description
user user object Data describing the user, including the optional profile 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:

Name Type Req'd Description
name string yes The displayable name of the community.
description string yes The textual description of the community.
hostname string yes The Internet host name of the community. The API call does not actually create this host name on the Internet; it must already exist within DNS and resolve to a Noteflight server.
inherit_domain_proxy boolean no Indicates whether SSO proxy authentication for this community is specified in the parent domain. Default is false.
proxy_url string no A proxy authentication URL to which requests with no established session should be redirected. The web service at this URL must implement Noteflight's Single Sign On authentication and signing protocol.
proxy_paramname string no The parameter used to pass the original request URL in redirects to the above proxy authentication URL.
post_logout_url string no An optional URL to which Notefight should redirect upon logout.
community_url string no An optional URL for the parent community's own site.
allow_anonymous_view boolean no If true, indicates that shared scores within the new community will be visible outside that community.
enable_browse_and_search boolean no If true, indicates that scores can be made searchable within the community. Defaults to true.
allow_view_members boolean no If true, indicates that member lists can be viewed by more than just community admins. Defaults to true.
allow_new_groups boolean no If true, indicates that groups can be created within the community. Defaults to true.

Response Object:

Property Value Type Description
community community object Data describing the newly created community.

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:

Property Value Type Description
communities Array of community objects The domain's communities.

Data Types Returned by API calls

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.

Key Value Type Description
title string The title of the score
external_id string Unique hexadecimal ID of the score to be used in API calls, etc.
composer string The composer of the score
description string A description of the score
tags string A tag list associated with the score
template boolean Flag indicating that the score is an activity template
searchable boolean Flag indicating the score is publicly searchable and browseable.
saved boolean Flag indicating the score has been saved at least once (false for a brand-new, unsaved score).
premium_instruments boolean Flag indicating that the score makes use of the premium-level instrument set.
everyone_role Choice of "none", "reader", "reviewer", "coauthor" The level of public sharing associated with this score
author user object Author of the score
view_score_uri string Absolute URI of a human-readable view of the score
score_data_uri string Absolute URI of score/data API request for this score's detailed information
created milliseconds since 1/1/1970 Timestamp for this document's creation
updated milliseconds since 1/1/1970 Timestamp of last update of this document
comments_count integer Number of comments attached to this document
favorites_count integer Number of favorites for this document
collections Array of collection objects. list of collection IDs for this score (only provided for members/private_scores)

user

This object describes a Noteflight user.

Key Value Type Description
username string Public username of the user
external_id string unique hexadecimal ID of the user to be used in API calls, etc.
homepage_uri string Absolute URI of user-readable member page
avatar_uri string Absolute URI of member's avatar
premium_member boolean Flag indicating that member has the premium level of service.
identified boolean Flag indicating that member has been identified and has access to identity-based features of the site.
created milliseconds since 1/1/1970 Timestamp for this user's creation
profile Profile data (see below) Descriptive information about this user. Only returned for some service calls.

profile

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

about_me string User's description of self country string User's self-reported country location string User's geographical location within country (unstructured text) facebook_username string Facebook username twitter_username string Twitter username

community

This object describes a Noteflight community.

Key Value Type Description
hostname string Internet host name of the community
name string displayable name for the community
description string displayable textual description for the community
managed boolean if true, indicates that the community is managed by its admin in a self-contained way
active boolean if true, indicates that the community is currently active (as opposed to an managed community that is inactivated after its owner's account is downgraded)

collection

This object describes a Noteflight score collection.

Key Value Type Description
name string Display name of the collection
id string unique ID of the collection

Error codes Returned by API calls

Theis section describes the error codes returned by API calls.

Error Code Description
apiAccessDenied The user who invoked and signed the API request does not have access to this API method.
authenticationRequired The request signature or invoking user was invalid.
communityNotFound A community could not be found given the identifying information available
emailAlreadyExists An email address for registration was already taken by an existing user
hostnameAlreadyExists A hostname for some community was already taken by an existing community
indexOutOfRange A starting index value for a query was negative or greater than the number of possible results.
invalidParameter A parameter was invalid. The accompanying message will provide user-readable information on the validation failure.
queryTooLarge The number of requested query results exceeded the maxium
requiredParameterMissing A required parameter was not provided to the API method. The accompanying message will identify the missing parameter.
scoreAlreadyExists The ID of some copied or newly created score was already taken by an existing score
scoreNotFound A score could not be located with the given unique ID.
scoreNotReadable The requested score is not accessible to the caller of the API.
userInvalidState The given user is not in the correct state for this API method to be performed successfully.
userNotFound A user could not be located with the given unique ID.
usernameAlreadyExists A username for registration was already taken by an existing user

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

Noteflight® is a registered trademark of Noteflight, LLC.