From 3040f179f3eb641773286a498ec296f54e10fe31 Mon Sep 17 00:00:00 2001 From: Vincent Giersch Date: Sat, 11 Dec 2021 08:30:02 +0100 Subject: [PATCH] feat(api): API specification v2.16.0 feat(scores): added `POST /scores/{score}/revisions/{revision}/{format}/task` to create a new export task for a score and `GET /tasks/{task}` to fetch the progress of an export task --- spec/swagger.yaml | 180 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 178 insertions(+), 2 deletions(-) diff --git a/spec/swagger.yaml b/spec/swagger.yaml index 7d883c4..61427f3 100644 --- a/spec/swagger.yaml +++ b/spec/swagger.yaml @@ -33,7 +33,7 @@ info: name: Flat url: https://flat.io/developers/docs/api/ email: developers@flat.io - version: 2.15.0 + version: 2.16.0 x-logo: url: https://prod.flat-cdn.com/img/logo-flat.svg servers: @@ -67,6 +67,7 @@ tags: At this time, only `private` privacy mode is widely available. Privacy modes `public`, `organizationPublic` and `privateLink`, and 1:1 sharing will be available in an upcoming update later this year. x-displayName: Collections of music scores + - name: User description: Flat users - name: Organization @@ -75,6 +76,8 @@ tags: description: Flat for Education classes - name: Group description: Flat Groups +- name: Task + description: Scheduled tasks paths: /me: get: @@ -1529,6 +1532,88 @@ paths: - OAuth2: - scores - scores.readonly + /scores/{score}/revisions/{revision}/{format}/task: + post: + tags: + - Score + summary: Create a new score export task + description: | + Some of the exports of a score takes are longer to process than a simple API requests. + Use this endpoint to launch a new export of one score hosted on Flat. + operationId: createExportTask + parameters: + - name: score + in: path + description: | + Unique identifier of the score document. This can be a Flat Score unique identifier (i.e. `ScoreDetails.id`) or, if the score is also a Google Drive file, the Drive file unique identifier prefixed with `drive-` (e.g. `drive-0B000000000`). + required: true + schema: + type: string + - name: revision + in: path + description: | + Unique identifier of a score revision. You can use `last` to fetch the information related to the last version created. + required: true + schema: + type: string + - name: format + in: path + description: The format of the file that will be generated or the target service name where the file will be exported + required: true + schema: + type: string + enum: + - mp3 + - wav + - practicefirst + - name: sharingKey + in: query + description: | + This sharing key must be specified to access to a score or collection with a `privacy` mode set to `privateLink` and the current user is not a collaborator of the document. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/TaskExportOptions' + required: false + responses: + 200: + description: Task associated to the generation of the file + content: + application/json: + schema: + $ref: '#/components/schemas/Task' + 402: + description: Account overquota + content: + application/json: + schema: + $ref: '#/components/schemas/FlatErrorResponse' + 403: + description: Not granted to access to this score + content: + application/json: + schema: + $ref: '#/components/schemas/FlatErrorResponse' + 404: + description: Score or associated file not found + content: + application/json: + schema: + $ref: '#/components/schemas/FlatErrorResponse' + default: + description: Error + content: + application/json: + schema: + $ref: '#/components/schemas/FlatErrorResponse' + security: + - OAuth2: + - scores + - scores.readonly + x-codegen-request-body-name: body /collections: get: tags: @@ -1994,6 +2079,37 @@ paths: security: - OAuth2: - collections + /tasks/{task}: + parameters: + - name: task + in: path + description: Unique identifier for the task + required: true + schema: + type: string + get: + tags: + - Task + summary: Get a task details + description: | + This method can be used to follow a task progression, for example while a score is being exported. + operationId: getTask + responses: + 200: + description: Task details + content: + application/json: + schema: + $ref: '#/components/schemas/Task' + default: + description: Error + content: + application/json: + schema: + $ref: '#/components/schemas/FlatErrorResponse' + security: + - OAuth2: + - tasks.readonly /users/{user}: parameters: - name: user @@ -2008,7 +2124,7 @@ paths: - User summary: Get a public user profile description: | - Get a public profile of a Flat User. + Get a profile of a Flat or Flat for Education User. operationId: getUser responses: 200: @@ -3626,6 +3742,7 @@ components: 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. schemas: FlatLocales: type: string @@ -4938,6 +5055,20 @@ components: measureUuid: 0be9f739-3213-f312-bb0a-00ad0c787ef7 autosave: true description: New revision + TaskExportOptions: + type: object + properties: + parts: + type: array + description: A list of parts to specifically export + items: + type: string + description: | + Options for the requested export + example: + parts: + - 49b7d7c5-7490-4f76-9813-607f79e5b92b + - 96b5066b-54ed-4c6b-b3fc-cb7281403a89 ScoreCommentContext: required: - measureUuids @@ -5193,6 +5324,7 @@ components: - edu.admin.lti.readonly - edu.admin.users - edu.admin.users.readonly + - tasks.readonly OrganizationUserAccessTokenCreation: required: - scopes @@ -6320,6 +6452,50 @@ components: thumbnailWidth: 1868 authorName: Flat authorUrl: https://www.youtube.com/channel/UCEUIbEP9Rba_g0r4eeGhmXw + Task: + type: object + description: An asynchronous task + properties: + id: + type: string + description: Unique identifier of the task + type: + type: string + description: Type of the task + enum: + - audio-export + - audio-low-prio + state: + type: string + description: State of the Task + enum: + - created + - doing + - done + - canceled + - error + progress: + type: object + description: Details about the task progression + properties: + percent: + type: number + description: Percent of the task progression + text: + type: string + description: Text details of the task progress + creationDate: + type: string + description: The creation date of the task + format: date-time + modificationDate: + type: string + description: The last modification date of the task + format: date-time + doneDate: + type: string + description: The date when the task has been completed + format: date-time FlatErrorResponse: description: An API Error response type: object