Skip to content

Latest commit

 

History

History
395 lines (347 loc) · 31.2 KB

README.md

File metadata and controls

395 lines (347 loc) · 31.2 KB
Raw

flat_api

FlatApi - the Ruby gem for the Flat API

The Flat API allows you to easily extend the abilities of the Flat Platform, with a wide range of use cases including the following:

  • Creating and importing new music scores using MusicXML, MIDI, Guitar Pro (GP3, GP4, GP5, GPX, GP), PowerTab, TuxGuitar and MuseScore files
  • Browsing, updating, copying, exporting the user's scores (for example in MP3, WAV or MIDI)
  • Managing educational resources with Flat for Education: creating & updating the organization accounts, the classes, rosters and assignments.

The Flat API is built on HTTP. Our API is RESTful It has predictable resource URLs. It returns HTTP response codes to indicate errors. It also accepts and returns JSON in the HTTP body. The schema of this API follows the OpenAPI Initiative (OAI) specification, you can use and work with compatible Swagger tools. This API features Cross-Origin Resource Sharing (CORS) implemented in compliance with W3C spec.

You can use your favorite HTTP/REST library for your programming language to use Flat's API. This specification and reference is available on Github.

Getting Started and learn more:

This SDK is automatically generated by the OpenAPI Generator project:

  • API version: 2.20.0
  • Package version: 0.3.0
  • Build package: org.openapitools.codegen.languages.RubyClientCodegen For more information, please visit https://flat.io/developers/docs/api/

Installation

Install from rubygem

gem install flat_api

Build a gem

To build the Ruby code into a gem:

gem build flat_api.gemspec

Then either install the gem locally:

gem install ./flat_api-0.3.0.gem

(for development, run gem install --dev ./flat_api-0.3.0.gem to install the development dependencies)

or publish the gem to a gem hosting service, e.g. RubyGems.

Finally add this to the Gemfile:

gem 'flat_api', '~> 0.3.0'

Install from Git

If the Ruby gem is hosted at a git repository: https://github.com/FlatIO/api-client-ruby, then add the following in the Gemfile:

gem 'flat_api', :git => 'https://github.com/FlatIO/api-client-ruby.git'

Include the Ruby code directly

Include the Ruby code directly using -I as follows:

ruby -Ilib script.rb

Getting Started

Please follow the installation procedure and then run the following code:

# Load the gem
require 'flat_api'

# Setup authorization
FlatApi.configure do |config|
  # Configure OAuth2 access token for authorization: OAuth2
  config.access_token = 'YOUR ACCESS TOKEN'
  # Configure a proc to get access tokens in lieu of the static access_token configuration
  config.access_token_getter = -> { 'YOUR TOKEN GETTER PROC' } 
end

api_instance = FlatApi::AccountApi.new
opts = {
  only_id: true # Boolean | Only return the user id
}

begin
  #Get current user account
  result = api_instance.get_authenticated_user(opts)
  p result
rescue FlatApi::ApiError => e
  puts "Exception when calling AccountApi->get_authenticated_user: #{e}"
end

Documentation for API Endpoints

All URIs are relative to https://api.flat.io/v2

Class Method HTTP request Description
FlatApi::AccountApi get_authenticated_user GET /me Get current user account
FlatApi::ClassApi activate_class POST /classes/{class}/activate Activate the class
FlatApi::ClassApi add_class_user PUT /classes/{class}/users/{user} Add a user to the class
FlatApi::ClassApi archive_assignment POST /classes/{class}/assignments/{assignment}/archive Archive the assignment
FlatApi::ClassApi archive_class POST /classes/{class}/archive Archive the class
FlatApi::ClassApi copy_assignment POST /classes/{class}/assignments/{assignment}/copy Copy an assignment
FlatApi::ClassApi create_class POST /classes Create a new class
FlatApi::ClassApi create_class_assignment POST /classes/{class}/assignments Assignment creation
FlatApi::ClassApi create_submission PUT /classes/{class}/assignments/{assignment}/submissions Create or edit a submission
FlatApi::ClassApi create_test_student_account POST /classes/{class}/testStudent Create a test student account
FlatApi::ClassApi delete_class_user DELETE /classes/{class}/users/{user} Remove a user from the class
FlatApi::ClassApi delete_submission DELETE /classes/{class}/assignments/{assignment}/submissions/{submission} Reset a submission
FlatApi::ClassApi delete_submission_comment DELETE /classes/{class}/assignments/{assignment}/submissions/{submission}/comments/{comment} Delete a feedback comment to a submission
FlatApi::ClassApi edit_submission PUT /classes/{class}/assignments/{assignment}/submissions/{submission} Edit a submission
FlatApi::ClassApi enroll_class POST /classes/enroll/{enrollmentCode} Join a class
FlatApi::ClassApi export_submissions_reviews_as_csv GET /classes/{class}/assignments/{assignment}/submissions/csv CSV Grades exports
FlatApi::ClassApi export_submissions_reviews_as_excel GET /classes/{class}/assignments/{assignment}/submissions/excel Excel Grades exports
FlatApi::ClassApi get_class GET /classes/{class} Get the details of a single class
FlatApi::ClassApi get_score_submissions GET /scores/{score}/submissions List submissions related to the score
FlatApi::ClassApi get_submission GET /classes/{class}/assignments/{assignment}/submissions/{submission} Get a student submission
FlatApi::ClassApi get_submission_comments GET /classes/{class}/assignments/{assignment}/submissions/{submission}/comments List the feedback comments of a submission
FlatApi::ClassApi get_submission_history GET /classes/{class}/assignments/{assignment}/submissions/{submission}/history Get the history of the submission
FlatApi::ClassApi get_submissions GET /classes/{class}/assignments/{assignment}/submissions List the students' submissions
FlatApi::ClassApi list_assignments GET /classes/{class}/assignments Assignments listing
FlatApi::ClassApi list_class_student_submissions GET /classes/{class}/students/{user}/submissions List the submissions for a student
FlatApi::ClassApi list_classes GET /classes List the classes available for the current user
FlatApi::ClassApi post_submission_comment POST /classes/{class}/assignments/{assignment}/submissions/{submission}/comments Add a feedback comment to a submission
FlatApi::ClassApi unarchive_assignment DELETE /classes/{class}/assignments/{assignment}/archive Unarchive the assignment.
FlatApi::ClassApi unarchive_class DELETE /classes/{class}/archive Unarchive the class
FlatApi::ClassApi update_class PUT /classes/{class} Update the class
FlatApi::ClassApi update_submission_comment PUT /classes/{class}/assignments/{assignment}/submissions/{submission}/comments/{comment} Update a feedback comment to a submission
FlatApi::CollectionApi add_score_to_collection PUT /collections/{collection}/scores/{score} Add a score to the collection
FlatApi::CollectionApi create_collection POST /collections Create a new collection
FlatApi::CollectionApi delete_collection DELETE /collections/{collection} Delete the collection
FlatApi::CollectionApi delete_score_from_collection DELETE /collections/{collection}/scores/{score} Delete a score from the collection
FlatApi::CollectionApi edit_collection PUT /collections/{collection} Update a collection's metadata
FlatApi::CollectionApi get_collection GET /collections/{collection} Get collection details
FlatApi::CollectionApi list_collection_scores GET /collections/{collection}/scores List the scores contained in a collection
FlatApi::CollectionApi list_collections GET /collections List the collections
FlatApi::CollectionApi untrash_collection POST /collections/{collection}/untrash Untrash a collection
FlatApi::EduResourcesApi copy_edu_resource POST /eduResources/{resource}/copy Copy an education resource to a Resource Library
FlatApi::EduResourcesApi copy_edu_resource_to_demo_class POST /eduResources/{resource}/copyToDemoClass Copy an education assignment to a teacher demo class
FlatApi::EduResourcesApi create_edu_resource POST /eduResources Create a new education resource
FlatApi::EduResourcesApi create_edu_resource_lti_link POST /eduResources/{resource}/createLtiLink Create an LTI link for an education resource
FlatApi::EduResourcesApi delete_edu_resource DELETE /eduResources/{resource} Delete an education resource
FlatApi::EduResourcesApi get_edu_resource GET /eduResources/{resource} Get an education resource
FlatApi::EduResourcesApi list_edu_libraries GET /eduResources/libraries List the education libraries
FlatApi::EduResourcesApi list_edu_resources GET /eduResources List education resources in a library or folder
FlatApi::EduResourcesApi move_edu_resource POST /eduResources/{resource}/move Move an education resource
FlatApi::EduResourcesApi update_edu_resource PUT /eduResources/{resource} Update an education resource metadata
FlatApi::EduResourcesApi update_edu_resource_assignment PUT /eduResources/{resource}/assignment Update an education resource assignment
FlatApi::EduResourcesApi use_edu_resource_in_class POST /eduResources/{resource}/useInClass Use an education resource in a class
FlatApi::GroupApi get_group_details GET /groups/{group} Get group information
FlatApi::GroupApi get_group_scores GET /groups/{group}/scores List group's scores
FlatApi::GroupApi list_group_users GET /groups/{group}/users List group's users
FlatApi::OrganizationApi count_orga_users GET /organizations/users/count Count the organization users using the provided filters
FlatApi::OrganizationApi create_lti_credentials POST /organizations/lti/credentials Create a new couple of LTI 1.x credentials
FlatApi::OrganizationApi create_organization_invitation POST /organizations/invitations Create a new invitation to join the organization
FlatApi::OrganizationApi create_organization_user POST /organizations/users Create a new user account
FlatApi::OrganizationApi create_organization_user_access_token POST /organizations/users/{user}/accessToken Create a delegated API access token for an organization user
FlatApi::OrganizationApi create_organization_user_signin_link POST /organizations/users/{user}/signinLink Create a sign in link for an organization user
FlatApi::OrganizationApi list_lti_credentials GET /organizations/lti/credentials List LTI 1.x credentials
FlatApi::OrganizationApi list_organization_invitations GET /organizations/invitations List the organization invitations
FlatApi::OrganizationApi list_organization_users GET /organizations/users List the organization users
FlatApi::OrganizationApi remove_organization_invitation DELETE /organizations/invitations/{invitation} Remove an organization invitation
FlatApi::OrganizationApi remove_organization_user DELETE /organizations/users/{user} Remove an account from Flat
FlatApi::OrganizationApi revoke_lti_credentials DELETE /organizations/lti/credentials/{credentials} Revoke LTI 1.x credentials
FlatApi::OrganizationApi update_organization_user PUT /organizations/users/{user} Update account information
FlatApi::ScoreApi add_score_collaborator POST /scores/{score}/collaborators Add a new collaborator
FlatApi::ScoreApi add_score_track POST /scores/{score}/tracks Add a new video or audio track to the score
FlatApi::ScoreApi create_export_task POST /scores/{score}/revisions/{revision}/{format}/task Create a new score export task
FlatApi::ScoreApi create_score POST /scores Create a new score
FlatApi::ScoreApi create_score_revision POST /scores/{score}/revisions Create a new revision
FlatApi::ScoreApi delete_score DELETE /scores/{score} Delete a score
FlatApi::ScoreApi delete_score_comment DELETE /scores/{score}/comments/{comment} Delete a comment
FlatApi::ScoreApi delete_score_track DELETE /scores/{score}/tracks/{track} Remove an audio or video track linked to the score
FlatApi::ScoreApi edit_score PUT /scores/{score} Edit a score's metadata
FlatApi::ScoreApi fork_score POST /scores/{score}/fork Fork a score
FlatApi::ScoreApi get_group_scores GET /groups/{group}/scores List group's scores
FlatApi::ScoreApi get_score GET /scores/{score} Get a score's metadata
FlatApi::ScoreApi get_score_collaborator GET /scores/{score}/collaborators/{collaborator} Get a collaborator
FlatApi::ScoreApi get_score_collaborators GET /scores/{score}/collaborators List the collaborators
FlatApi::ScoreApi get_score_comments GET /scores/{score}/comments List comments
FlatApi::ScoreApi get_score_revision GET /scores/{score}/revisions/{revision} Get a score revision
FlatApi::ScoreApi get_score_revision_data GET /scores/{score}/revisions/{revision}/{format} Get a score revision data
FlatApi::ScoreApi get_score_revisions GET /scores/{score}/revisions List the revisions
FlatApi::ScoreApi get_score_submissions GET /scores/{score}/submissions List submissions related to the score
FlatApi::ScoreApi get_score_track GET /scores/{score}/tracks/{track} Retrieve the details of an audio or video track linked to a score
FlatApi::ScoreApi get_user_likes GET /users/{user}/likes List liked scores
FlatApi::ScoreApi get_user_scores GET /users/{user}/scores List user's scores
FlatApi::ScoreApi list_score_tracks GET /scores/{score}/tracks List the audio or video tracks linked to a score
FlatApi::ScoreApi mark_score_comment_resolved PUT /scores/{score}/comments/{comment}/resolved Mark the comment as resolved
FlatApi::ScoreApi mark_score_comment_unresolved DELETE /scores/{score}/comments/{comment}/resolved Mark the comment as unresolved
FlatApi::ScoreApi post_score_comment POST /scores/{score}/comments Post a new comment
FlatApi::ScoreApi remove_score_collaborator DELETE /scores/{score}/collaborators/{collaborator} Delete a collaborator
FlatApi::ScoreApi untrash_score POST /scores/{score}/untrash Untrash a score
FlatApi::ScoreApi update_score_comment PUT /scores/{score}/comments/{comment} Update an existing comment
FlatApi::ScoreApi update_score_track PUT /scores/{score}/tracks/{track} Update an audio or video track linked to a score
FlatApi::TaskApi get_task GET /tasks/{task} Get a task details
FlatApi::UserApi get_user GET /users/{user} Get a public user profile
FlatApi::UserApi get_user_likes GET /users/{user}/likes List liked scores
FlatApi::UserApi get_user_scores GET /users/{user}/scores List user's scores

Documentation for Models

Documentation for Authorization

Authentication schemes defined for the API:

OAuth2

  • Type: OAuth
  • Flow: accessCode
  • Authorization URL: https://flat.io/auth/oauth
  • Scopes:
    • account.public_profile: Provides access to the basic person's public profile. Education profiles may be anonymized with this scope, you can request the scope `education_profile` to access to the a basic education account profile.
    • account.email: Provices access to the person's email.
    • account.education_profile: Provides access to the basic person's education profile and public organization information.
    • scores.readonly: Allows read-only access to all a user's scores. You won't need this scope to read public scores.
    • scores.social: Allow to post comments and like scores
    • scores: Full, permissive scope to access all of a user's scores.
    • collections.readonly: Allow read-only access to a user's collections.
    • collections.add_scores: Allow to add scores to a user's collections.
    • collections: Full, permissive scope to access all of a user's collections.
    • edu.resources: Read-write access to the resource library.
    • edu.resources.readonly: Read-only access to the resource library.
    • edu.classes: Full, permissive scope to manage the classes.
    • edu.classes.readonly: Read-only access to the classes.
    • edu.assignments: Read-write access to the assignments and submissions.
    • edu.assignments.readonly: Read-only access to the assignments and submissions.
    • edu.admin: Full, permissive scope to manage all the admin of an organization.
    • edu.admin.lti: Access and manage the LTI Credentials for an organization.
    • edu.admin.lti.readonly: Read-only access to the LTI Credentials of an organization.
    • edu.admin.users: Access and manage the users and invitations of the organization.
    • edu.admin.users.readonly: Read-only access to the users and invitations of the organization.
    • tasks.readonly: Read-only access to export tasks created by this account.