Your HarmonySite has an API - an Application Programming Interface. That means that a programmer can connect to your HarmonySite and read any of the information in its database. They may want to do this so that they can develop their own computer program or smartphone app that will benefit your organisation in some way.


Please note that this API is fully secure.  The API will not even be enabled on your HarmonySite unless you tell us you want it enabled.  Moreover, any programmer attempting to access this data must provide a valid username and password - from your logins database.


Note that we will not enable the API for your HarmonySite unless your HarmonySite has an SSL security certificate.


If you are not a programmer, or have no need for any known program or smartphone app to connect to your HarmonySite's database, then you can ignore the rest of this document.


Enabling the API for your HarmonySite


If you would like the API enabled for your HarmonySite, then please do the following...


  1. If your site does not already have an SSL security certificate, please email admin@harmonysite.com and ask us to install one.  There is a nominal fee for doing so:  www.harmonysite.com/pricing 
  2. Please email admin@harmonysite.com and ask us to enable the API. We will only accept requests from the person we have on file as the main contact for your organisation. Please include the reason that you would like the API enabled on your site (such as the name of the program/app or developer that will be connecting to it).


Once the API has been enabled, it will be found at an address like https://www.mygroup.com/api

(note the "api" on the end of the URL).


Using the API


In broad terms, the API works like this:  You specify a URL containing the details of the information you'd like returned, and then that information is returned, either in XML or JSON format (your choice).  An example of such a URL might be...


https://www.mygroup.com/api?endpoint=browse&token=ABC&table=members&n=20


This particular query would return you the first 20 members from the member database ("first" in terms of their alphabetical order, sorted by last name).


Authorising


Before such a query can be run, an initial request to the API must be made establishing a secure session, and providing the username and password of a known member in that group.  That request might look like this...


https://www.mygroup.com/api?endpoint=authorise&username=fred&password=123

(note the endpoint = authorise part of the URL)


If the username and password can be validated, then a "token" is returned.  This token must be provided as part of the URL in every subsequent API request (except "authorise" requests).


Note that this token is based on the server's internal "session ID".  If your program/app cannot maintain a "session" internally (like a web-browser can), then this API might not work for you as is.  Email admin@harmonysite.com and we'll sort something out for you.


Next, you use this token to make the next API request.  The most important component of an API request URL is the "endpoint".  Currently the HarmonySite API offers only ONE endpoint (besides the authorise endpoint):  browse


Endpoint: browse


The browse endpoint is used to retrieve database records from database tables. For example, you might want to retrieve...


  • All the members in the database
  • All members that live in California
  • All membership records that are "Active"
  • All songs in the current repertoire


So you'll need to know the following...


  • The name of the table you want to retrieve data from Required
  • How many records you want (as a maximum, for paging purposes)
  • The starting index number (for paging purposes)
  • Any "filtering" options (e.g. State = California, or ID = 12345)
  • The name of the field to sort on
  • Whether sorting is in ascending or descending order
  • Whether you want XML or JSON data
  • Whether you want "raw" data or nicely formatted data


The request may then look like this...


https://www.mygroup.com/api?endpoint=browse&token=ABC&table=members&n=20

(note the endpoint = browse part of the URL)


Note that if you want a particular database record, and you know that record's "id", then you can specify id=value as one of the filter options in the URL.


General notes

  • This endpoint can optionally also return the table's structure.  This structure includes the list of fields, their data 
  • All parameter names and field names (for filtering and sorting) are CASE-SENSITIVE!
  • The availability of records will be based on the privileges of the username/password that you have logged in with.   So if you want access to the entire database, make sure that you log in with the username and password of someone who has "Webmaster Access"


Endpoint: config


The config endpoint is used to retrieve the configuration of this particular HarmonySite.


There are quite literally hundreds of configuration options in any HarmonySite.  Not all of them are returned via this API call.  If you want another one added, please contact us.


Full API Specification


Rather than specify the details of every API parameter, along with the details of every field of every database table, we have prepared a page in your HarmonySite where you can try out the API, by constructing a URL in a user-friendly manner.  ALL the details you need are listed in this page.  To find it...


  1. Log into your HarmonySite with "Webmaster Access"
  2. Visit the Admin Dashboard
  3. On the Website Content line, click the link called Test the HarmonySite API


Useful Tools


Jon Davies, from the London Welsh Rugby Club Choir, has created a Python interface for our API, and has graciously made it available for any programmer to use.  He has provided full instructions for its use, here:  https://www.lwrcc.uk/dbpage.php?pg=blogusingapi