From 01fcee7f68d33236aad10c453a4e04fbe7365f8a Mon Sep 17 00:00:00 2001 From: aneeshafedo Date: Fri, 11 Jun 2021 11:13:33 +0530 Subject: [PATCH 01/14] add spotify connector --- openapi/spotify/.gitignore | 1 + openapi/spotify/Ballerina.toml | 11 + openapi/spotify/Package.md | 56 ++ openapi/spotify/client.bal | 141 ++++ openapi/spotify/openapi.yaml | 1429 ++++++++++++++++++++++++++++++++ openapi/spotify/types.bal | 303 +++++++ 6 files changed, 1941 insertions(+) create mode 100644 openapi/spotify/.gitignore create mode 100644 openapi/spotify/Ballerina.toml create mode 100644 openapi/spotify/Package.md create mode 100644 openapi/spotify/client.bal create mode 100644 openapi/spotify/openapi.yaml create mode 100644 openapi/spotify/types.bal diff --git a/openapi/spotify/.gitignore b/openapi/spotify/.gitignore new file mode 100644 index 000000000..1de565933 --- /dev/null +++ b/openapi/spotify/.gitignore @@ -0,0 +1 @@ +target \ No newline at end of file diff --git a/openapi/spotify/Ballerina.toml b/openapi/spotify/Ballerina.toml new file mode 100644 index 000000000..8a980ef24 --- /dev/null +++ b/openapi/spotify/Ballerina.toml @@ -0,0 +1,11 @@ +[package] +org = "ballerinax" +name = "spotify" +version = "0.1.0" +license= ["Apache-2.0"] +authors = ["Ballerina"] +keywords = ["spotify", "spotify playlist"] +repository = "https://github.com/ballerina-platform/ballerinax-openapi-connectors" + +[build-options] +observabilityIncluded = true \ No newline at end of file diff --git a/openapi/spotify/Package.md b/openapi/spotify/Package.md new file mode 100644 index 000000000..0efa603a0 --- /dev/null +++ b/openapi/spotify/Package.md @@ -0,0 +1,56 @@ +Conncets to Spotify Playlist API from Ballerina. + +## Module Overview + +The Spotify Playlist connector consume the data exposed in [https://api.spotify.com](https://api.spotify.com/v1). It is currently supporting following operations. + +- getMyPlaylists +- getPlaylistById +- createPlaylist +- updatePlaylist +- getPlaylistCover +- updatePlaylistCover +- getPlaylistTracks +- reorderOrReplacePlaylistTracks +- getPlayslistsByUserID + + +## Compatibility + +| | Version | +|:---------------------:|:---------------------------:| +| Ballerina Language | Swan-Lake-Alpha5 | +| Spotify Playlist API | v1 | + + +# Quickstart + +## Obtain Tokens for Authentication + +Spotify Web API follows OAuth 2.0 mechanism for authentication. Please follow below steps to get tokens to access the API + +1. Create a Spotify account +2. Register your application inSpotify developer portal +2. Use Client Id and Client Secret to get access token or refresh token. + +Please see [here](https://developer.spotify.com/documentation/web-api/quick-start/) for more details. + +Then provide the tokens to configure the client. + +### Client configuration + +```ballerina + import ballerinax/spotify; + + spotify:ClientConfig clientConfig = { + authConfig : { + refreshUrl = "" + refreshToken = "" + clientId = "" + clientSecret = "" + } + }; + + spotify:Client spotifyClient = new spotify:Client(clientConfig); +``` + \ No newline at end of file diff --git a/openapi/spotify/client.bal b/openapi/spotify/client.bal new file mode 100644 index 000000000..c8c637dd7 --- /dev/null +++ b/openapi/spotify/client.bal @@ -0,0 +1,141 @@ +// Copyright (c) 2021, WSO2 Inc. (http://www.wso2.org) All Rights Reserved. +// +// WSO2 Inc. licenses this file to you under the Apache License, +// Version 2.0 (the "License"); you may not use this file except +// in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +import ballerina/http; +import ballerina/url; +import ballerina/lang.'string; + +public type ClientConfig record { + http:BearerTokenConfig|http:OAuth2RefreshTokenGrantConfig authConfig; + http:ClientSecureSocket secureSocketConfig?; +}; + +type ImageObjectArr ImageObject[]; + +@display {label: "Spotify Client"} +public client class Client { + http:Client clientEp; + public isolated function init(ClientConfig clientConfig, string serviceUrl = "https://api.spotify.com/v1") returns error? { + http:ClientSecureSocket? secureSocketConfig = clientConfig?.secureSocketConfig; + http:Client httpEp = check new (serviceUrl, { auth: clientConfig.authConfig, secureSocket: secureSocketConfig }); + self.clientEp = httpEp; + } + @display {label: "My Playlists"} + remote isolated function getMyPlaylists(@display {label: "Limit"} int? 'limit = (), @display {label: "Offset"} int? offset = ()) returns CurrentPlaylistDetails|error { + string path = string `/me/playlists`; + map queryParam = {'limit: 'limit, offset: offset}; + path = path + getPathForQueryParam(queryParam); + CurrentPlaylistDetails response = check self.clientEp-> get(path, targetType = CurrentPlaylistDetails); + return response; + } + @display {label: "Playlist By Id"} + remote isolated function getPlaylistById(@display {label: "Playlist Id"} string playlist_id, @display {label: "Market"} string? market = (), @display {label: "Fields to Return"} string? fields = (), @display {label: "Additional Types"} string? additional_types = ()) returns PlaylistObject|error { + string path = string `/playlists/${playlist_id}`; + map queryParam = {market: market, fields: fields, additional_types: additional_types}; + path = path + getPathForQueryParam(queryParam); + PlaylistObject response = check self.clientEp-> get(path, targetType = PlaylistObject); + return response; + } + @display {label: "Update Playlist"} + remote isolated function updatePlaylist(@display {label: "Content Type"} string 'Content\-Type, @display {label: "Playlist Id"} string playlist_id, ChangePlayListDetails payload) returns error? { + string path = string `/playlists/${playlist_id}`; + map accHeaders = {'Content\-Type: 'Content\-Type}; + http:Request request = new; + json jsonBody = check payload.cloneWithType(json); + request.setPayload(jsonBody); + _ = check self.clientEp->put(path, request, headers = accHeaders, targetType=http:Response); + } + @display {label: "Playlist Cover"} + remote isolated function getPlaylistCover(@display {label: "Playlist Id"} string playlist_id) returns ImageObjectArr|error { + string path = string `/playlists/${playlist_id}/images`; + ImageObjectArr response = check self.clientEp-> get(path, targetType = ImageObjectArr); + return response; + } + @display {label: "Update Playlist Cover"} + remote isolated function updatePlaylistCover(@display {label: "Content Type"} string 'Content\-Type, @display {label: "Playlist Id"} string playlist_id) returns error? { + string path = string `/playlists/${playlist_id}/images`; + map accHeaders = {'Content\-Type: 'Content\-Type}; + http:Request request = new; + //TODO: Update the request as needed; + _ = check self.clientEp-> put(path, request, headers = accHeaders, targetType=http:Response); + } + @display {label: "Playlist Tracks"} + remote isolated function getPlaylistTracks(@display {label: "Playlist Id"} string playlist_id, @display {label: "Market"} string market, @display {label: "Fields to Return"} string? fields = (), @display {label: "Limit"} int? 'limit = (), @display {label: "Offset"} int? offset = (), string? additional_types = ()) returns PlaylistTrackDetails|error { + string path = string `/playlists/${playlist_id}/tracks`; + map queryParam = {market: market, fields: fields, 'limit: 'limit, offset: offset, additional_types: additional_types}; + path = path + getPathForQueryParam(queryParam); + PlaylistTrackDetails response = check self.clientEp-> get(path, targetType = PlaylistTrackDetails); + return response; + } + @display {label: "Reorder or Replace Tracks"} + remote isolated function reorderOrReplacePlaylistTracks(@display {label: "Playlist Id"} string playlist_id, PlayListReorderDetails payload, @display {label: "Track URIs"} string? uris = ()) returns SnapshotIdObject|error { + string path = string `/playlists/${playlist_id}/tracks`; + map queryParam = {uris: uris}; + path = path + getPathForQueryParam(queryParam); + http:Request request = new; + json jsonBody = check payload.cloneWithType(json); + request.setPayload(jsonBody); + SnapshotIdObject response = check self.clientEp->put(path, request, targetType=SnapshotIdObject); + return response; + } + @display {label: "Playlist By User Id"} + remote isolated function getPlayslistsByUserID(@display {label: "User Id"} string user_id, @display {label: "Limit"} int? 'limit = (), @display {label: "Offset"} int? offset = ()) returns UserPlayListDetails|error { + string path = string `/users/${user_id}/playlists`; + map queryParam = {'limit: 'limit, offset: offset}; + path = path + getPathForQueryParam(queryParam); + UserPlayListDetails response = check self.clientEp-> get(path, targetType = UserPlayListDetails); + return response; + } + @display {label: "Create Playlist"} + remote isolated function createPlaylist(@display {label: "User Id"} string user_id, PlayListDetails payload) returns PlaylistObject|error { + string path = string `/users/${user_id}/playlists`; + http:Request request = new; + json jsonBody = check payload.cloneWithType(json); + request.setPayload(jsonBody); + PlaylistObject response = check self.clientEp->post(path, request, targetType=PlaylistObject); + return response; + } +} + +isolated function getPathForQueryParam(map queryParam) returns string { + string[] param = []; + param[param.length()] = "?"; + foreach var [key, value] in queryParam.entries() { + if value is () { + _ = queryParam.remove(key); + } else { + if string:startsWith( key, "'") { + param[param.length()] = string:substring(key, 1, key.length()); + } else { + param[param.length()] = key; + } + param[param.length()] = "="; + if value is string { + string updateV = checkpanic url:encode(value, "UTF-8"); + param[param.length()] = updateV; + } else { + param[param.length()] = value.toString(); + } + param[param.length()] = "&"; + } + } + _ = param.remove(param.length()-1); + if param.length() == 1 { + _ = param.remove(0); + } + string restOfPath = string:'join("", ...param); + return restOfPath; +} diff --git a/openapi/spotify/openapi.yaml b/openapi/spotify/openapi.yaml new file mode 100644 index 000000000..dcdb0d605 --- /dev/null +++ b/openapi/spotify/openapi.yaml @@ -0,0 +1,1429 @@ +openapi: 3.0.1 +servers: + - url: https://api.spotify.com/v1 +info: + title: Spotify Web API + version: 0.1.0 + x-display: + label: "Spotify Client" +externalDocs: + description: Find more info on the official Spotify Web API Reference + url: https://developer.spotify.com/documentation/web-api/reference +tags: + - description: Playlists API + externalDocs: + description: Find more info on the official Spotify Web API Reference + url: https://developer.spotify.com/documentation/web-api/reference/#category-playlists + name: category-playlists +paths: + /me/playlists: + get: + description: |- + Get a list of the playlists owned or followed by the current Spotify + user. + externalDocs: + description: Find more info on the official Spotify Web API Reference + url: https://developer.spotify.com/documentation/web-api/reference/#endpoint-get-a-list-of-current-users-playlists + operationId: getMyPlaylists + x-display: + label: "My Playlists" + parameters: + - description: "'The maximum number of playlists to return. Default: 20. Minimum: 1. Maximum: 50.'" + in: query + name: limit + required: false + schema: + format: int32 + type: integer + x-display: + label: "Limit" + - description: "'The index of the first playlist to return. Default: 0 (the first object). Maximum offset: 100.000. Use with `limit` to get the next set of playlists.'" + in: query + name: offset + required: false + schema: + format: int32 + type: integer + x-display: + label: "Offset" + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/CurrentPlaylistDetails" + description: On success, the HTTP status code in the response header is `200` OK and the response body contains an array of simplified [playlist objects](https://developer.spotify.com/documentation/web-api/reference/#object-simplifiedplaylistobject) (wrapped in a [paging object](https://developer.spotify.com/documentation/web-api/reference/#object-pagingobject)) in JSON format. On error, the header status code is an [error code](https://developer.spotify.com/documentation/web-api/#response-status-codes) and the response body contains an [error object](https://developer.spotify.com/documentation/web-api/#response-schema). Please note that the access token has to be tied to a user. + default: + $ref: "#/components/responses/ErrorResponse" + security: + - spotify_auth: + - playlist-read-private + - playlist-read-collaborative + summary: Get a List of Current User's Playlists + tags: + - category-playlists + /playlists/{playlist_id}: + get: + description: Get a playlist owned by a Spotify user. + externalDocs: + description: Find more info on the official Spotify Web API Reference + url: https://developer.spotify.com/documentation/web-api/reference/#endpoint-get-playlist + operationId: getPlaylistById + x-display: + label: "Playlist By Id" + parameters: + - description: The [Spotify ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the playlist. + in: path + name: playlist_id + required: true + schema: + type: string + x-display: + label: "Playlist Id" + - description: |- + An [ISO 3166-1 alpha-2 country code](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) or the string `from_token`. Provide this parameter if you want to apply [Track + Relinking](https://developer.spotify.com/documentation/general/guides/track-relinking-guide/). For episodes, if a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter. + *Note: If neither market or user country are provided, the episode is considered unavailable for the client.* + in: query + name: market + required: false + schema: + type: string + x-display: + label: "Market" + - description: "Filters for the query: a comma-separated list of the fields to return. If omitted, all fields are returned. For example, to get just the playlist''s description and URI: `fields=description,uri`. A dot separator can be used to specify non-reoccurring fields, while parentheses can be used to specify reoccurring fields within objects. For example, to get just the added date and user ID of the adder: `fields=tracks.items(added_at,added_by.id)`. Use multiple parentheses to drill down into nested objects, for example: `fields=tracks.items(track(name,href,album(name,href)))`. Fields can be excluded by prefixing them with an exclamation mark, for example: `fields=tracks.items(track(name,href,album(!name,href)))`" + in: query + name: fields + required: false + schema: + type: string + x-display: + label: "Fields to Return" + - description: "A comma-separated list of item types that your client supports besides the default `track` type. Valid types are: `track` and `episode`. **Note** : This parameter was introduced to allow existing clients to maintain their current behaviour and might be deprecated in the future. In addition to providing this parameter, make sure that your client properly handles cases of new types in the future by checking against the `type` field of each object." + in: query + name: additional_types + required: false + schema: + type: string + x-display: + label: "Additional Types" + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/PlaylistObject" + description: On success, the response body contains a [playlist object](https://developer.spotify.com/documentation/web-api/reference/#object-playlistobject) in JSON format and the HTTP status code in the response header is `200` OK. If an episode is unavailable in the given `market`, its information will not be included in the response. On error, the header status code is an [error code](https://developer.spotify.com/documentation/web-api/#response-status-codes) and the response body contains an [error object](https://developer.spotify.com/documentation/web-api/#response-schema). Requesting playlists that you do not have the user's authorization to access returns error `403` Forbidden. + default: + $ref: "#/components/responses/ErrorResponse" + security: + - spotify_auth: [] + summary: Get a Playlist + tags: + - category-playlists + put: + description: |- + Change a playlist's name and public/private state. (The user must, of + course, own the playlist.) + externalDocs: + description: Find more info on the official Spotify Web API Reference + url: https://developer.spotify.com/documentation/web-api/reference/#endpoint-change-playlist-details + operationId: updatePlaylist + x-display: + label: "Update Playlist" + parameters: + - description: "The content type of the request body: `application/json`" + in: header + name: Content-Type + required: true + schema: + type: string + x-display: + label: "Content Type" + - description: The [Spotify ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the playlist. + in: path + name: playlist_id + required: true + schema: + type: string + x-display: + label: "Playlist Id" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/ChangePlayListDetails" + type: object + required: false + responses: + "200": + description: |- + On success the HTTP status code in the response header is `200` OK. + + On error, the header status code is an [error code](https://developer.spotify.com/documentation/web-api/#response-status-codes) and the response body contains an [error object](https://developer.spotify.com/documentation/web-api/#response-schema). Trying to change a playlist when you do not have the user's authorization returns error `403` Forbidden. + default: + $ref: "#/components/responses/ErrorResponse" + security: + - spotify_auth: + - playlist-modify-public + - playlist-modify-private + summary: Change a Playlist's Details + tags: + - category-playlists + /playlists/{playlist_id}/images: + get: + description: Get the current image associated with a specific playlist. + externalDocs: + description: Find more info on the official Spotify Web API Reference + url: https://developer.spotify.com/documentation/web-api/reference/#endpoint-get-playlist-cover + operationId: getPlaylistCover + x-display: + label: "Playlist Cover" + parameters: + - description: The [Spotify ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the playlist. + in: path + name: playlist_id + required: true + schema: + type: string + x-display: + label: "Playlist Id" + responses: + "200": + content: + application/json: + schema: + items: + $ref: "#/components/schemas/ImageObject" + type: array + description: |- + On success, the response body contains a list of [image objects](https://developer.spotify.com/documentation/web-api/reference/#object-imageobject) in JSON format and the HTTP status code in the response header is `200` OK + On error, the header status code is an [error code](https://developer.spotify.com/documentation/web-api/#response-status-codes) and the response body contains an [error object](https://developer.spotify.com/documentation/web-api/#response-schema). + default: + $ref: "#/components/responses/ErrorResponse" + security: + - spotify_auth: [] + summary: Get a Playlist Cover Image + tags: + - category-playlists + put: + description: Replace the image used to represent a specific playlist. + externalDocs: + description: Find more info on the official Spotify Web API Reference + url: https://developer.spotify.com/documentation/web-api/reference/#endpoint-upload-custom-playlist-cover + operationId: updatePlaylistCover + x-display: + label: "Update Playlist Cover" + parameters: + - description: "The content type of the request body: `image/jpeg`" + in: header + name: Content-Type + required: true + schema: + type: string + x-display: + label: "Content Type" + - description: The [Spotify ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the playlist. + in: path + name: playlist_id + required: true + schema: + type: string + x-display: + label: "Playlist Id" + responses: + "202": + description: |- + If you get status code `429`, it means that you have sent too many requests. + If this happens, have a look in the `Retry-After` header, where you will see a number displayed. + This is the amount of seconds that you need to wait, before you can retry sending your requests. + default: + $ref: "#/components/responses/ErrorResponse" + security: + - spotify_auth: + - ugc-image-upload + - playlist-modify-public + - playlist-modify-private + summary: Upload a Custom Playlist Cover Image + tags: + - category-playlists + /playlists/{playlist_id}/tracks: + get: + description: Get full details of the items of a playlist owned by a Spotify user. + externalDocs: + description: Find more info on the official Spotify Web API Reference + url: https://developer.spotify.com/documentation/web-api/reference/#endpoint-get-playlists-tracks + operationId: getPlaylistTracks + x-display: + label: "Playlist Tracks" + parameters: + - description: The [Spotify ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the playlist. + in: path + name: playlist_id + required: true + schema: + type: string + x-display: + label: "Playlist Id" + - description: |- + An [ISO 3166-1 alpha-2 country code](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) or the string `from_token`. Provide this parameter if you want to apply [Track + Relinking](https://developer.spotify.com/documentation/general/guides/track-relinking-guide/). For episodes, if a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter. + *Note: If neither market or user country are provided, the episode is considered unavailable for the client.* + in: query + name: market + required: true + schema: + type: string + x-display: + label: "Market" + - description: |- + Filters for the query: a comma-separated list of the fields to return. If omitted, all fields are returned. For example, to get just the total number of items and the request limit: + `fields=total,limit` + A dot separator can be used to specify non-reoccurring fields, while parentheses can be used to specify reoccurring fields within objects. For example, to get just the added date and user ID of the adder: + `fields=items(added_at,added_by.id)` + Use multiple parentheses to drill down into nested objects, for example: + `fields=items(track(name,href,album(name,href)))` + Fields can be excluded by prefixing them with an exclamation mark, for example: + `fields=items.track.album(!external_urls,images)` + in: query + name: fields + required: false + schema: + type: string + x-display: + label: "Fields to Return" + - description: "The maximum number of items to return. Default: 100. Minimum: 1. Maximum: 100." + in: query + name: limit + required: false + schema: + format: int32 + type: integer + x-display: + label: "Limit" + - description: "The index of the first item to return. Default: 0 (the first object)." + in: query + name: offset + required: false + schema: + format: int32 + type: integer + x-display: + label: "Offset" + - description: "A comma-separated list of item types that your client supports besides the default `track` type. Valid types are: `track` and `episode`. **Note** : This parameter was introduced to allow existing clients to maintain their current behaviour and might be deprecated in the future. In addition to providing this parameter, make sure that your client properly handles cases of new types in the future by checking against the `type` field of each object." + in: query + name: additional_types + required: false + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/PlaylistTrackDetails" + description: On success, the response body contains an array of [track objects](https://developer.spotify.com/documentation/web-api/reference/#object-simplifiedtrackobject) and [episode objects](https://developer.spotify.com/documentation/web-api/reference/#object-simplifiedepisodeobject) (depends on the `additional_types` parameter), wrapped in a [paging object](https://developer.spotify.com/documentation/web-api/reference/#object-pagingobject) in JSON format and the HTTP status code in the response header is `200` OK. If an episode is unavailable in the given `market`, its information will not be included in the response. On error, the header status code is an [error code](https://developer.spotify.com/documentation/web-api/#response-status-codes) and the response body contains an [error object](https://developer.spotify.com/documentation/web-api/#response-schema). Requesting playlists that you do not have the user's authorization to access returns error `403` Forbidden. + default: + $ref: "#/components/responses/ErrorResponse" + security: + - spotify_auth: [] + summary: Get a Playlist's Items + tags: + - category-playlists + put: + description: |- + Either reorder or replace items in a playlist depending on the request's parameters. + To reorder items, include `range_start`, `insert_before`, `range_length` and `snapshot_id` in the request's body. + To replace items, include `uris` as either a query parameter or in the request's body. + Replacing items in a playlist will overwrite its existing items. This operation can be used for replacing or clearing items in a playlist. + + + **Note**: Replace and reorder are mutually exclusive operations which share the same endpoint, but have different parameters. + These operations can't be applied together in a single request. + externalDocs: + description: Find more info on the official Spotify Web API Reference + url: https://developer.spotify.com/documentation/web-api/reference/#endpoint-reorder-or-replace-playlists-tracks + operationId: reorderOrReplacePlaylistTracks + x-display: + label: "Reorder or Replace Tracks" + parameters: + - description: The [Spotify ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the playlist. + in: path + name: playlist_id + required: true + schema: + type: string + x-display: + label: "Playlist Id" + - description: |- + A comma-separated list of [Spotify URIs](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) to set, can be track or episode URIs. For example: `uris=spotify:track:4iV5W9uYEdYUVa79Axb7Rh,spotify:track:1301WleyT98MSxVHPZCA6M,spotify:episode:512ojhOuo1ktJprKbVcKyQ` + A maximum of 100 items can be set in one request. + in: query + name: uris + required: false + schema: + type: string + x-display: + label: "Track URIs" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/PlayListReorderDetails" + required: false + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/SnapshotIdObject" + description: |- + On a successful **reorder** operation, the response body contains a `snapshot_id` in JSON format + and the HTTP status code in the response header is `200` OK. The `snapshot_id` + can be used to identify your playlist version in future requests. + + On a successful **replace** operation, the HTTP status code in the response header is `201` + Created. + + On error, the header status code is an [error code](https://developer.spotify.com/documentation/web-api/#response-status-codes), + the response body contains an [error object](https://developer.spotify.com/documentation/web-api/#response-schema), + and the existing playlist is unmodified. + Trying to set an item when you do not have the user's authorization returns error `403` Forbidden. + "201": + description: |- + On a successful **reorder** operation, the response body contains a `snapshot_id` in JSON format + and the HTTP status code in the response header is `200` OK. The `snapshot_id` + can be used to identify your playlist version in future requests. + + On a successful **replace** operation, the HTTP status code in the response header is `201` + Created. + + On error, the header status code is an [error code](https://developer.spotify.com/documentation/web-api/#response-status-codes), + the response body contains an [error object](https://developer.spotify.com/documentation/web-api/#response-schema), + and the existing playlist is unmodified. + Trying to set an item when you do not have the user's authorization returns error `403` Forbidden. + default: + $ref: "#/components/responses/ErrorResponse" + security: + - spotify_auth: + - playlist-modify-public + - playlist-modify-private + summary: Reorder or Replace a Playlist's Items + tags: + - category-playlists + /users/{user_id}/playlists: + get: + description: Get a list of the playlists owned or followed by a Spotify user. + externalDocs: + description: Find more info on the official Spotify Web API Reference + url: https://developer.spotify.com/documentation/web-api/reference/#endpoint-get-list-users-playlists + operationId: getPlayslistsByUserID + x-display: + label: "Playlist By User Id" + parameters: + - description: The user's [Spotify user ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids). + in: path + name: user_id + required: true + schema: + type: string + x-display: + label: "User Id" + - description: "The maximum number of playlists to return. Default: 20. Minimum: 1. Maximum: 50." + in: query + name: limit + required: false + schema: + format: int32 + type: integer + x-display: + label: "Limit" + - description: "The index of the first playlist to return. Default: 0 (the first object). Maximum offset: 100.000. Use with `limit` to get the next set of playlists." + in: query + name: offset + required: false + schema: + format: int32 + type: integer + x-display: + label: "Offset" + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/UserPlayListDetails" + description: On success, the HTTP status code in the response header is `200` OK and the response body contains an array of simplified [playlist objects](https://developer.spotify.com/documentation/web-api/reference/#object-simplifiedplaylistobject) (wrapped in a [paging object](https://developer.spotify.com/documentation/web-api/reference/#object-pagingobject)) in JSON format. On error, the header status code is an [error code](https://developer.spotify.com/documentation/web-api/#response-status-codes) and the response body contains an [error object](https://developer.spotify.com/documentation/web-api/#response-schema). + default: + $ref: "#/components/responses/ErrorResponse" + security: + - spotify_auth: + - playlist-read-private + - playlist-read-collaborative + summary: Get a List of a User's Playlists + tags: + - category-playlists + post: + description: |- + Create a playlist for a Spotify user. (The playlist will be empty until + you [add tracks](https://developer.spotify.com/documentation/web-api/reference/#endpoint-add-tracks-to-playlist).) + externalDocs: + description: Find more info on the official Spotify Web API Reference + url: https://developer.spotify.com/documentation/web-api/reference/#endpoint-create-playlist + operationId: createPlaylist + x-display: + label: "Create Playlist" + parameters: + - description: The user's [Spotify user ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids). + in: path + name: user_id + required: true + schema: + type: string + x-display: + label: "User Id" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/PlayListDetails" + type: object + required: true + responses: + "200": + content: + application/json: + schema: + $ref: "#/components/schemas/PlaylistObject" + description: |- + On success, the response body contains the created [playlist object](https://developer.spotify.com/documentation/web-api/reference/#object-playlistobject) + in JSON format and the HTTP status code in the response header is `200` OK or + `201` Created. There is also a `Location` response header giving the Web API + endpoint for the new playlist. + + On error, the header status code is an [error code](https://developer.spotify.com/documentation/web-api/#response-status-codes) and the response body contains an [error object](https://developer.spotify.com/documentation/web-api/#response-schema). Trying to create a playlist when you do not have the user's authorization returns error `403` Forbidden. + "201": + content: + application/json: + schema: + $ref: "#/components/schemas/PlaylistObject" + description: |- + On success, the response body contains the created [playlist object](https://developer.spotify.com/documentation/web-api/reference/#object-playlistobject) + in JSON format and the HTTP status code in the response header is `200` OK or + `201` Created. There is also a `Location` response header giving the Web API + endpoint for the new playlist. + + On error, the header status code is an [error code](https://developer.spotify.com/documentation/web-api/#response-status-codes) and the response body contains an [error object](https://developer.spotify.com/documentation/web-api/#response-schema). Trying to create a playlist when you do not have the user's authorization returns error `403` Forbidden. + default: + $ref: "#/components/responses/ErrorResponse" + security: + - spotify_auth: + - playlist-modify-public + - playlist-modify-private + summary: Create a Playlist + tags: + - category-playlists +components: + responses: + ErrorResponse: + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorResponseObject" + description: Unexpected error + schemas: + PlayListDetails: + properties: + collaborative: + description: Defaults to `false` . If `true` the playlist will be collaborative. Note that to create a collaborative playlist you must also set `public` to `false` . To create collaborative playlists you must have granted `playlist-modify-private` and `playlist-modify-public` [scopes](https://developer.spotify.com/documentation/general/guides/authorization-guide/#list-of-scopes) . + type: boolean + description: + description: value for playlist description as displayed in Spotify Clients and in the Web API. + type: string + name: + description: The name for the new playlist, for example `"Your Coolest Playlist"` . This name does not need to be unique; a user may have several playlists with the same name. + type: string + public: + description: Defaults to `true` . If `true` the playlist will be public, if `false` it will be private. To be able to create private playlists, the user must have granted the `playlist-modify-private` [scope](https://developer.spotify.com/documentation/general/guides/authorization-guide/#list-of-scopes) + type: boolean + required: + - name + type: object + UserPlayListDetails: + externalDocs: + description: Find more info on the official Spotify Web API Reference + url: https://developer.spotify.com/documentation/web-api/reference/#object-pagingobject + properties: + href: + description: A link to the Web API endpoint returning the full result of the request + type: string + items: + description: The requested data. + items: + $ref: "#/components/schemas/SimplifiedPlaylistObject" + type: array + limit: + description: The maximum number of items in the response (as set in the query or by default). + format: int32 + type: integer + next: + description: URL to the next page of items. ( `null` if none) + type: string + nullable: true + offset: + description: The offset of the items returned (as set in the query or by default) + format: int32 + type: integer + previous: + description: URL to the previous page of items. ( `null` if none) + type: string + nullable: true + total: + description: The total number of items available to return. + format: int32 + type: integer + type: object + PlaylistTrackInsertionDetails: + properties: + position: + description: 'The position to insert the items, a zero-based index. For example, to insert the items in the first position: `position=0` ; to insert the items in the third position: `position=2`. If omitted, the items will be appended to the playlist. Items are added in the order they appear in the uris array. For example: `{"uris": ["spotify:track:4iV5W9uYEdYUVa79Axb7Rh","spotify:track:1301WleyT98MSxVHPZCA6M"], "position": 3}`' + format: int32 + type: integer + uris: + description: |- + A JSON array of the [Spotify URIs](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) to add. For example: `{"uris": ["spotify:track:4iV5W9uYEdYUVa79Axb7Rh","spotify:track:1301WleyT98MSxVHPZCA6M", "spotify:episode:512ojhOuo1ktJprKbVcKyQ"]}` + A maximum of 100 items can be added in one request. *Note: if the `uris` parameter is present in the query string, any URIs listed here in the body will be ignored.* + items: + type: string + type: array + type: object + PlayListReorderDetails: + properties: + insert_before: + description: |- + The position where the items should be inserted. + To reorder the items to the end of the playlist, simply set *insert_before* to the position after the last item. + Examples: + To reorder the first item to the last position in a playlist with 10 items, set *range_start* to 0, and *insert_before* to 10. + To reorder the last item in a playlist with 10 items to the start of the playlist, set *range_start* to 9, and *insert_before* to 0. + format: int32 + type: integer + range_length: + description: |- + The amount of items to be reordered. Defaults to 1 if not set. + The range of items to be reordered begins from the *range_start* position, and includes the *range_length* subsequent items. + Example: + To move the items at index 9-10 to the start of the playlist, *range_start* is set to 9, and *range_length* is set to 2. + format: int32 + type: integer + range_start: + description: The position of the first item to be reordered. + format: int32 + type: integer + snapshot_id: + description: The playlist's snapshot ID against which you want to make the changes. + type: string + uris: + description: |- + A comma-separated list of [Spotify URIs](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) to set, can be track or episode URIs. For example: `uris=spotify:track:4iV5W9uYEdYUVa79Axb7Rh,spotify:track:1301WleyT98MSxVHPZCA6M,spotify:episode:512ojhOuo1ktJprKbVcKyQ` + A maximum of 100 items can be set in one request. + items: + type: string + type: array + type: object + PlaylistTrackDetails: + externalDocs: + description: Find more info on the official Spotify Web API Reference + url: https://developer.spotify.com/documentation/web-api/reference/#object-pagingobject + properties: + href: + description: A link to the Web API endpoint returning the full result of the request + type: string + items: + description: The requested data. + items: + $ref: "#/components/schemas/PlaylistTrackObject" + type: array + limit: + description: The maximum number of items in the response (as set in the query or by default). + format: int32 + type: integer + next: + description: URL to the next page of items. ( `null` if none) + type: string + nullable: true + offset: + description: The offset of the items returned (as set in the query or by default) + format: int32 + type: integer + previous: + description: URL to the previous page of items. ( `null` if none) + type: string + nullable: true + total: + description: The total number of items available to return. + format: int32 + type: integer + type: object + ChangePlayListDetails: + properties: + collaborative: + description: "If `true` , the playlist will become collaborative and other users will be able to modify the playlist in their Spotify client. *Note: You can only set `collaborative` to `true` on non-public playlists.*" + type: boolean + description: + description: Value for playlist description as displayed in Spotify Clients and in the Web API. + type: string + name: + description: The new name for the playlist, for example `"My New Playlist Title"` + type: string + public: + description: If `true` the playlist will be public, if `false` it will be private. + type: boolean + type: object + CurrentPlaylistDetails: + externalDocs: + description: Find more info on the official Spotify Web API Reference + url: https://developer.spotify.com/documentation/web-api/reference/#object-pagingobject + properties: + href: + description: A link to the Web API endpoint returning the full result of the request + type: string + items: + description: The requested data. + items: + $ref: "#/components/schemas/SimplifiedPlaylistObject" + type: array + limit: + description: The maximum number of items in the response (as set in the query or by default). + format: int32 + type: integer + next: + description: URL to the next page of items. ( `null` if none) + type: string + nullable: true + offset: + description: The offset of the items returned (as set in the query or by default) + format: int32 + type: integer + previous: + description: URL to the previous page of items. ( `null` if none) + type: string + nullable: true + total: + description: The total number of items available to return. + format: int32 + type: integer + PlaylistObject: + externalDocs: + description: Find more info on the official Spotify Web API Reference + url: https://developer.spotify.com/documentation/web-api/reference/#object-playlistobject + properties: + collaborative: + description: "`true` if the owner allows other users to modify the playlist." + type: boolean + description: + description: The playlist description. *Only returned for modified, verified playlists, otherwise* `null`. + type: string + external_urls: + $ref: "#/components/schemas/ExternalUrlObject" + followers: + $ref: "#/components/schemas/FollowersObject" + href: + description: A link to the Web API endpoint providing full details of the playlist. + type: string + id: + description: The [Spotify ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the playlist. + type: string + images: + description: "Images for the playlist. The array may be empty or contain up to three images. The images are returned by size in descending order. See [Working with Playlists](https://developer.spotify.com/documentation/general/guides/working-with-playlists/). *Note: If returned, the source URL for the image (`url`) is temporary and will expire in less than a day.*" + items: + $ref: "#/components/schemas/ImageObject" + type: array + name: + description: The name of the playlist. + type: string + owner: + $ref: "#/components/schemas/PublicUserObject" + public: + description: "The playlist's public/private status: `true` the playlist is public, `false` the playlist is private, `null` the playlist status is not relevant. For more about public/private status, see [Working with Playlists](https://developer.spotify.com/documentation/general/guides/working-with-playlists/)" + type: boolean + snapshot_id: + description: The version identifier for the current playlist. Can be supplied in other requests to target a specific playlist version + type: string + tracks: + description: Information about the tracks of the playlist. Note, a track object may be `null`. This can happen if a track is no longer available. + externalDocs: + description: Find more info on the official Spotify Web API Reference + url: https://developer.spotify.com/documentation/web-api/reference/#object-pagingobject + properties: + href: + description: A link to the Web API endpoint returning the full result of the request + type: string + items: + description: The requested data. + items: + $ref: "#/components/schemas/PlaylistTrackObject" + type: array + limit: + description: The maximum number of items in the response (as set in the query or by default). + format: int32 + type: integer + next: + description: URL to the next page of items. ( `null` if none) + type: string + nullable: true + offset: + description: The offset of the items returned (as set in the query or by default) + format: int32 + type: integer + previous: + description: URL to the previous page of items. ( `null` if none) + type: string + nullable: true + total: + description: The total number of items available to return. + format: int32 + type: integer + type: object + type: + description: 'The object type: "playlist"' + type: string + uri: + description: The [Spotify URI](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the playlist. + type: string + type: object + ImageObject: + externalDocs: + description: Find more info on the official Spotify Web API Reference + url: https://developer.spotify.com/documentation/web-api/reference/#object-imageobject + properties: + height: + description: "The image height in pixels. If unknown: `null` or not returned." + format: int32 + type: integer + url: + description: The source URL of the image. + type: string + width: + description: "The image width in pixels. If unknown: `null` or not returned." + format: int32 + type: integer + type: object + SnapshotIdObject: + properties: + snapshot_id: + description: The snapshot_id can be used to identify your playlist version in future requests. + type: string + type: object + ErrorResponseObject: + properties: + error: + $ref: "#/components/schemas/ErrorObject" + type: object + SimplifiedPlaylistObject: + externalDocs: + description: Find more info on the official Spotify Web API Reference + url: https://developer.spotify.com/documentation/web-api/reference/#object-simplifiedplaylistobject + properties: + collaborative: + description: "`true` if the owner allows other users to modify the playlist." + type: boolean + description: + description: The playlist description. *Only returned for modified, verified playlists, otherwise* `null`. + type: string + external_urls: + $ref: "#/components/schemas/ExternalUrlObject" + href: + description: A link to the Web API endpoint providing full details of the playlist. + type: string + id: + description: The [Spotify ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the playlist. + type: string + images: + description: "Images for the playlist. The array may be empty or contain up to three images. The images are returned by size in descending order. See [Working with Playlists](https://developer.spotify.com/documentation/general/guides/working-with-playlists/). *Note: If returned, the source URL for the image (`url`) is temporary and will expire in less than a day.*" + items: + $ref: "#/components/schemas/ImageObject" + type: array + name: + description: The name of the playlist. + type: string + owner: + $ref: "#/components/schemas/PublicUserObject" + public: + description: "The playlist's public/private status: `true` the playlist is public, `false` the playlist is private, `null` the playlist status is not relevant. For more about public/private status, see [Working with Playlists](https://developer.spotify.com/documentation/general/guides/working-with-playlists/)" + type: boolean + snapshot_id: + description: The version identifier for the current playlist. Can be supplied in other requests to target a specific playlist version + type: string + tracks: + $ref: "#/components/schemas/PlaylistTracksRefObject" + type: + description: 'The object type: "playlist"' + type: string + uri: + description: The [Spotify URI](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the playlist. + type: string + type: object + PlaylistTrackObject: + externalDocs: + description: Find more info on the official Spotify Web API Reference + url: https://developer.spotify.com/documentation/web-api/reference/#object-playlisttrackobject + properties: + added_at: + description: The date and time the track or episode was added. *Note that some very old playlists may return `null` in this field.* + format: date-time + type: string + added_by: + $ref: "#/components/schemas/PublicUserObject" + is_local: + description: Whether this track or episode is a [local file](https://developer.spotify.com/web-api/local-files-spotify-playlists/) or not. + type: boolean + track: + description: Information about the track or episode. + oneOf: + - $ref: "#/components/schemas/TrackObject" + - $ref: "#/components/schemas/EpisodeObject" + type: object + ExternalUrlObject: + externalDocs: + description: Find more info on the official Spotify Web API Reference + url: https://developer.spotify.com/documentation/web-api/reference/#object-externalurlobject + properties: + spotify: + description: The [Spotify URL](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the object. + type: string + type: object + FollowersObject: + externalDocs: + description: Find more info on the official Spotify Web API Reference + url: https://developer.spotify.com/documentation/web-api/reference/#object-followersobject + properties: + href: + description: A link to the Web API endpoint providing full details of the followers; `null` if not available. Please note that this will always be set to null, as the Web API does not support it at the moment. + type: string + total: + description: The total number of followers. + format: int32 + type: integer + PublicUserObject: + externalDocs: + description: Find more info on the official Spotify Web API Reference + url: https://developer.spotify.com/documentation/web-api/reference/#object-publicuserobject + properties: + display_name: + description: The name displayed on the user's profile. `null` if not available. + type: string + external_urls: + $ref: "#/components/schemas/ExternalUrlObject" + followers: + $ref: "#/components/schemas/FollowersObject" + href: + description: A link to the Web API endpoint for this user. + type: string + id: + description: The [Spotify user ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for this user. + type: string + images: + description: The user's profile image. + items: + $ref: "#/components/schemas/ImageObject" + type: array + type: + description: 'The object type: "user"' + type: string + uri: + description: The [Spotify URI](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for this user. + type: string + type: object + ErrorObject: + externalDocs: + description: Find more info on the official Spotify Web API Reference + url: https://developer.spotify.com/documentation/web-api/reference/#object-errorobject + properties: + message: + description: A short description of the cause of the error. + type: string + status: + description: The HTTP status code (also returned in the response header; see [Response Status Codes](https://developer.spotify.com/documentation/web-api/#response-status-codes) for more information). + format: int32 + type: integer + type: object + PlaylistTracksRefObject: + externalDocs: + description: Find more info on the official Spotify Web API Reference + url: https://developer.spotify.com/documentation/web-api/reference/#object-playlisttracksrefobject + properties: + href: + description: A link to the Web API endpoint where full details of the playlist's tracks can be retrieved. + type: string + total: + description: Number of tracks in the playlist. + format: int32 + type: integer + type: object + EpisodeObject: + externalDocs: + description: Find more info on the official Spotify Web API Reference + url: https://developer.spotify.com/documentation/web-api/reference/#object-episodeobject + properties: + audio_preview_url: + description: A URL to a 30 second preview (MP3 format) of the episode. `null` if not available. + type: string + description: + description: A description of the episode. HTML tags are stripped away from this field, use `html_description` field in case HTML tags are needed. + type: string + duration_ms: + description: The episode length in milliseconds. + format: int32 + type: integer + explicit: + description: Whether or not the episode has explicit content (true = yes it does; false = no it does not OR unknown). + type: boolean + external_urls: + $ref: "#/components/schemas/ExternalUrlObject" + href: + description: A link to the Web API endpoint providing full details of the episode. + type: string + html_description: + description: A description of the episode. This field may contain HTML tags. + type: string + id: + description: The [Spotify ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the episode. + type: string + images: + description: The cover art for the episode in various sizes, widest first. + items: + $ref: "#/components/schemas/ImageObject" + type: array + is_externally_hosted: + description: True if the episode is hosted outside of Spotify's CDN. + type: boolean + is_playable: + description: True if the episode is playable in the given market. Otherwise false. + type: boolean + language: + description: "**Note: This field is deprecated and might be removed in the future. Please use the `languages` field instead.** The language used in the episode, identified by a [ISO 639](https://en.wikipedia.org/wiki/ISO_639) code." + type: string + languages: + description: A list of the languages used in the episode, identified by their [ISO 639](https://en.wikipedia.org/wiki/ISO_639) code. + items: + type: string + type: array + name: + description: The name of the episode. + type: string + release_date: + description: The date the episode was first released, for example `"1981-12-15"`. Depending on the precision, it might be shown as `"1981"` or `"1981-12"`. + type: string + release_date_precision: + description: 'The precision with which `release_date` value is known: `"year"`, `"month"`, or `"day"`.' + type: string + restrictions: + $ref: "#/components/schemas/EpisodeRestrictionObject" + resume_point: + $ref: "#/components/schemas/ResumePointObject" + show: + $ref: "#/components/schemas/SimplifiedShowObject" + type: + description: 'The object type: "episode".' + type: string + uri: + description: The [Spotify URI](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the episode. + type: string + type: object + EpisodeRestrictionObject: + externalDocs: + description: Find more info on the official Spotify Web API Reference + url: https://developer.spotify.com/documentation/web-api/reference/#object-episoderestrictionobject + properties: + reason: + description: |- + The reason for the restriction. Supported values: + + - `market` - The content item is not available in the given market. + - `product` - The content item is not available for the user's subscription type. + - `explicit` - The content item is explicit and the user's account is set to not play explicit content. + Additional reasons may be added in the future. **Note**: If you use this field, make sure that your application safely handles unknown values. + type: string + type: object + ResumePointObject: + externalDocs: + description: Find more info on the official Spotify Web API Reference + url: https://developer.spotify.com/documentation/web-api/reference/#object-resumepointobject + properties: + fully_played: + description: Whether or not the episode has been fully played by the user. + type: boolean + resume_position_ms: + description: The user's most recent position in the episode in milliseconds. + format: int32 + type: integer + type: object + SimplifiedShowObject: + externalDocs: + description: Find more info on the official Spotify Web API Reference + url: https://developer.spotify.com/documentation/web-api/reference/#object-simplifiedshowobject + properties: + available_markets: + description: A list of the countries in which the show can be played, identified by their [ISO 3166-1 alpha-2](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code. + items: + type: string + type: array + copyrights: + description: The copyright statements of the show. + items: + $ref: "#/components/schemas/CopyrightObject" + type: array + description: + description: A description of the show. HTML tags are stripped away from this field, use `html_description` field in case HTML tags are needed. + type: string + explicit: + description: Whether or not the show has explicit content (true = yes it does; false = no it does not OR unknown). + type: boolean + external_urls: + $ref: "#/components/schemas/ExternalUrlObject" + href: + description: A link to the Web API endpoint providing full details of the show. + type: string + html_description: + description: A description of the show. This field may contain HTML tags. + type: string + id: + description: The [Spotify ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the show. + type: string + images: + description: The cover art for the show in various sizes, widest first. + items: + $ref: "#/components/schemas/ImageObject" + type: array + is_externally_hosted: + description: True if all of the show's episodes are hosted outside of Spotify's CDN. This field might be `null` in some cases. + type: boolean + languages: + description: A list of the languages used in the show, identified by their [ISO 639](https://en.wikipedia.org/wiki/ISO_639) code. + items: + type: string + type: array + media_type: + description: The media type of the show. + type: string + name: + description: The name of the episode. + type: string + publisher: + description: The publisher of the show. + type: string + type: + description: 'The object type: "show".' + type: string + uri: + description: The [Spotify URI](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the show. + type: string + type: object + CopyrightObject: + externalDocs: + description: Find more info on the official Spotify Web API Reference + url: https://developer.spotify.com/documentation/web-api/reference/#object-copyrightobject + properties: + text: + description: The copyright text for this content. + type: string + type: + description: "The type of copyright: `C` = the copyright, `P` = the sound recording (performance) copyright." + type: string + type: object + SimplifiedArtistObject: + externalDocs: + description: Find more info on the official Spotify Web API Reference + url: https://developer.spotify.com/documentation/web-api/reference/#object-simplifiedartistobject + properties: + external_urls: + $ref: "#/components/schemas/ExternalUrlObject" + href: + description: A link to the Web API endpoint providing full details of the artist. + type: string + id: + description: The [Spotify ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the artist. + type: string + name: + description: The name of the artist. + type: string + type: + description: 'The object type: `"artist"`' + type: string + uri: + description: The [Spotify URI](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the artist. + type: string + type: object + SimplifiedAlbumObject: + externalDocs: + description: Find more info on the official Spotify Web API Reference + url: https://developer.spotify.com/documentation/web-api/reference/#object-simplifiedalbumobject + properties: + album_group: + description: The field is present when getting an artist's albums. Possible values are "album", "single", "compilation", "appears_on". Compare to album_type this field represents relationship between the artist and the album. + type: string + album_type: + description: 'The type of the album: one of "album", "single", or "compilation".' + type: string + artists: + description: The artists of the album. Each artist object includes a link in `href` to more detailed information about the artist. + items: + $ref: "#/components/schemas/SimplifiedArtistObject" + type: array + available_markets: + description: "The markets in which the album is available: [ISO 3166-1 alpha-2 country codes](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). Note that an album is considered available in a market when at least 1 of its tracks is available in that market." + items: + type: string + type: array + external_urls: + $ref: "#/components/schemas/ExternalUrlObject" + href: + description: A link to the Web API endpoint providing full details of the album. + type: string + id: + description: The [Spotify ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the album. + type: string + images: + description: The cover art for the album in various sizes, widest first. + items: + $ref: "#/components/schemas/ImageObject" + type: array + name: + description: The name of the album. In case of an album takedown, the value may be an empty string. + type: string + release_date: + description: The date the album was first released, for example `1981`. Depending on the precision, it might be shown as `1981-12` or `1981-12-15`. + type: string + release_date_precision: + description: "The precision with which `release_date` value is known: `year` , `month` , or `day`." + type: string + restrictions: + $ref: "#/components/schemas/AlbumRestrictionObject" + total_tracks: + description: The total number of tracks in the album. + format: int32 + type: integer + type: + description: 'The object type: "album"' + type: string + uri: + description: The [Spotify URI](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the album. + type: string + type: object + AlbumRestrictionObject: + externalDocs: + description: Find more info on the official Spotify Web API Reference + url: https://developer.spotify.com/documentation/web-api/reference/#object-albumrestrictionobject + properties: + reason: + description: |- + The reason for the restriction. Supported values: + + - `market` - The content item is not available in the given market. + - `product` - The content item is not available for the user's subscription type. + - `explicit` - The content item is explicit and the user's account is set to not play explicit content. + Additional reasons may be added in the future. **Note**: If you use this field, make sure that your application safely handles unknown values. + type: string + type: object + ArtistObject: + externalDocs: + description: Find more info on the official Spotify Web API Reference + url: https://developer.spotify.com/documentation/web-api/reference/#object-artistobject + properties: + external_urls: + $ref: "#/components/schemas/ExternalUrlObject" + followers: + $ref: "#/components/schemas/FollowersObject" + genres: + description: 'A list of the genres the artist is associated with. For example: `"Prog Rock"` , `"Post-Grunge"`. (If not yet classified, the array is empty.)' + items: + type: string + type: array + href: + description: A link to the Web API endpoint providing full details of the artist. + type: string + id: + description: The [Spotify ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the artist. + type: string + images: + description: Images of the artist in various sizes, widest first. + items: + $ref: "#/components/schemas/ImageObject" + type: array + name: + description: The name of the artist. + type: string + popularity: + description: The popularity of the artist. The value will be between 0 and 100, with 100 being the most popular. The artist's popularity is calculated from the popularity of all the artist's tracks. + format: int32 + type: integer + type: + description: 'The object type: `"artist"`' + type: string + uri: + description: The [Spotify URI](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the artist. + type: string + type: object + ExternalIdObject: + externalDocs: + description: Find more info on the official Spotify Web API Reference + url: https://developer.spotify.com/documentation/web-api/reference/#object-externalidobject + properties: + ean: + description: "[International Article Number](http://en.wikipedia.org/wiki/International_Article_Number_%28EAN%29)" + type: string + isrc: + description: "[International Standard Recording Code](http://en.wikipedia.org/wiki/International_Standard_Recording_Code)" + type: string + upc: + description: "[Universal Product Code](http://en.wikipedia.org/wiki/Universal_Product_Code)" + type: string + type: object + LinkedTrackObject: + externalDocs: + description: Find more info on the official Spotify Web API Reference + url: https://developer.spotify.com/documentation/web-api/reference/#object-linkedtrackobject + properties: + external_urls: + $ref: "#/components/schemas/ExternalUrlObject" + href: + description: A link to the Web API endpoint providing full details of the track. + type: string + id: + description: The [Spotify ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the track. + type: string + type: + description: 'The object type: "track".' + type: string + uri: + description: The [Spotify URI](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the track. + type: string + type: object + TrackRemovingDetails: + properties: + snapshot_id: + description: The playlist's snapshot ID against which you want to make the changes. The API will validate that the specified items exist and in the specified positions and make the changes, even if more recent changes have been made to the playlist. + type: string + tracks: + description: 'An array of objects containing [Spotify URIs](https://developer.spotify.com/spotify-documentation/web-api/#spotify-uris-and-ids) of the tracks or episodes to remove. For example: `{ "tracks": [{ "uri": "spotify:track:4iV5W9uYEdYUVa79Axb7Rh" },{ "uri": "spotify:track:1301WleyT98MSxVHPZCA6M" }] }`. A maximum of 100 objects can be sent at once.' + items: + type: string + type: array + required: + - tracks + type: object + TrackObject: + externalDocs: + description: Find more info on the official Spotify Web API Reference + url: https://developer.spotify.com/documentation/web-api/reference/#object-trackobject + properties: + album: + $ref: "#/components/schemas/SimplifiedAlbumObject" + artists: + description: The artists who performed the track. Each artist object includes a link in `href` to more detailed information about the artist. + items: + $ref: "#/components/schemas/ArtistObject" + type: array + available_markets: + description: A list of the countries in which the track can be played, identified by their [ISO 3166-1 alpha-2](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code. + items: + type: string + type: array + disc_number: + description: The disc number (usually `1` unless the album consists of more than one disc). + format: int32 + type: integer + duration_ms: + description: The track length in milliseconds. + format: int32 + type: integer + explicit: + description: Whether or not the track has explicit lyrics ( `true` = yes it does; `false` = no it does not OR unknown). + type: boolean + external_ids: + $ref: "#/components/schemas/ExternalIdObject" + external_urls: + $ref: "#/components/schemas/ExternalUrlObject" + href: + description: A link to the Web API endpoint providing full details of the track. + type: string + id: + description: The [Spotify ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the track. + type: string + is_local: + description: Whether or not the track is from a local file. + type: boolean + is_playable: + description: Part of the response when [Track Relinking](https://developer.spotify.com/documentation/general/guides/track-relinking-guide/) is applied. If `true` , the track is playable in the given market. Otherwise `false`. + type: boolean + linked_from: + $ref: "#/components/schemas/LinkedTrackObject" + name: + description: The name of the track. + type: string + popularity: + description: |- + The popularity of the track. The value will be between 0 and 100, with 100 being the most popular. + The popularity of a track is a value between 0 and 100, with 100 being the most popular. The popularity is calculated by algorithm and is based, in the most part, on the total number of plays the track has had and how recent those plays are. + Generally speaking, songs that are being played a lot now will have a higher popularity than songs that were played a lot in the past. Duplicate tracks (e.g. the same track from a single and an album) are rated independently. Artist and album popularity is derived mathematically from track popularity. Note that the popularity value may lag actual popularity by a few days: the value is not updated in real time. + format: int32 + type: integer + preview_url: + description: A link to a 30 second preview (MP3 format) of the track. Can be `null` + type: string + restrictions: + $ref: "#/components/schemas/TrackRestrictionObject" + track_number: + description: The number of the track. If an album has several discs, the track number is the number on the specified disc. + format: int32 + type: integer + type: + description: 'The object type: "track".' + type: string + uri: + description: The [Spotify URI](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the track. + type: string + type: object + TrackRestrictionObject: + externalDocs: + description: Find more info on the official Spotify Web API Reference + url: https://developer.spotify.com/documentation/web-api/reference/#object-trackrestrictionobject + properties: + reason: + description: |- + The reason for the restriction. Supported values: + + - `market` - The content item is not available in the given market. + - `product` - The content item is not available for the user's subscription type. + - `explicit` - The content item is explicit and the user's account is set to not play explicit content. + Additional reasons may be added in the future. **Note**: If you use this field, make sure that your application safely handles unknown values. + type: string + type: object + securitySchemes: + spotify_auth: + flows: + authorizationCode: + authorizationUrl: https://accounts.spotify.com/authorize + scopes: + app-remote-control: Remote control playback of Spotify. This scope is currently available to Spotify iOS and Android SDKs. + playlist-modify-private: Write access to a user's private playlists. + playlist-modify-public: Write access to a user's public playlists. + playlist-read-collaborative: Include collaborative playlists when requesting a user's playlists. + playlist-read-private: Read access to user's private playlists. + streaming: Control playback of a Spotify track. This scope is currently available to the Web Playback SDK. The user must have a Spotify Premium account. + ugc-image-upload: Write access to user-provided images. + user-follow-modify: Write/delete access to the list of artists and other users that the user follows. + user-follow-read: Read access to the list of artists and other users that the user follows. + user-library-modify: Write/delete access to a user's "Your Music" library. + user-library-read: Read access to a user's library. + user-modify-playback-state: Write access to a user’s playback state + user-read-currently-playing: Read access to a user’s currently playing content. + user-read-email: Read access to user’s email address. + user-read-playback-position: Read access to a user’s playback position in a content. + user-read-playback-state: Read access to a user’s player state. + user-read-private: Read access to user’s subscription details (type of user account). + user-read-recently-played: Read access to a user’s recently played tracks. + user-top-read: Read access to a user's top artists and tracks. + tokenUrl: https://accounts.spotify.com/api/token + type: oauth2 diff --git a/openapi/spotify/types.bal b/openapi/spotify/types.bal new file mode 100644 index 000000000..73f91ce32 --- /dev/null +++ b/openapi/spotify/types.bal @@ -0,0 +1,303 @@ +// Copyright (c) 2021, WSO2 Inc. (http://www.wso2.org) All Rights Reserved. +// +// WSO2 Inc. licenses this file to you under the Apache License, +// Version 2.0 (the "License"); you may not use this file except +// in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +public type PlayListDetails record { + boolean collaborative?; + string description?; + string name; + boolean 'public?; +}; + +public type UserPlayListDetails record { + string href?; + SimplifiedPlaylistObject[] items?; + int 'limit?; + string? next?; + int offset?; + string? previous?; + int total?; +}; + +public type PlaylistTrackInsertionDetails record { + int position?; + string[] uris?; +}; + +public type PlayListReorderDetails record { + int insert_before?; + int range_length?; + int range_start?; + string snapshot_id?; + string[] uris?; +}; + +public type PlaylistTrackDetails record { + string href?; + PlaylistTrackObject[] items?; + int 'limit?; + string? next?; + int offset?; + string? previous?; + int total?; +}; + +public type ChangePlayListDetails record { + boolean collaborative?; + string description?; + string name?; + boolean 'public?; +}; + +public type CurrentPlaylistDetails record { + string href?; + SimplifiedPlaylistObject[] items?; + int 'limit?; + string? next?; + int offset?; + string? previous?; + int total?; +}; + +public type PlaylistObject record { + boolean collaborative?; + string description?; + ExternalUrlObject external_urls?; + FollowersObject followers?; + string href?; + string id?; + ImageObject[] images?; + string name?; + PublicUserObject owner?; + boolean 'public?; + string snapshot_id?; + record { string href?; PlaylistTrackObject[] items?; int 'limit?; string? next?; int offset?; string? previous?; int total?;} tracks?; + string 'type?; + string uri?; +}; + +public type ImageObject record { + int height?; + string url?; + int width?; +}; + +public type SnapshotIdObject record { + string snapshot_id?; +}; + +public type ErrorResponseObject record { + ErrorObject _error?; +}; + +public type SimplifiedPlaylistObject record { + boolean collaborative?; + string description?; + ExternalUrlObject external_urls?; + string href?; + string id?; + ImageObject[] images?; + string name?; + PublicUserObject owner?; + boolean 'public?; + string snapshot_id?; + PlaylistTracksRefObject tracks?; + string 'type?; + string uri?; +}; + +public type PlaylistTrackObject record { + string added_at?; + PublicUserObject added_by?; + boolean is_local?; + anydata track?; +}; + +public type ExternalUrlObject record { + string spotify?; +}; + +public type FollowersObject record { + string? href?; + int total?; +}; + +public type PublicUserObject record { + string display_name?; + ExternalUrlObject external_urls?; + FollowersObject followers?; + string href?; + string id?; + ImageObject[] images?; + string 'type?; + string uri?; +}; + +public type ErrorObject record { + string message?; + int status?; +}; + +public type PlaylistTracksRefObject record { + string href?; + int total?; +}; + +public type EpisodeObject record { + string audio_preview_url?; + string description?; + int duration_ms?; + boolean explicit?; + ExternalUrlObject external_urls?; + string href?; + string html_description?; + string id?; + ImageObject[] images?; + boolean is_externally_hosted?; + boolean is_playable?; + string language?; + string[] languages?; + string name?; + string release_date?; + string release_date_precision?; + EpisodeRestrictionObject restrictions?; + ResumePointObject resume_point?; + SimplifiedShowObject show?; + string 'type?; + string uri?; +}; + +public type EpisodeRestrictionObject record { + string reason?; +}; + +public type ResumePointObject record { + boolean fully_played?; + int resume_position_ms?; +}; + +public type SimplifiedShowObject record { + string[] available_markets?; + CopyrightObject[] copyrights?; + string description?; + boolean explicit?; + ExternalUrlObject external_urls?; + string href?; + string html_description?; + string id?; + ImageObject[] images?; + boolean is_externally_hosted?; + string[] languages?; + string media_type?; + string name?; + string publisher?; + string 'type?; + string uri?; +}; + +public type CopyrightObject record { + string text?; + string 'type?; +}; + +public type SimplifiedArtistObject record { + ExternalUrlObject external_urls?; + string href?; + string id?; + string name?; + string 'type?; + string uri?; +}; + +public type SimplifiedAlbumObject record { + string album_group?; + string album_type?; + SimplifiedArtistObject[] artists?; + string[] available_markets?; + ExternalUrlObject external_urls?; + string href?; + string id?; + ImageObject[] images?; + string name?; + string release_date?; + string release_date_precision?; + AlbumRestrictionObject restrictions?; + int total_tracks?; + string 'type?; + string uri?; +}; + +public type AlbumRestrictionObject record { + string reason?; +}; + +public type ArtistObject record { + ExternalUrlObject external_urls?; + FollowersObject followers?; + string[] genres?; + string href?; + string id?; + ImageObject[] images?; + string name?; + int popularity?; + string 'type?; + string uri?; +}; + +public type ExternalIdObject record { + string ean?; + string isrc?; + string upc?; +}; + +public type LinkedTrackObject record { + ExternalUrlObject external_urls?; + string href?; + string id?; + string 'type?; + string uri?; +}; + +public type TrackRemovingDetails record { + string snapshot_id?; + string[] tracks; +}; + +public type TrackObject record { + SimplifiedAlbumObject album?; + ArtistObject[] artists?; + string[] available_markets?; + int disc_number?; + int duration_ms?; + boolean explicit?; + ExternalIdObject external_ids?; + ExternalUrlObject external_urls?; + string href?; + string id?; + boolean is_local?; + boolean is_playable?; + LinkedTrackObject linked_from?; + string name?; + int popularity?; + string preview_url?; + TrackRestrictionObject restrictions?; + int track_number?; + string 'type?; + string uri?; +}; + +public type TrackRestrictionObject record { + string reason?; +}; From 7596983fabd17b76f04adba26b47f5c3a0f99791 Mon Sep 17 00:00:00 2001 From: aneeshafedo Date: Sat, 12 Jun 2021 18:08:17 +0530 Subject: [PATCH 02/14] update openweathermap connector --- openapi/openweathermap/Package.md | 29 ++-- openapi/openweathermap/client.bal | 28 ++- openapi/openweathermap/openap.yaml | 138 ++++++++++++--- openapi/openweathermap/types.bal | 263 +++++++++++++++++++++-------- 4 files changed, 356 insertions(+), 102 deletions(-) diff --git a/openapi/openweathermap/Package.md b/openapi/openweathermap/Package.md index faccc1c46..6229c5dd4 100644 --- a/openapi/openweathermap/Package.md +++ b/openapi/openweathermap/Package.md @@ -1,5 +1,21 @@ Connects to Openweathermap API from Ballerina. +## Module Overview + +The Open Weather Map connector consume the data exposed in [openweathermap.org](https://openweathermap.org/). It is currently supporting the following operations. + +### Get Current Weather Data + +Can be used to access current weather data for any location on Earth including over 200,000 cities. + +For more details please check [here](https://openweathermap.org/current) + +### Get Weather Forecast + +Can be used to access current weather, minute forecast for 1 hour, hourly forecast for 48 hours, daily forecast for 7 days and government weather alerts. + +For more details please check [here](https://openweathermap.org/api/one-call-api) + ## Compatibility | Ballerina Language Versions | OpenWeatherMap API | @@ -35,17 +51,8 @@ Then provide the obtained API Key in client configuration. }; ``` - -## Module Overview - -The Open Weather Map connector consume the data exposed in [openweathermap.org](https://openweathermap.org/). It is currently supporting the following operations. - ### Get Current Weather Data -Can be used to access current weather data for any location on Earth including over 200,000 cities. - -For more details please check [here](https://openweathermap.org/current) - ```ballerina CurrentWeatherData result = check weatherclient->getCurretWeatherData("Colombo"); log:printInfo("Colombo Current Weather data : " + result.toString()); @@ -54,10 +61,6 @@ For more details please check [here](https://openweathermap.org/current) ### Get Weather Forecast -Can be used to access current weather, minute forecast for 1 hour, hourly forecast for 48 hours, daily forecast for 7 days and government weather alerts. - -For more details please check [here](https://openweathermap.org/api/one-call-api) - ```ballerina CurrentWeatherData result = check weatherclient->getWeatherForecast(lat = "6.93194", lon = "79.847778"); log:printInfo("Colombo Weather Forecast : " + result.toString()); diff --git a/openapi/openweathermap/client.bal b/openapi/openweathermap/client.bal index 23a91766f..c024ab6d5 100644 --- a/openapi/openweathermap/client.bal +++ b/openapi/openweathermap/client.bal @@ -1,4 +1,4 @@ -// Copyright (c) 2021, WSO2 Inc. (http://www.wso2.org) All Rights Reserved. +// Copyright (c) 2021 WSO2 Inc. (http://www.wso2.org) All Rights Reserved. // // WSO2 Inc. licenses this file to you under the Apache License, // Version 2.0 (the "License"); you may not use this file except @@ -22,6 +22,9 @@ public type ApiKeysConfig record { map apiKeys; }; +# Client endpoint for OpenWeatherMap API +# +# + clientEp - Connector http endpoint @display {label: "Open Weather Client"} public client class Client { http:Client clientEp; @@ -31,6 +34,17 @@ public client class Client { self.clientEp = httpEp; self.apiKeys = apiKeyConfig.apiKeys; } + # Access current weather data for any location. + # + # + q - City name, or city name and country code. For the query value, type the city name and optionally the country code divided by comma; use ISO 3166 country codes. + # + id - City ID. Example: `2172797`. The List of city IDs can be downloaded [here](http://bulk.openweathermap.o/sample/). + # + lat - Latitude + # + lon - Longtitude + # + zip - Zip code. Search by zip code. Example: 95050,us. + # + units - Units of measurement. + # + lang - Language + # + mode - Format of response. Possible values are `xml` and `html`. If mode parameter is empty the format is `json` by default. + # + return - Current weather data of the given location @display {label: "Current Weather"} remote isolated function getCurretWeatherData(@display {label: "CityName or StateCode or CountryCode"} string? q = (), @display {label: "City Id"} string? id = (), @display {label: "Latitude"} string? lat = (), @display {label: "Longitude"} string? lon = (), @display {label: "Zip Code"} string? zip = (), @display {label: "Units"} string? units = (), @display {label: "Language"} string? lang = (), @display {label: "Mode"} string? mode = ()) returns CurrentWeatherData|error { string path = string `/weather`; @@ -39,6 +53,14 @@ public client class Client { CurrentWeatherData response = check self.clientEp-> get(path, targetType = CurrentWeatherData); return response; } + # Access to current weather, minute forecast for 1 hour, hourly forecast for 48 hours, daily forecast for 7 days and government weather alerts. + # + # + lat - Latitude + # + lon - Longtitude + # + exclude - Exclude parts of the weather data from the API response. It should be a comma-delimited list (without spaces). + # + units - Units of measurement. + # + lang - Language + # + return - Weather forecast of the given location @display {label: "Weather Forecast"} remote isolated function getWeatherForecast(@display {label: "Latitude"} string lat, @display {label: "Longtitude"} string lon, @display {label: "Exclude"} string? exclude = (), @display {label: "Units"} string? units = (), @display {label: "Language"} string? lang = ()) returns WeatherForecast|error { string path = string `/onecall`; @@ -49,6 +71,10 @@ public client class Client { } } +# Generate query path with query parameter. +# +# + queryParam - Query parameter map +# + return - Returns generated Path or error at failure of client initialization isolated function getPathForQueryParam(map queryParam) returns string { string[] param = []; param[param.length()] = "?"; diff --git a/openapi/openweathermap/openap.yaml b/openapi/openweathermap/openap.yaml index 1ec6c58cb..4f696fdf4 100644 --- a/openapi/openweathermap/openap.yaml +++ b/openapi/openweathermap/openap.yaml @@ -2,7 +2,7 @@ openapi: "3.0.1" info: title: "OpenWeatherMap API" - description: "Get current weather, daily forecast for 16 days, and 3-hourly forecast 5 days for your city. Helpful stats, graphics, and this day in history charts are available for your reference. Interactive maps show precipitation, clouds, pressure, wind around your location stations. Data is available in JSON, XML, or HTML format. **Note**: This sample Swagger file covers the `current` endpoint only from the OpenWeatherMap API.

**Note**: All parameters are optional, but you must select at least one parameter. Calling the API by city ID (using the `id` parameter) will provide the most precise location results." + description: "Client endpoint for OpenWeatherMap API" version: "2.5.2" termsOfService: "https://openweathermap.org/terms" contact: @@ -23,7 +23,7 @@ paths: tags: - Current Weather Data summary: "Call current weather data for one location" - description: "Access current weather data for any location on Earth including over 200,000 cities! Current weather is frequently updated based on global models and data from more than 40,000 weather stations." + description: "Access current weather data for any location." operationId: getCurretWeatherData parameters: - $ref: '#/components/parameters/cityName' @@ -36,10 +36,9 @@ paths: - $ref: '#/components/parameters/mode' x-display: label: "Current Weather" - responses: 200: - description: Successful response + description: Current weather data of the given location content: application/json: schema: @@ -56,7 +55,7 @@ paths: get: tags: - Weather Forecast - summary: "Weather forcast for for one location" + summary: "Provide weather forecast for any geographical coordinates" description: "Access to current weather, minute forecast for 1 hour, hourly forecast for 48 hours, daily forecast for 7 days and government weather alerts." operationId: getWeatherForecast parameters: @@ -76,7 +75,7 @@ paths: type: string x-display: label: Longtitude - - description: "By using this parameter you can exclude some parts of the weather data from the API response. It should be a comma-delimited list (without spaces)." + - description: "Exclude parts of the weather data from the API response. It should be a comma-delimited list (without spaces)." in: query name: exclude required: false @@ -90,7 +89,7 @@ paths: type: string x-display: label: Exclude - - description: "Units of measurement. standard, metric and imperial units are available. If you do not use the units parameter, standard units will be applied by default." + - description: 'Units of measurement.' in: query name: units required: false @@ -98,7 +97,7 @@ paths: type: string x-display: label: Units - - description: "You can use the lang parameter to get the output in your language." + - description: 'Language' in: query name: lang required: false @@ -110,7 +109,7 @@ paths: label: "Weather Forecast" responses: 200: - description: Successful response + description: Weather forecast of the given location content: application/json: schema: @@ -130,6 +129,8 @@ security: tags: - name: Current Weather Data description: "Get current weather details" + - name: Weather Forecast + description: "Get data related to weather forecast" externalDocs: description: API Documentation @@ -140,7 +141,7 @@ components: cityName: name: q in: query - description: "**City name**. *Example: London*. You can call by city name, or by city name and country code. The API responds with a list of results that match a searching word. For the query value, type the city name and optionally the country code divided by comma; use ISO 3166 country codes." + description: "City name, or city name and country code. For the query value, type the city name and optionally the country code divided by comma; use ISO 3166 country codes." schema: type: string x-display: @@ -148,7 +149,7 @@ components: id: name: id in: query - description: "**City ID**. *Example: `2172797`*. You can call by city ID. API responds with exact result. The List of city IDs can be downloaded [here](http://bulk.openweathermap.org/sample/). You can include multiple cities in parameter — just separate them by commas. The limit of locations is 20. *Note: A single ID counts as a one API call. So, if you have city IDs. it's treated as 3 API calls.*" + description: "City ID. Example: `2172797`. The List of city IDs can be downloaded [here](http://bulk.openweathermap.o/sample/)." schema: type: string x-display: @@ -156,7 +157,7 @@ components: lat: name: lat in: query - description: "**Latitude**. *Example: 35*. The latitude cordinate of the location of your interest. Must use with `lon`." + description: "Latitude" schema: type: string x-display: @@ -165,7 +166,7 @@ components: lon: name: lon in: query - description: "**Longitude**. *Example: 139*. Longitude cordinate of the location of your interest. Must use with `lat`." + description: "Longtitude" schema: type: string x-display: @@ -174,7 +175,7 @@ components: zip: name: zip in: query - description: "**Zip code**. Search by zip code. *Example: 95050,us*. Please note if country is not specified then the search works for USA as a default." + description: "Zip code. Search by zip code. Example: 95050,us." schema: type: string x-display: @@ -183,7 +184,7 @@ components: units: name: units in: query - description: '**Units**. *Example: imperial*. Possible values: `standard`, `metric`, and `imperial`. When you do not use units parameter, format is `standard` by default.' + description: 'Units of measurement.' schema: type: string enum: [standard, metric, imperial] @@ -194,7 +195,7 @@ components: lang: name: lang in: query - description: '**Language**. *Example: en*. You can use lang parameter to get the output in your language. We support the following languages that you can use with the corresponded lang values: Arabic - `ar`, Bulgarian - `bg`, Catalan - `ca`, Czech - `cz`, German - `de`, Greek - `el`, English - `en`, Persian (Farsi) - `fa`, Finnish - `fi`, French - `fr`, Galician - `gl`, Croatian - `hr`, Hungarian - `hu`, Italian - `it`, Japanese - `ja`, Korean - `kr`, Latvian - `la`, Lithuanian - `lt`, Macedonian - `mk`, Dutch - `nl`, Polish - `pl`, Portuguese - `pt`, Romanian - `ro`, Russian - `ru`, Swedish - `se`, Slovak - `sk`, Slovenian - `sl`, Spanish - `es`, Turkish - `tr`, Ukrainian - `ua`, Vietnamese - `vi`, Chinese Simplified - `zh_cn`, Chinese Traditional - `zh_tw`.' + description: 'Language' schema: type: string enum: [ar, bg, ca, cz, de, el, en, fa, fi, fr, gl, hr, hu, it, ja, kr, la, lt, mk, nl, pl, pt, ro, ru, se, sk, sl, es, tr, ua, vi, zh_cn, zh_tw] @@ -205,7 +206,7 @@ components: mode: name: mode in: query - description: "**Mode**. *Example: html*. Determines format of response. Possible values are `xml` and `html`. If mode parameter is empty the format is `json` by default." + description: "Format of response. Possible values are `xml` and `html`. If mode parameter is empty the format is `json` by default." schema: type: string enum: [json, xml, html] @@ -215,109 +216,153 @@ components: schemas: WeatherForecast: type: object + description: "Weather forecast data" properties: lat: type: number + description: Latitude lon: type: number + description: Longtitude timezone: type: string + description: Timezone name for the requested location timezone_offset: type: number + description: Shift in seconds from UTC current: $ref: '#/components/schemas/ForecastCurrent' + description: Current weather data minutely: type: array items: $ref: '#/components/schemas/Minutely' + description: Minutely weather forecast hourly: type: array items: $ref: '#/components/schemas/Hourly' + description: Hourly weather forecast daily: type: array items: $ref: '#/components/schemas/Daily' + description: Daily weather forecast alerts: type: array items: $ref: '#/components/schemas/Alerts' + description: Government weather alerts Alerts: type: object properties: sender_name: type: string + description: Name of the alert source. event: type: string + description: Alert event name description: type: string + description: Description of the alert start: type: number + description: Date and time of the start of the alert, Unix, UTC end: type: number + description: Date and time of the end of the alert, Unix, UTC tags: type: array items: type: string + description: Tags related to alerts Temp: type: object + description: Temperature data properties: day: type: number + description: Day temperature. min: type: number + description: Min daily temperature. max: type: number + description: Max daily temperature. night: type: number + description: Night temperature. eve: type: number + description: Evening temperature. morn: type: number + description: Morning temperature FeelsLike: type: object + description: "Human perception of temperature each time of the day" properties: day: type: number + description: Day temperature. night: type: number + description: Night temperature. eve: type: number + description: Evening temperature. morn: type: number + description: Morning temperature. Daily: type: object + description: "Daily forecast weather data API response" properties: dt: type: number + description: Time of the forecasted data, Unix, UTC temp: $ref: '#/components/schemas/Temp' + description: Temperature data feels_like: $ref: '#/components/schemas/FeelsLike' + description: "Temperature. This accounts for the human perception of weather." moonrise: type: number + description: The time of when the moon rises for this day, Unix, UTC moonset: type: number + description: The time of when the moon sets for this day, Unix, UTC moon_phase: type: number + description: "Moon phase. 0 and 1 are 'new moon', 0.25 is 'first quarter moon', 0.5 is 'full moon' and 0.75 is 'last quarter moon." pressure: type: number + description: "Atmospheric pressure on the sea level, hPa" humidity: type: number + description: Humidity, % dew_point: type: number + description: "Atmospheric temperature below which water droplets begin to condense and dew can form." uvi: type: number + description: The maximum value of UV index for the day clouds: type: number + description: Cloudiness, % visibility: type: number + description: Visibility of the atmosphere wind_deg: type: number + description: Wind direction, degrees (meteorological) wind_gust: type: number + description: "(where available) Wind gust. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour." pop: type: number + description: Probability of precipitation weather: type: array items: @@ -325,33 +370,47 @@ components: description: (more info Weather condition codes) rain: type: number + description: where available) Precipitation volume, mm Hourly: type: object + description: "Hourly forecast weather data API response" properties: dt: type: number + description: Time of the forecasted data, Unix, UTC temp: type: number + description: "Temperature. Units – default: kelvin, metric: Celsius, imperial: Fahrenheit." feels_like: type: number + description: "Temperature. This accounts for the human perception of weather." pressure: type: number + description: "Atmospheric pressure on the sea level, hPa" humidity: type: number + description: "Humidity, %" dew_point: type: number + description: "Atmospheric temperature below which water droplets begin to condense and dew can form." uvi: type: number + description: "UV index" clouds: type: number + description: "Cloudiness, %" visibility: type: number + description: "Average visibility, metres" wind_deg: type: number + description: "Wind direction, degrees (meteorological)" wind_gust: type: number + description: "(where available) Wind gust. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour." pop: type: number + description: "Probability of precipitatio" weather: type: array items: @@ -359,42 +418,60 @@ components: description: (more info Weather condition codes) rain: $ref: '#/components/schemas/Rain' + description: Nature of the rain Minutely: type: object properties: dt: type: number + description: Time of the forecasted data, unix, UTC precipitation: type: number + description: Precipitation volume, mm + description: "Minute forecast weather data API response" ForecastCurrent: type: object + description: Current weather data API response properties: dt: type: number + description: Current time, Unix, UTC sunrise: type: number + description: Sunrise time, Unix, UTC sunset: type: number + description: Sunset time, Unix, UTC temp: type: number + description: "Temperature. Units - default: kelvin, metric: Celsius, imperial: Fahrenheit." feels_like: type: number + description: "Temperature. This temperature parameter accounts for the human perception of weather." pressure: type: number + description: "Atmospheric pressure on the sea level, hPa" humidity: type: number + description: "Humidity, %" dew_point: type: number + description: "Atmospheric temperature below which water droplets begin to condense and dew can form." uvi: type: number + description: "Current UV index" clouds: type: number + description: "Cloudiness, %" visibility: type: number + description: Average visibility, metres wind_speed: type: number + description: "Wind speed. Wind speed. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour." wind_deg: type: number + description: Wind direction, degrees (meteorological) weather: type: array items: @@ -402,14 +479,18 @@ components: description: (more info Weather condition codes) rain: $ref: '#/components/schemas/Rain' + description: Nature of the rain snow: $ref: '#/components/schemas/Snow' + description: Nature of the Snow CurrentWeatherData: title: Successful response + description: Current weather data type: object properties: coord: $ref: '#/components/schemas/Coord' + description: City geo location weather: type: array items: @@ -421,18 +502,23 @@ components: example: cmc stations main: $ref: '#/components/schemas/Main' + description: Basic weather data visibility: type: integer description: Visibility, meter example: 16093 wind: $ref: '#/components/schemas/Wind' + description: Nature of the wind clouds: $ref: '#/components/schemas/Clouds' + description: Nature of the clouds rain: $ref: '#/components/schemas/Rain' + description: Nature of the rain snow: $ref: '#/components/schemas/Snow' + description: Nature of the snow dt: type: integer description: Time of data calculation, unix, UTC @@ -440,6 +526,7 @@ components: example: 1435658272 sys: $ref: '#/components/schemas/Sys' + description: Internal data id: type: integer description: City ID @@ -448,6 +535,7 @@ components: name: type: string example: Cairns + description: City name cod: type: integer description: Internal parameter @@ -456,18 +544,20 @@ components: Coord: title: Coord type: object + description: City geo location properties: lon: type: number - description: City geo location, longitude + description: Longitude example: 145.77000000000001 lat: type: number - description: City geo location, latitude + description: Latitude example: -16.920000000000002 Weather: title: Weather type: object + description: Weather properties: id: type: integer @@ -489,6 +579,7 @@ components: Main: title: Main type: object + description: Basic weather data properties: temp: type: number @@ -506,11 +597,11 @@ components: example: 83 temp_min: type: number - description: 'Minimum temperature at the moment. This is deviation from current temp that is possible for large cities and megalopolises geographically expanded (use these parameter optionally). Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit.' + description: 'Minimum temperature at the moment.' example: 289.81999999999999 temp_max: type: number - description: 'Maximum temperature at the moment. This is deviation from current temp that is possible for large cities and megalopolises geographically expanded (use these parameter optionally). Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit.' + description: 'Maximum temperature at the moment.' example: 295.37 sea_level: type: number @@ -523,6 +614,7 @@ components: Wind: title: Wind type: object + description: Nature of the wind properties: speed: type: number @@ -536,6 +628,7 @@ components: Clouds: title: Clouds type: object + description: Nature of the clounds properties: all: type: integer @@ -545,6 +638,7 @@ components: Rain: title: Rain type: object + description: Nature of the rain properties: 3h: type: integer @@ -554,6 +648,7 @@ components: Snow: title: Snow type: object + description: Snow properties: 3h: type: number @@ -562,6 +657,7 @@ components: Sys: title: Sys type: object + description: System data properties: type: type: integer diff --git a/openapi/openweathermap/types.bal b/openapi/openweathermap/types.bal index 4df37f532..082f22d7c 100644 --- a/openapi/openweathermap/types.bal +++ b/openapi/openweathermap/types.bal @@ -1,4 +1,4 @@ -// Copyright (c) 2021, WSO2 Inc. (http://www.wso2.org) All Rights Reserved. +// Copyright (c) 2021 WSO2 Inc. (http://www.wso2.org) All Rights Reserved. // // WSO2 Inc. licenses this file to you under the Apache License, // Version 2.0 (the "License"); you may not use this file except @@ -13,165 +13,294 @@ // KIND, either express or implied. See the License for the // specific language governing permissions and limitations // under the License. + +# Weather forecast data public type WeatherForecast record { - float lat?; - float lon?; + # Latitude + decimal lat?; + # Longtitude + decimal lon?; + # Timezone name for the requested location string timezone?; - float timezone_offset?; + # Shift in seconds from UTC + decimal timezone_offset?; + # Current weather data ForecastCurrent current?; + # Minutely weather forecast Minutely[] minutely?; + # Hourly weather forecast Hourly[] hourly?; + # Daily weather forecast Daily[] daily?; + # Government weather alerts Alerts[] alerts?; }; public type Alerts record { + # Name of the alert source. string sender_name?; + # Alert event name string event?; + # Description of the alert string description?; - float 'start?; - float end?; + # Date and time of the start of the alert, Unix, UTC + decimal 'start?; + # Date and time of the end of the alert, Unix, UTC + decimal end?; + # Tags related to alerts string[] tags?; }; +# Temperature data public type Temp record { - float day?; - float min?; - float max?; - float night?; - float eve?; - float morn?; + # Day temperature. + decimal day?; + # Min daily temperature. + decimal min?; + # Max daily temperature. + decimal max?; + # Night temperature. + decimal night?; + # Evening temperature. + decimal eve?; + # Morning temperature + decimal morn?; }; +# Human perception of temperature each time of the day public type FeelsLike record { - float day?; - float night?; - float eve?; - float morn?; + # Day temperature. + decimal day?; + # Night temperature. + decimal night?; + # Evening temperature. + decimal eve?; + # Morning temperature. + decimal morn?; }; +# Daily forecast weather data API response public type Daily record { - float dt?; + # Time of the forecasted data, Unix, UTC + decimal dt?; + # Temperature data Temp temp?; + # Human perception of temperature each time of the day FeelsLike feels_like?; - float moonrise?; - float moonset?; - float moon_phase?; - float pressure?; - float humidity?; - float dew_point?; - float uvi?; - float clouds?; - float visibility?; - float wind_deg?; - float wind_gust?; - float pop?; + # The time of when the moon rises for this day, Unix, UTC + decimal moonrise?; + # The time of when the moon sets for this day, Unix, UTC + decimal moonset?; + # Moon phase. 0 and 1 are 'new moon', 0.25 is 'first quarter moon', 0.5 is 'full moon' and 0.75 is 'last quarter moon. + decimal moon_phase?; + # Atmospheric pressure on the sea level, hPa + decimal pressure?; + # Humidity, % + decimal humidity?; + # Atmospheric temperature below which water droplets begin to condense and dew can form. + decimal dew_point?; + # The maximum value of UV index for the day + decimal uvi?; + # Cloudiness, % + decimal clouds?; + # Visibility of the atmosphere + decimal visibility?; + # Wind direction, degrees (meteorological) + decimal wind_deg?; + # (where available) Wind gust. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour. + decimal wind_gust?; + # Probability of precipitation + decimal pop?; + # (more info Weather condition codes) Weather[] weather?; - float rain?; + # where available) Precipitation volume, mm + decimal rain?; }; +# Hourly forecast weather data API response public type Hourly record { - float dt?; - float temp?; - float feels_like?; - float pressure?; - float humidity?; - float dew_point?; - float uvi?; - float clouds?; - float visibility?; - float wind_deg?; - float wind_gust?; - float pop?; + # Time of the forecasted data, Unix, UTC + decimal dt?; + # Temperature. Units – default: kelvin, metric: Celsius, imperial: Fahrenheit. + decimal temp?; + # Temperature. This accounts for the human perception of weather. + decimal feels_like?; + # Atmospheric pressure on the sea level, hPa + decimal pressure?; + # Humidity, % + decimal humidity?; + # Atmospheric temperature below which water droplets begin to condense and dew can form. + decimal dew_point?; + # UV index + decimal uvi?; + # Cloudiness, % + decimal clouds?; + # Average visibility, metres + decimal visibility?; + # Wind direction, degrees (meteorological) + decimal wind_deg?; + # (where available) Wind gust. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour. + decimal wind_gust?; + # Probability of precipitatio + decimal pop?; + # (more info Weather condition codes) Weather[] weather?; + # Where available) Precipitation volume, mm Rain rain?; }; +# Minute forecast weather data API response public type Minutely record { - float dt?; - float precipitation?; + # Time of the forecasted data, unix, UTC + decimal dt?; + # Precipitation volume, mm + decimal precipitation?; }; +# Current weather data API response public type ForecastCurrent record { - float dt?; - float sunrise?; - float sunset?; - float temp?; - float feels_like?; - float pressure?; - float humidity?; - float dew_point?; - float uvi?; - float clouds?; - float visibility?; - float wind_speed?; - float wind_deg?; + # Current time, Unix, UTC + decimal dt?; + # Sunrise time, Unix, UTC + decimal sunrise?; + # Sunset time, Unix, UTC + decimal sunset?; + # Temperature. Units - default: kelvin, metric: Celsius, imperial: Fahrenheit. + decimal temp?; + # Temperature. This temperature parameter accounts for the human perception of weather. + decimal feels_like?; + # Atmospheric pressure on the sea level, hPa + decimal pressure?; + # Humidity, % + decimal humidity?; + # Atmospheric temperature below which water droplets begin to condense and dew can form. + decimal dew_point?; + # Current UV index + decimal uvi?; + # Cloudiness, % + decimal clouds?; + # Average visibility, metres + decimal visibility?; + # Wind speed. Wind speed. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour. + decimal wind_speed?; + # Wind direction, degrees (meteorological) + decimal wind_deg?; + # (more info Weather condition codes) Weather[] weather?; + # where available) Precipitation volume, mm Rain rain?; + # Nature of the Snow Snow snow?; }; +# Current weather data public type CurrentWeatherData record { + # City geo location Coord coord?; + # (more info Weather condition codes) Weather[] weather?; + # Internal parameter string base?; + # Basic weather data Main main?; + # Visibility, meter int visibility?; + # Nature of the wind Wind wind?; + # Nature of the clouds Clouds clouds?; + # Nature of the rain Rain rain?; + # Nature of the snow Snow snow?; + # Time of data calculation, unix, UTC int dt?; + # Internal data Sys sys?; + # City ID int id?; + # City name string name?; + # Internal parameter int cod?; }; +# City geo location public type Coord record { - float lon?; - float lat?; + # Longitude + decimal lon?; + # Latitude + decimal lat?; }; +# Weather public type Weather record { + # Weather condition id int id?; + # Group of weather parameters (Rain, Snow, Extreme etc.) string main?; + # Weather condition within the group string description?; + # Weather icon id string icon?; }; +# Basic weather data public type Main record { - float temp?; + # Temperature. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit. + decimal temp?; + # Atmospheric pressure (on the sea level, if there is no sea_level or grnd_level data), hPa int pressure?; + # Humidity, % int humidity?; - float temp_min?; - float temp_max?; - float sea_level?; - float grnd_level?; + # Minimum temperature at the moment. + decimal temp_min?; + # Maximum temperature at the moment. + decimal temp_max?; + # Atmospheric pressure on the sea level, hPa + decimal sea_level?; + # Atmospheric pressure on the ground level, hPa + decimal grnd_level?; }; +# Nature of the wind public type Wind record { - float speed?; + # Wind speed. Unit Default: meter/sec, Metric: meter/sec, Imperial: miles/hour. + decimal speed?; + # Wind direction, degrees (meteorological) int deg?; }; +# Nature of the clounds public type Clouds record { + # Cloudiness, % int 'all?; }; +# Nature of the rain public type Rain record { + # Rain volume for the last 3 hours int '\3h?; }; +# Snow public type Snow record { - float '\3h?; + # Snow volume for the last 3 hours + decimal '\3h?; }; +# System data public type Sys record { + # Internal parameter int 'type?; + # Internal parameter int id?; - float message?; + # Internal parameter + decimal message?; + # Country code (GB, JP etc.) string country?; + # Sunrise time, unix, UTC int sunrise?; + # Sunset time, unix, UTC int sunset?; }; From 6a182a13d6f8e4699b0a763edca24c36efff3530 Mon Sep 17 00:00:00 2001 From: aneeshafedo Date: Sat, 12 Jun 2021 18:09:29 +0530 Subject: [PATCH 03/14] update covid19 connector --- openapi/covid19/client.bal | 76 ++++++++- openapi/covid19/openapi.yaml | 314 ++++++++++++++++++++--------------- openapi/covid19/types.bal | 299 +++++++++++++++++++++++---------- 3 files changed, 464 insertions(+), 225 deletions(-) diff --git a/openapi/covid19/client.bal b/openapi/covid19/client.bal index fd61fd846..c495f7287 100644 --- a/openapi/covid19/client.bal +++ b/openapi/covid19/client.bal @@ -1,4 +1,4 @@ -// Copyright (c) 2021, WSO2 Inc. (http://www.wso2.org) All Rights Reserved. +// Copyright (c) 2021 WSO2 Inc. (http://www.wso2.org) All Rights Reserved. // // WSO2 Inc. licenses this file to you under the Apache License, // Version 2.0 (the "License"); you may not use this file except @@ -18,6 +18,9 @@ import ballerina/http; import ballerina/url; import ballerina/lang.'string; +# Client endpoint for Novel Covid19 API - disease.sh +# +# + clientEp - Connector http endpoint @display {label: "Covid19 Client"} public client class Client { http:Client clientEp; @@ -25,6 +28,12 @@ public client class Client { http:Client httpEp = check new (serviceUrl, clientConfig); self.clientEp = httpEp; } + # Get global COVID-19 totals for today, yesterday and two days ago + # + # + yesterday - Queries data reported a day ago + # + twoDaysAgo - Queries data reported two days ago + # + allowNull - By default, value is 0. This allows nulls to be returned + # + return - Global Covid-19 status @display {label: "Global Status"} remote isolated function getGlobalStatus(@display {label: "Yesterday"} string? yesterday = (), @display {label: "Two Days Ago"} string? twoDaysAgo = (), @display {label: "Allow Null"} string? allowNull = ()) returns CovidAll|error { string path = string `/v3/covid-19/all`; @@ -33,6 +42,12 @@ public client class Client { CovidAll response = check self.clientEp-> get(path, targetType = CovidAll); return response; } + # Get COVID-19 totals for specific US State(s) + # + # + states - State name or comma separated names spelled correctly + # + yesterday - Queries data reported a day ago + # + allowNull - By default, value is 0. This allows nulls to be returned + # + return - Covid-19 status of the given US state @display {label: "USA State Status"} remote isolated function getUSAStatusByState(@display {label: "State Name"} string states, @display {label: "Yesterday"} string? yesterday = (), @display {label: "Allow Null"} string? allowNull = ()) returns CovidState|error { string path = string `/v3/covid-19/states/${states}`; @@ -41,6 +56,14 @@ public client class Client { CovidState response = check self.clientEp-> get(path, targetType = CovidState); return response; } + # Get COVID-19 totals for a specific continent + # + # + continent - Continent name + # + yesterday - Queries data reported a day ago + # + twoDaysAgo - Queries data reported two days ago + # + strict - Setting to false gives you the ability to fuzzy search continents (i.e. Oman vs. rOMANia) + # + allowNull - By default, value is 0. This allows nulls to be returned + # + return - Covid-19 status of the given continent @display {label: "Continent Status"} remote isolated function getStatusByContinent(@display {label: "Continent"} string continent, @display {label: "Yesterday"} string? yesterday = (), @display {label: "Two Days Ago"} string? twoDaysAgo = (), @display {label: "Strict"} string? strict = (), @display {label: "Allow Null"} string? allowNull = ()) returns CovidContinent|error { string path = string `/v3/covid-19/continents/${continent}`; @@ -49,6 +72,14 @@ public client class Client { CovidContinent response = check self.clientEp-> get(path, targetType = CovidContinent); return response; } + # Get COVID-19 totals for a specific country + # + # + country - Country name, iso2, iso3, or country ID code + # + yesterday - Queries data reported a day ago + # + twoDaysAgo - Queries data reported two days ago + # + strict - Setting to false gives you the ability to fuzzy search countries (i.e. Oman vs. rOMANia) + # + allowNull - By default, value is 0. This allows nulls to be returned + # + return - Covid-19 status of the given country @display {label: "Country Status"} remote isolated function getStatusByCountry(@display {label: "Country"} string country, @display {label: "Yesterday"} string? yesterday = (), @display {label: "Two Days Ago"} string? twoDaysAgo = (), @display {label: "Strict"} string? strict = (), @display {label: "Allow Null"} string? allowNull = ()) returns CovidCountry|error { string path = string `/v3/covid-19/countries/${country}`; @@ -57,6 +88,10 @@ public client class Client { CovidCountry response = check self.clientEp-> get(path, targetType = CovidCountry); return response; } + # Get global accumulated COVID-19 time series data + # + # + lastdays - Number of days to return. Use 'all' for the full data set (e.g. 15, all, 24) + # + return - Global accumulated COVID-19 time series data @display {label: "Global Status By Time Series"} remote isolated function getGlobalStatusInTimeSeries(@display {label: "Number Of Days"} string? lastdays = ()) returns CovidHistoricalAll|error { string path = string `/v3/covid-19/historical/all`; @@ -65,14 +100,25 @@ public client class Client { CovidHistoricalAll response = check self.clientEp-> get(path, targetType = CovidHistoricalAll); return response; } + # Get COVID-19 time series data for a specific country + # + # + country - Country name, iso2, iso3, or country ID code + # + lastdays - Number of days to return. Use 'all' for the full data set (e.g. 15, all, 24) + # + return - COVID-19 related time series for the given country @display {label: "Country Status By Time Series"} - remote isolated function getTimeSeriesBycountry(@display {label: "Country"} string country, @display {label: "Number Of Days"} string? lastdays = ()) returns CovidHistoricalCountry|error { + remote isolated function getTimeSeriesbycountry(@display {label: "Country"} string country, @display {label: "Number Of Days"} string? lastdays = ()) returns CovidHistoricalCountry|error { string path = string `/v3/covid-19/historical/${country}`; map queryParam = {lastdays: lastdays}; path = path + getPathForQueryParam(queryParam); CovidHistoricalCountry response = check self.clientEp-> get(path, targetType = CovidHistoricalCountry); return response; } + # Get COVID-19 time series data for a specific province in a country + # + # + country - Country name, iso2, iso3, or country ID code + # + province - Province name. All available names can be found in the /v3/covid-19/historical/{query} endpoint + # + lastdays - Number of days to return. Use 'all' for the full data set (e.g. 15, all, 24) + # + return - COVID-19 related time series for the given province @display {label: "Province Status By Time Seires"} remote isolated function getTimeSeriesByProvince(@display {label: "Country"} string country, @display {label: "Province"} string province, @display {label: "Number of Days"} string? lastdays = ()) returns CovidHistoricalProvince|error { string path = string `/v3/covid-19/historical/${country}/${province}`; @@ -81,30 +127,46 @@ public client class Client { CovidHistoricalProvince response = check self.clientEp-> get(path, targetType = CovidHistoricalProvince); return response; } + # Get vaccine trial data from RAPS (Regulatory Affairs Professional Society). + # + # + return - Vaccine trial data @display {label: "Vaccine Trial Data"} remote isolated function getVaccineTrialData() returns Vaccines|error { string path = string `/v3/covid-19/vaccine`; Vaccines response = check self.clientEp-> get(path, targetType = Vaccines); return response; } + # Get total global COVID-19 Vaccine doses administered. + # + # + lastdays - Number of days to return. Use 'all' for the full data set (e.g. 15, all, 24) + # + return - Vaccine coverage data @display {label: "Global Vaccine Administration"} - remote isolated function getTotalGlobalVaccineDosesAdministered(@display {label: "Number of Days"} string? lastdays = (), @display {label: "Full Data"} string? fullData = ()) returns VaccineCoverage|error { + remote isolated function getTotalGlobalVaccineDosesAdministered(@display {label: "Number of Days"} string? lastdays = ()) returns SimpleVaccineTimeline|error { string path = string `/v3/covid-19/vaccine/coverage`; - map queryParam = {lastdays: lastdays, fullData: fullData}; + map queryParam = {lastdays: lastdays}; path = path + getPathForQueryParam(queryParam); - VaccineCoverage response = check self.clientEp-> get(path, targetType = VaccineCoverage); + SimpleVaccineTimeline response = check self.clientEp-> get(path, targetType = SimpleVaccineTimeline); return response; } + # Get COVID-19 vaccine doses administered for a country that has reported vaccination rollout. + # + # + country - Country name, iso2, iso3 + # + lastdays - Number of days to return. Use 'all' for the full data set (e.g. 15, all, 24) + # + return - Vaccine coverage data of the given country @display {label: "Vaccine Coverage By Country"} - remote isolated function getVaccineCoverageByCountry(@display {label: "Country"} string country, @display {label: "Last Days"} string? lastdays = (), @display {label: "Full Data"} string? fullData = ()) returns VaccineCountryCoverage|error { + remote isolated function getVaccineCoverageByCountry(@display {label: "Country"} string country, @display {label: "Last Days"} string? lastdays = ()) returns VaccineCountryCoverage|error { string path = string `/v3/covid-19/vaccine/coverage/countries/${country}`; - map queryParam = {lastdays: lastdays, fullData: fullData}; + map queryParam = {lastdays: lastdays}; path = path + getPathForQueryParam(queryParam); VaccineCountryCoverage response = check self.clientEp-> get(path, targetType = VaccineCountryCoverage); return response; } } +# Generate query path with query parameter. +# +# + queryParam - Query parameter map +# + return - Returns generated Path or error at failure of client initialization isolated function getPathForQueryParam(map queryParam) returns string { string[] param = []; param[param.length()] = "?"; diff --git a/openapi/covid19/openapi.yaml b/openapi/covid19/openapi.yaml index a590e45ca..fda02da99 100644 --- a/openapi/covid19/openapi.yaml +++ b/openapi/covid19/openapi.yaml @@ -4,7 +4,7 @@ servers: info: version: 3.0.0 title: Novel Covid19 API - Disease.sh - An open API for disease-related statistics - description: Third Party API for reliable global disease information + description: Client endpoint for Novel Covid19 API - disease.sh license: name: GNU V3 url: 'https://github.com/disease-sh/API/blob/master/LICENSE' @@ -58,13 +58,13 @@ paths: - '1' - '0' type: string - description: 'By default, if a value is missing, it is returned as 0. This allows nulls to be returned' + description: 'By default, value is 0. This allows nulls to be returned' x-display: label: "Allow Null" - summary: 'Get global COVID-19 totals for today, yesterday and two days ago' + description: 'Get global COVID-19 totals for today, yesterday and two days ago' responses: '200': - description: Status OK + description: Global Covid-19 status content: application/json: schema: @@ -75,7 +75,7 @@ paths: - 'COVID-19: Worldometers' operationId: getUSAStatusByState x-display: - label: "USA State Status" + label: "USA State Status" parameters: - name: states in: path @@ -86,6 +86,7 @@ paths: x-display: label: "State Name" - name: yesterday + description: Queries data reported a day ago in: query schema: enum: @@ -93,26 +94,25 @@ paths: - 'false' - '1' - '0' - description: Queries data reported a day ago type: string x-display: label: "Yesterday" - name: allowNull in: query + description: 'By default, value is 0. This allows nulls to be returned' schema: enum: - 'true' - 'false' - '1' - '0' - description: 'By default, if a value is missing, it is returned as 0. This allows nulls to be returned' type: string x-display: label: "Allow Null" - summary: Get COVID-19 totals for specific US State(s) + description: Get COVID-19 totals for specific US State(s) responses: '200': - description: Status OK + description: Covid-19 status of the given US state content: application/json: schema: @@ -135,55 +135,55 @@ paths: label: "Continent" - name: yesterday in: query + description: Queries data reported a day ago schema: enum: - 'true' - 'false' - '1' - '0' - description: Queries data reported a day ago type: string x-display: label: "Yesterday" - name: twoDaysAgo in: query + description: Queries data reported two days ago schema: enum: - 'true' - 'false' - '1' - '0' - description: Queries data reported two days ago type: string x-display: label: "Two Days Ago" - name: strict in: query + description: Setting to false gives you the ability to fuzzy search continents (i.e. Oman vs. rOMANia) schema: enum: - 'true' - 'false' default: 'true' - description: Setting to false gives you the ability to fuzzy search continents (i.e. Oman vs. rOMANia) type: string x-display: label: "Strict" - name: allowNull in: query + description: 'By default, value is 0. This allows nulls to be returned' schema: enum: - 'true' - 'false' - '1' - '0' - description: 'By default, if a value is missing, it is returned as 0. This allows nulls to be returned' type: string x-display: label: "Allow Null" - summary: Get COVID-19 totals for a specific continent + description: Get COVID-19 totals for a specific continent responses: '200': - description: Status OK + description: Covid-19 status of the given continent content: application/json: schema: @@ -194,67 +194,67 @@ paths: - 'COVID-19: Worldometers' operationId: getStatusByCountry x-display: - label: "Country Status" + label: "Country Status" parameters: - name: country in: path required: true - description: 'A country name, iso2, iso3, or country ID code' + description: 'Country name, iso2, iso3, or country ID code' schema: type: string x-display: label: "Country" - name: yesterday in: query + description: Queries data reported a day ago schema: enum: - 'true' - 'false' - '1' - - '0' - description: Queries data reported a day ago + - '0' type: string x-display: label: "Yesterday" - name: twoDaysAgo in: query + description: Queries data reported two days ago schema: enum: - 'true' - 'false' - '1' - - '0' - description: Queries data reported two days ago + - '0' type: string x-display: label: "Two Days Ago" - name: strict in: query + description: Setting to false gives you the ability to fuzzy search countries (i.e. Oman vs. rOMANia) schema: enum: - 'true' - 'false' default: 'true' - description: Setting to false gives you the ability to fuzzy search countries (i.e. Oman vs. rOMANia) type: string x-display: label: "Strict" - name: allowNull in: query + description: 'By default, value is 0. This allows nulls to be returned' schema: enum: - 'true' - 'false' - '1' - '0' - description: 'By default, if a value is missing, it is returned as 0. This allows nulls to be returned' type: string x-display: label: "Allow Null" - summary: Get COVID-19 totals for a specific country + description: Get COVID-19 totals for a specific country responses: '200': - description: Status OK + description: Covid-19 status of the given country content: application/json: schema: @@ -265,7 +265,7 @@ paths: - 'COVID-19: JHUCSSE' operationId: getGlobalStatusInTimeSeries x-display: - label: "Global Status By Time Series" + label: "Global Status By Time Series" parameters: - name: lastdays in: query @@ -274,10 +274,10 @@ paths: type: string x-display: label: "Number Of Days" - summary: Get global accumulated COVID-19 time series data + description: Get global accumulated COVID-19 time series data responses: '200': - description: Status Ok + description: Global accumulated COVID-19 time series data content: application/json: schema: @@ -286,14 +286,14 @@ paths: get: tags: - 'COVID-19: JHUCSSE' - operationId: getTimeSeriesBycountry + operationId: getTimeSeriesbycountry x-display: label: "Country Status By Time Series" parameters: - name: country in: path required: true - description: 'A country name, iso2, iso3, or country ID code' + description: 'Country name, iso2, iso3, or country ID code' schema: type: string x-display: @@ -306,10 +306,10 @@ paths: default: 30 x-display: label: "Number Of Days" - summary: Get COVID-19 time series data for a specific country + description: Get COVID-19 time series data for a specific country responses: '200': - description: Status Ok + description: COVID-19 related time series for the given country content: application/json: schema: @@ -320,12 +320,12 @@ paths: - 'COVID-19: JHUCSSE' operationId: getTimeSeriesByProvince x-display: - label: "Province Status By Time Seires" + label: "Province Status By Time Seires" parameters: - name: country in: path required: true - description: 'A country name, iso2, iso3, or country ID code' + description: 'Country name, iso2, iso3, or country ID code' schema: type: string x-display: @@ -346,10 +346,10 @@ paths: default: 30 x-display: label: "Number of Days" - summary: Get COVID-19 time series data for a specific province in a country + description: Get COVID-19 time series data for a specific province in a country responses: '200': - description: Status Ok + description: COVID-19 related time series for the given province content: application/json: schema: @@ -361,10 +361,10 @@ paths: operationId: getVaccineTrialData x-display: label: "Vaccine Trial Data" - summary: 'Get vaccine trial data from RAPS (Regulatory Affairs Professional Society). Specifically published by Jeff Craven at https://www.raps.org/news-and-articles/news-articles/2020/3/covid-19-vaccine-tracker' + description: 'Get vaccine trial data from RAPS (Regulatory Affairs Professional Society).' responses: '200': - description: Status Ok + description: Vaccine trial data content: application/json: schema: @@ -385,27 +385,18 @@ paths: default: 30 x-display: label: "Number of Days" - - name: fullData - in: query - description: Flag indicating whether to return data type as SimpleVaccineTimeline (false) or FullVaccineTimeline (true). - schema: - type: string - default: 'false' - x-display: - label: "Full Data" - summary: 'Get total global COVID-19 Vaccine doses administered. Sourced from https://covid.ourworldindata.org/' + description: 'Get total global COVID-19 Vaccine doses administered.' responses: '200': - description: Status Ok + description: Vaccine coverage data content: application/json: schema: - $ref: '#/components/schemas/VaccineCoverage' + description: Covid-19 vaccine timeline briefly + $ref: '#/components/schemas/SimpleVaccineTimeline' examples: simpleTimeline: $ref: '#/components/examples/SimpleVaccineTimeline' - fullTimeline: - $ref: '#/components/examples/FullVaccineTimeline' '/v3/covid-19/vaccine/coverage/countries/{country}': get: tags: @@ -417,7 +408,7 @@ paths: - name: country in: path required: true - description: 'A valid country name, iso2, iso3' + description: 'Country name, iso2, iso3' schema: type: string x-display: @@ -430,18 +421,10 @@ paths: default: 30 x-display: label: "Last Days" - - name: fullData - in: query - description: Flag indicating whether to return timeline data type as SimpleVaccineTimeline (false) or FullVaccineTimeline (true). - schema: - type: string - default: 'false' - x-display: - label: "Full Data" - summary: 'Get COVID-19 vaccine doses administered for a country that has reported vaccination rollout. Sourced from https://covid.ourworldindata.org/' + description: 'Get COVID-19 vaccine doses administered for a country that has reported vaccination rollout.' responses: '200': - description: Status Ok + description: Vaccine coverage data of the given country content: application/json: schema: @@ -449,215 +432,311 @@ paths: examples: simpleTimeline: $ref: '#/components/examples/countrySimpleVaccineTimeline' - fullTimeline: - $ref: '#/components/examples/countryFullVaccineTimeline' components: schemas: CovidAll: properties: updated: type: number + description: Last updated timestamp cases: type: number + description: Total cases todayCases: type: number + description: Today cases deaths: type: number + description: Total deaths + todayDeaths: + type: number + description: Today deaths recovered: type: number + description: Total recovered todayRecovered: type: number + description: Today recovered active: type: number + description: Active cases critical: type: number + description: Critical cases casesPerOneMillion: type: number + description: Cases per one million deathsPerOneMillion: type: number + description: Deaths per one million tests: type: number + description: Total number of Covid-19 tests administered testsPerOneMillion: type: number + description: Covid-19 tests for one million population: type: number + description: World population oneCasePerPeople: type: number + description: One case per people oneDeathPerPeople: type: number + description: One deaths per people oneTestPerPeople: type: number + description: One tests per people activePerOneMillion: type: number + description: Active cases per one million recoveredPerOneMillion: type: number + description: Recovered cases per one million criticalPerOneMillion: type: number + description: Critical cases per one million affectedCountries: type: number + description: Affected countries + description: Covid-19 global status CovidState: properties: state: type: string + description: State name updated: type: number + description: Last updated timestamp cases: type: number + description: Total cases todayCases: type: number + description: Today cases deaths: type: number + description: Total deaths todayDeaths: type: number + description: Today deaths active: type: number + description: Active cases casesPerOneMillion: type: number + description: Cases per one million deathsPerOneMillion: type: number + description: Deaths per one million tests: type: number + description: Total number of Covid-19 tests administered testsPerOneMillion: type: number + description: Covid-19 tests for one million population: type: number + description: Population of the state + description: Covid-19 status in the given USA state CovidContinent: properties: updated: type: number + description: Last updated timestamp cases: type: number + description: Total cases todayCases: type: number + description: Today cases deaths: type: number + description: Total deaths todayDeaths: type: number + description: Today deaths recovered: type: number + description: Total recovered todayRecovered: type: number + description: Today recovered active: type: number + description: Active cases critical: type: number + description: Critical cases casesPerOneMillion: type: number + description: Cases per one million deathsPerOneMillion: type: number + description: Deaths per one million tests: type: number + description: Total number of Covid-19 tests administered testsPerOneMillion: type: number + description: Tests per one milliom population: type: number + description: Population of the continent continent: type: string + description: Continent name activePerOneMillion: type: number + description: Active cases per one million recoveredPerOneMillion: type: number + description: Recovered cases per one million criticalPerOneMillion: type: number + description: Critical cases per one million continentInfo: + description: Continent information type: object properties: lat: type: number + description: Latitude long: type: number + description: Longtitude countries: + description: List of countries in the continent type: array items: type: string + description: Covid-19 status of the given continent CovidCountry: properties: updated: type: number + description: Last updated timestamp country: type: string + description: Country name countryInfo: type: object + description: Country information properties: _id: type: number uniqueItems: true + description: Country Id iso2: type: string uniqueItems: true + description: Country ISO2 code iso3: type: string uniqueItems: true + description: Country ISO3 code lat: type: number + description: Latitude long: type: number + description: Longtitude flag: type: string + description: URL for the country flag cases: type: number + description: Total cases todayCases: type: number + description: Today cases deaths: type: number + description: Total deaths todayDeaths: type: number + description: Today deaths recovered: type: number + description: Total recovered todayRecovered: type: number + description: Today recovered active: type: number + description: Active cases critical: type: number + description: Critical cases casesPerOneMillion: type: number + description: Cases per one million deathsPerOneMillion: type: number + description: Deaths per one million tests: type: number + description: Total number of Covid-19 tests administered testsPerOneMillion: type: number + description: Covid-19 tests for one million population: type: number + description: Total population continent: type: string + description: Continent name oneCasePerPeople: type: number + description: One case per people oneDeathPerPeople: type: number + description: One death per people oneTestPerPeople: type: number + description: One test per people activePerOneMillion: type: number + description: Active cases per one million recoveredPerOneMillion: type: number + description: Recovered cases per one million criticalPerOneMillion: type: number + description: Critical cases per one million + description: Covid-19 status of the given country CovidHistoricalAll: description: 'The amount of key-value pairs in ''cases'', ''deaths'' and ''recovered'' is dependent on the ''lastdays'' query' properties: cases: type: object + description: Total cases properties: date: type: number + description: Date deaths: type: object + description: Total deaths properties: date: type: number + description: Date recovered: type: object + description: Total recovered properties: date: type: number + description: Date CovidHistoricalCountry: properties: country: type: string + description: Country province: type: array + description: Province items: type: string timeline: @@ -666,115 +745,130 @@ components: properties: cases: type: object + description: Total cases properties: date: type: number + description: Date deaths: type: object + description: Total deaths properties: date: type: number + description: Date recovered: type: object + description: Total recovered properties: date: type: number + description: Date + description: Covid-19 historical data of the given country CovidHistoricalProvince: properties: country: type: string + description: Country province: type: string + description: Province timeline: type: object description: 'The amount of key-value pairs in ''cases'', ''deaths'' and ''recovered'' is dependent on the ''lastdays'' query' properties: cases: type: object + description: Total cases properties: date: type: number + description: Date deaths: type: object + description: Total deaths properties: date: type: number + description: Date recovered: type: object + description: Total recovered properties: date: type: number + description: Date + description: Covid-19 historical data of the given province Vaccines: properties: source: type: string + description: Source for the information totalCandidates: type: string + description: Total number of candidates phases: type: array + description: Trial phases items: $ref: '#/components/schemas/Phases' data: type: array + description: Vaccine data of each candidate items: $ref: '#/components/schemas/Vaccine' + description: Covid19-19 vaccine trial data Vaccine: properties: candidate: type: string + description: Candiate Id mechanism: type: string + description: Type of the vaccine sponsors: type: array + description: Sponsors of the vaccine items: type: string details: type: string + description: Details trialPhase: type: string + description: Trial phase institutions: type: array + description: Institutions items: type: string + description: Covid-19 vaccine related data Phases: properties: phase: type: string + description: Trial phase candidates: type: string - VaccineCoverage: - oneOf: - - $ref: '#/components/schemas/SimpleVaccineTimeline' - - $ref: '#/components/schemas/FullVaccineTimeline' + description: Number of candidates + description: Covid-19 vaccine coverage related data VaccineCountryCoverage: type: object + description: Vaccine coverage of each country. properties: country: type: string + description: Country timeline: - oneOf: - - $ref: '#/components/schemas/SimpleVaccineTimeline' - - $ref: '#/components/schemas/FullVaccineTimeline' + description: Covid-19 vaccine timeline briefly + $ref: '#/components/schemas/SimpleVaccineTimeline' SimpleVaccineTimeline: type: object properties: date: type: number - FullVaccineTimeline: - type: array - items: - type: object - properties: - total: - type: number - daily: - type: number - totalPerHundred: - type: number - dailyPerMillion: - type: number - date: - type: string + description: Date + description: Covid-19 Vaccine timeline briefly examples: countriesSimpleVaccineTimeline: value: @@ -782,76 +876,28 @@ components: timeline: 4/25/2021: 1000 summary: Simple Vaccine Timeline - countriesFullVaccineTimeline: - value: - - country: USA - timeline: - - total: 1000 - daily: 1000 - totalPerHundred: 1000 - dailyPerMillion: 1000 - date: 4/25/2021 - summary: Full Vaccine Timeline countrySimpleVaccineTimeline: value: country: USA timeline: 4/25/2021: 1000 summary: Simple Vaccine Timeline - countryFullVaccineTimeline: - value: - country: USA - timeline: - - total: 1000 - daily: 1000 - totalPerHundred: 1000 - dailyPerMillion: 1000 - date: 4/25/2021 - summary: Full Vaccine Timeline statesSimpleVaccineTimeline: value: - state: California timeline: 4/25/2021: 1000 summary: Simple Vaccine Timeline - statesFullVaccineTimeline: - value: - - state: California - timeline: - - total: 1000 - daily: 1000 - totalPerHundred: 1000 - dailyPerMillion: 1000 - date: 4/25/2021 - summary: Full Vaccine Timeline stateSimpleVaccineTimeline: value: state: California timeline: 4/25/2021: 1000 summary: Simple Vaccine Timeline - stateFullVaccineTimeline: - value: - state: California - timeline: - - total: 1000 - daily: 1000 - totalPerHundred: 1000 - dailyPerMillion: 1000 - date: 4/25/2021 - summary: Full Vaccine Timeline SimpleVaccineTimeline: value: 4/25/2021: 1000 summary: Simple Vaccine Timeline - FullVaccineTimeline: - value: - - total: 1000 - daily: 1000 - totalPerHundred: 1000 - dailyPerMillion: 1000 - date: 4/25/2021 - summary: Full Vaccine Timeline externalDocs: description: Find out more about this API url: 'https://github.com/disease-sh/API' diff --git a/openapi/covid19/types.bal b/openapi/covid19/types.bal index 6657383bf..6a0d9ade7 100644 --- a/openapi/covid19/types.bal +++ b/openapi/covid19/types.bal @@ -1,4 +1,4 @@ -// Copyright (c) 2021, WSO2 Inc. (http://www.wso2.org) All Rights Reserved. +// Copyright (c) 2021 WSO2 Inc. (http://www.wso2.org) All Rights Reserved. // // WSO2 Inc. licenses this file to you under the Apache License, // Version 2.0 (the "License"); you may not use this file except @@ -13,143 +13,274 @@ // KIND, either express or implied. See the License for the // specific language governing permissions and limitations // under the License. + +# Covid-19 global status public type CovidAll record { - float updated?; - float cases?; - float todayCases?; - float deaths?; - float recovered?; - float todayRecovered?; - float active?; - float critical?; - float casesPerOneMillion?; - float deathsPerOneMillion?; - float tests?; - float testsPerOneMillion?; - float population?; - float oneCasePerPeople?; - float oneDeathPerPeople?; - float oneTestPerPeople?; - float activePerOneMillion?; - float recoveredPerOneMillion?; - float criticalPerOneMillion?; - float affectedCountries?; + # Last updated timestamp + decimal updated?; + # Total cases + decimal cases?; + # Today cases + decimal todayCases?; + # Total deaths + decimal deaths?; + # Today deaths + decimal todayDeaths?; + # Total recovered + decimal recovered?; + # Today recovered + decimal todayRecovered?; + # Active cases + decimal active?; + # Critical cases + decimal critical?; + # Cases per one million + decimal casesPerOneMillion?; + # Deaths per one million + decimal deathsPerOneMillion?; + # Total number of Covid-19 tests administered + decimal tests?; + # Covid-19 tests for one million + decimal testsPerOneMillion?; + # World population + decimal population?; + # One case per people + decimal oneCasePerPeople?; + # One deaths per people + decimal oneDeathPerPeople?; + # One tests per people + decimal oneTestPerPeople?; + # Active cases per one million + decimal activePerOneMillion?; + # Recovered cases per one million + decimal recoveredPerOneMillion?; + # Critical cases per one million + decimal criticalPerOneMillion?; + # Affected countries + decimal affectedCountries?; }; +# Covid-19 status in the given USA state public type CovidState record { + # State name string state?; - float updated?; - float cases?; - float todayCases?; - float deaths?; - float todayDeaths?; - float active?; - float casesPerOneMillion?; - float deathsPerOneMillion?; - float tests?; - float testsPerOneMillion?; - float population?; + # Last updated timestamp + decimal updated?; + # Total cases + decimal cases?; + # Today cases + decimal todayCases?; + # Total deaths + decimal deaths?; + # Today deaths + decimal todayDeaths?; + # Active cases + decimal active?; + # Cases per one million + decimal casesPerOneMillion?; + # Deaths per one million + decimal deathsPerOneMillion?; + # Total number of Covid-19 tests administered + decimal tests?; + # Covid-19 tests for one million + decimal testsPerOneMillion?; + # Population of the state + decimal population?; }; +# Covid-19 status of the given continent public type CovidContinent record { - float updated?; - float cases?; - float todayCases?; - float deaths?; - float todayDeaths?; - float recovered?; - float todayRecovered?; - float active?; - float critical?; - float casesPerOneMillion?; - float deathsPerOneMillion?; - float tests?; - float testsPerOneMillion?; - float population?; + # Last updated timestamp + decimal updated?; + # Total cases + decimal cases?; + # Today cases + decimal todayCases?; + # Total deaths + decimal deaths?; + # Today deaths + decimal todayDeaths?; + # Total recovered + decimal recovered?; + # Today recovered + decimal todayRecovered?; + # Active cases + decimal active?; + # Critical cases + decimal critical?; + # Cases per one million + decimal casesPerOneMillion?; + # Deaths per one million + decimal deathsPerOneMillion?; + # Total number of Covid-19 tests administered + decimal tests?; + # Tests per one milliom + decimal testsPerOneMillion?; + # Population of the continent + decimal population?; + # Continent name string continent?; - float activePerOneMillion?; - float recoveredPerOneMillion?; - float criticalPerOneMillion?; - record { float lat?; float long?;} continentInfo?; + # Active cases per one million + decimal activePerOneMillion?; + # Recovered cases per one million + decimal recoveredPerOneMillion?; + # Critical cases per one million + decimal criticalPerOneMillion?; + # Continent information + record { # Latitude + decimal lat?; # Longtitude + decimal long?;} continentInfo?; + # List of countries in the continent string[] countries?; }; +# Covid-19 status of the given country public type CovidCountry record { - float updated?; + # Last updated timestamp + decimal updated?; + # Country name string country?; - record { float _id?; string iso2?; string iso3?; float lat?; float long?; string flag?;} countryInfo?; - float cases?; - float todayCases?; - float deaths?; - float todayDeaths?; - float recovered?; - float todayRecovered?; - float active?; - float critical?; - float casesPerOneMillion?; - float deathsPerOneMillion?; - float tests?; - float testsPerOneMillion?; - float population?; + # Country information + record { # Country Id + decimal _id?; # Country ISO2 code + string iso2?; # Country ISO3 code + string iso3?; # Latitude + decimal lat?; # Longtitude + decimal long?; # URL for the country flag + string flag?;} countryInfo?; + # Total cases + decimal cases?; + # Today cases + decimal todayCases?; + # Total deaths + decimal deaths?; + # Today deaths + decimal todayDeaths?; + # Total recovered + decimal recovered?; + # Today recovered + decimal todayRecovered?; + # Active cases + decimal active?; + # Critical cases + decimal critical?; + # Cases per one million + decimal casesPerOneMillion?; + # Deaths per one million + decimal deathsPerOneMillion?; + # Total number of Covid-19 tests administered + decimal tests?; + # Covid-19 tests for one million + decimal testsPerOneMillion?; + # Total population + decimal population?; + # Continent name string continent?; - float oneCasePerPeople?; - float oneDeathPerPeople?; - float oneTestPerPeople?; - float activePerOneMillion?; - float recoveredPerOneMillion?; - float criticalPerOneMillion?; + # One case per people + decimal oneCasePerPeople?; + # One death per people + decimal oneDeathPerPeople?; + # One test per people + decimal oneTestPerPeople?; + # Active cases per one million + decimal activePerOneMillion?; + # Recovered cases per one million + decimal recoveredPerOneMillion?; + # Critical cases per one million + decimal criticalPerOneMillion?; }; +# The amount of key-value pairs in 'cases', 'deaths' and 'recovered' is dependent on the 'lastdays' query public type CovidHistoricalAll record { - record { float date?;} cases?; - record { float date?;} deaths?; - record { float date?;} recovered?; + # Total cases + record { # Date + decimal date?;} cases?; + # Total deaths + record { # Date + decimal date?;} deaths?; + # Total recovered + record { # Date + decimal date?;} recovered?; }; +# Covid-19 historical data of the given country public type CovidHistoricalCountry record { + # Country string country?; + # Province string[] province?; - record { record { float date?;} cases?; record { float date?;} deaths?; record { float date?;} recovered?;} timeline?; + # The amount of key-value pairs in 'cases', 'deaths' and 'recovered' is dependent on the 'lastdays' query + record { # Total cases + record { # Date + decimal date?;} cases?; # Total deaths + record { # Date + decimal date?;} deaths?; # Total recovered + record { # Date + decimal date?;} recovered?;} timeline?; }; +# Covid-19 historical data of the given province public type CovidHistoricalProvince record { + # Country string country?; + # Province string province?; - record { record { float date?;} cases?; record { float date?;} deaths?; record { float date?;} recovered?;} timeline?; + # The amount of key-value pairs in 'cases', 'deaths' and 'recovered' is dependent on the 'lastdays' query + record { # Total cases + record { # Date + decimal date?;} cases?; # Total deaths + record { # Date + decimal date?;} deaths?; # Total recovered + record { # Date + decimal date?;} recovered?;} timeline?; }; +# Covid19-19 vaccine trial data public type Vaccines record { + # Source for the information string 'source?; + # Total number of candidates string totalCandidates?; + # Trial phases Phases[] phases?; + # Vaccine data of each candidate Vaccine[] data?; }; +# Covid-19 vaccine related data public type Vaccine record { + # Candiate Id string candidate?; + # Type of the vaccine string mechanism?; + # Sponsors of the vaccine string[] sponsors?; + # Details string details?; + # Trial phase string trialPhase?; + # Institutions string[] institutions?; }; +# Covid-19 vaccine coverage related data public type Phases record { + # Trial phase string phase?; + # Number of candidates string candidates?; }; -public type VaccineCoverage SimpleVaccineTimeline|FullVaccineTimeline; - +# Vaccine coverage of each country. public type VaccineCountryCoverage record { + # Country string country?; - anydata timeline?; + # Covid-19 vaccine timeline briefly + SimpleVaccineTimeline timeline?; }; +# Covid-19 Vaccine timeline briefly public type SimpleVaccineTimeline record { - float date?; -}; - -public type FullVaccineTimeline record { - record { float total?; float daily?; float totalPerHundred?; float dailyPerMillion?; string date?;} [] fullvaccinetimelinelist; + # Date + decimal date?; }; From af19449eaef36110c07b2b86fd96ae5f4879a243 Mon Sep 17 00:00:00 2001 From: aneeshafedo Date: Fri, 18 Jun 2021 13:07:38 +0530 Subject: [PATCH 04/14] add zoom connector --- openapi/zoom/.gitignore | 1 + openapi/zoom/Ballerina.toml | 11 + openapi/zoom/Package.md | 22 + openapi/zoom/client.bal | 330 ++++ openapi/zoom/openapi.yaml | 3009 +++++++++++++++++++++++++++++++++++ openapi/zoom/types.bal | 390 +++++ 6 files changed, 3763 insertions(+) create mode 100644 openapi/zoom/.gitignore create mode 100644 openapi/zoom/Ballerina.toml create mode 100644 openapi/zoom/Package.md create mode 100644 openapi/zoom/client.bal create mode 100644 openapi/zoom/openapi.yaml create mode 100644 openapi/zoom/types.bal diff --git a/openapi/zoom/.gitignore b/openapi/zoom/.gitignore new file mode 100644 index 000000000..1de565933 --- /dev/null +++ b/openapi/zoom/.gitignore @@ -0,0 +1 @@ +target \ No newline at end of file diff --git a/openapi/zoom/Ballerina.toml b/openapi/zoom/Ballerina.toml new file mode 100644 index 000000000..e725dc694 --- /dev/null +++ b/openapi/zoom/Ballerina.toml @@ -0,0 +1,11 @@ +[package] +org = "ballerinax" +name = "zoom" +version = "0.1.0" +authors = ["Ballerina"] +license= ["Apache-2.0"] +keywords = ["zoom", "zoom meetings", "zoom webinars"] +repository = "https://github.com/ballerina-platform/ballerinax-openapi-connectors" + +[build-options] +observabilityIncluded = true \ No newline at end of file diff --git a/openapi/zoom/Package.md b/openapi/zoom/Package.md new file mode 100644 index 000000000..4812d3380 --- /dev/null +++ b/openapi/zoom/Package.md @@ -0,0 +1,22 @@ +Connects to Zoom API from Ballerina. + +## Module Overview + +The Zoom connector consume the data exposed in https://api.zoom.us/v2. It is currently supporting the following operations. + +- Create Meeting +- List Meetings +- Get Meeting by Id +- Delete Meeting +- Add Meeting Registrant +- List Meeting Registrants +- List Past Meeting Participants +- List Webinar Registrants +- List Webinar Participants +- List Webinar Absentees + +## Compatibility + +| Ballerina Language Versions | Zoom API | +|:----------------------------:|:-----------------:| +| Swan Lake Alpha 5 | V2 | diff --git a/openapi/zoom/client.bal b/openapi/zoom/client.bal new file mode 100644 index 000000000..34d8ab59c --- /dev/null +++ b/openapi/zoom/client.bal @@ -0,0 +1,330 @@ +// Copyright (c) 2021 WSO2 Inc. (http://www.wso2.org) All Rights Reserved. +// +// WSO2 Inc. licenses this file to you under the Apache License, +// Version 2.0 (the "License"); you may not use this file except +// in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +import ballerina/http; +import ballerina/url; +import ballerina/lang.'string; + +public type ClientConfig record { + http:BearerTokenConfig|http:OAuth2RefreshTokenGrantConfig authConfig; + http:ClientSecureSocket secureSocketConfig?; +}; + +public type CompoundListMeetingsResponse record { + *PaginationObject; + *MeetingList; +}; + +public type CompoundCreateMeetingResponse record { + *MeetingMetadata; + *RequestedMeetingDetails; +}; + +public type CompoundListMeetingRegistrantsResponse record { + *PaginationObject; + *RegistrantsList; +}; + +# Registrant base object +public type CompoundAddMeetingRegistrantRequest record { + # Registrant's address. + string address?; + # Registrant's city. + string city?; + # A field that allows registrants to provide any questions or comments that they might have. + string comments?; + # Registrant's country. The value of this field must be in two-letter abbreviated form and must match the ID field provided in the [Countries](https://marketplace.zoom.us/docs/api-reference/other-references/abbreviation-lists#countries) table. + string country?; + # Custom questions. + record { string title?; string value?;} [] custom_questions?; + # A valid email address of the registrant. + string email?; + # Registrant's first name. + string first_name?; + # Registrant's Industry. + string industry?; + # Registrant's job title. + string job_title?; + # Registrant's last name. + string last_name?; + # Number of Employees: `1-20`, `21-50`, `51-100`, `101-500`, `500-1,000`, `1,001-5,000`, `5,001-10,000`, `More than 10,000` + string no_of_employees?; + # Registrant's Organization. + string org?; + # Registrant's Phone number. + string phone?; + # This field can be included to gauge interest of webinar attendees towards buying your product or service. + string purchasing_time_frame?; + # Role in Purchase Process: `Decision Maker`, `Evaluator/Recommender`, `Influencer`, `Not involved` + string role_in_purchase_process?; + # Registrant's State/Province. + string state?; + # Registrant's Zip/Postal Code. + string zip?; +}; + +# Add meeting registrant respond +public type AddMeetingRegistrantResponse record { + # [Meeting ID](https://support.zoom.us/hc/en-us/articles/201362373-What-is-a-Meeting-ID-): Unique identifier of the meeting in "**long**" format(represented as int64 data type in JSON), also known as the meeting number. + int id?; + # Unique URL for this registrant to join the meeting. This URL should only be shared with the registrant for whom the API request was made. + string join_url?; + # Unique identifier of the registrant. + string registrant_id?; + # The start time for the meeting. + string start_time?; + # Topic of the meeting. + string topic?; +}; + +public type CompoundGetMeetingByIdResponse record { + *MeetingFullMetadata; + *RequestedMeetingDetails; +}; + +public type CompoundListPastMeetingParticipantsResponse record { + *PaginationObject; + *MeetingPartcipantsList; +}; + +public type CompoundListWebinarRegistrantsResponse record { + *PaginationObject; + *RegistrantsList; +}; + +# Webinar participants' details +public type ListWebinarParticipantsResponse record { + # The next page token is used to paginate through large result sets. A next page token will be returned whenever the set of available results exceeds the current page size. The expiration period for this token is 15 minutes. + string next_page_token?; + # The number of pages returned for this request. + int page_count?; + # The total number of records returned from a single API call. + int page_size?; + # ParticipantsDetails + record { # Unique identifier of the participant. + string id?; # Name of the participant. + string name?; # Email address of the participant. + string user_email?;} [] participants?; + # The total number of records available across all pages. + int total_records?; +}; + +public type CompoundListWebinarAbsenteesResponse record { + *PaginationObject; + *RegistrantsList; +}; + +# Client endpoint for Zoom API +# +# + clientEp - Connector http endpoint +@display {label: "Zoom Client"} +public client class Client { + http:Client clientEp; + public isolated function init(ClientConfig clientConfig, string serviceUrl = "https://api.zoom.us/v2") returns error? { + http:ClientSecureSocket? secureSocketConfig = clientConfig?.secureSocketConfig; + http:Client httpEp = check new (serviceUrl, { auth: clientConfig.authConfig, secureSocket: secureSocketConfig }); + self.clientEp = httpEp; + } + # List meetings + # + # + userId - The user ID or email address of the user. For user-level apps, pass `me` as the value for userId. + # + 'type - The meeting types. Scheduled, live or upcoming + # + page_size - The number of records returned within a single API call. + # + next_page_token - The next page token is used to paginate through large result sets. A next page token will be returned whenever the set of available results exceeds the current page size. The expiration period for this token is 15 minutes. + # + page_number - The page number of the current page in the returned records. + # + return - HTTP Status Code:200. List of meetings returned. + @display {label: "List Meetings"} + remote isolated function listMeetings(@display {label: "User Id"} string userId, @display {label: "Meeting Type"} string? 'type = "live", @display {label: "Page Size"} int? page_size = 30, @display {label: "Next Page Token"} string? next_page_token = (), @display {label: "Page Number"} string? page_number = ()) returns CompoundListMeetingsResponse|error { + string path = string `/users/${userId}/meetings`; + map queryParam = {'type: 'type, page_size: page_size, next_page_token: next_page_token, page_number: page_number}; + path = path + getPathForQueryParam(queryParam); + CompoundListMeetingsResponse response = check self.clientEp-> get(path, targetType = CompoundListMeetingsResponse); + return response; + } + # Create a meeting + # + # + userId - The user ID or email address of the user. For user-level apps, pass me as the value for userId. + # + payload - Meeting detailed. + # + return - HTTP Status Code:201 - Meeting created. + @display {label: "Create Meeting"} + remote isolated function createMeeting(@display {label: "User Id"} string userId, @display {label: "Meeting Details"} MeetingDetails payload) returns CompoundCreateMeetingResponse|error { + string path = string `/users/${userId}/meetings`; + http:Request request = new; + json jsonBody = check payload.cloneWithType(json); + request.setPayload(jsonBody); + CompoundCreateMeetingResponse response = check self.clientEp->post(path, request, targetType=CompoundCreateMeetingResponse); + return response; + } + # List meeting registrants + # + # + meetingId - MThe meeting ID in **long** format. The data type of this field is "long"(represented as int64 in JSON). + # + occurrence_id - The meeting occurrence ID. + # + status - The registrant status + # + page_size - The number of records returned within a single API call. + # + page_number - Deprecated - The page number of the current page in the returned records. + # + next_page_token - The next page token is used to paginate through large result sets. A next page token will be returned whenever the set of available results exceeds the current page size. The expiration period for this token is 15 minutes. + # + return - HTTP Status Code:200. Successfully listed meeting registrants. + @display {label: "List Meeting Registrants"} + remote isolated function listMeetingRegistrants(@display {label: "Meeting Id"} int meetingId, @display {label: "Occurence Id"} string? occurrence_id = (), @display {label: "Registrant Status"} string? status = "approved", @display {label: "Page Size"} int? page_size = 30, @display {label: "Page Number"} int? page_number = 1, @display {label: "Next Page Token"} string? next_page_token = ()) returns CompoundListMeetingRegistrantsResponse|error { + string path = string `/meetings/${meetingId}/registrants`; + map queryParam = {occurrence_id: occurrence_id, status: status, page_size: page_size, page_number: page_number, next_page_token: next_page_token}; + path = path + getPathForQueryParam(queryParam); + CompoundListMeetingRegistrantsResponse response = check self.clientEp-> get(path, targetType = CompoundListMeetingRegistrantsResponse); + return response; + } + # Add meeting registrant + # + # + meetingId - The meeting ID in **long** format. The data type of this field is "long"(represented as int64 in JSON). + # + payload - Meeting Registrant Details + # + occurrence_ids - Occurrence IDs. You can find these with the meeting get API. Multiple values separated by comma. + # + return - Add meeting registrant respond + @display {label: "Add Meeting Registrant"} + remote isolated function addMeetingRegistrant(@display {label: "Meeting Id"} int meetingId, CompoundAddMeetingRegistrantRequest payload, @display {label: "Occurence Id"} string? occurrence_ids = ()) returns AddMeetingRegistrantResponse|error { + string path = string `/meetings/${meetingId}/registrants`; + map queryParam = {occurrence_ids: occurrence_ids}; + path = path + getPathForQueryParam(queryParam); + http:Request request = new; + json jsonBody = check payload.cloneWithType(json); + request.setPayload(jsonBody); + AddMeetingRegistrantResponse response = check self.clientEp->post(path, request, targetType=AddMeetingRegistrantResponse); + return response; + } + # Get a meeting + # + # + meetingId - The meeting ID in **long** format. The data type of this field is "long"(represented as int64 in JSON). + # + occurrence_id - Meeting Occurrence ID. Provide this field to view meeting details of a particular occurrence of the [recurring meeting](https://support.zoom.us/hc/en-us/articles/214973206-Scheduling-Recurring-Meetings). + # + show_previous_occurrences - Set the value of this field to `true` if you would like to view meeting details of all previous occurrences of a [recurring meeting](https://support.zoom.us/hc/en-us/articles/214973206-Scheduling-Recurring-Meetings). + # + return - **HTTP Status Code:** `200` Meeting object returned. + @display {label: "Get Meeting Details"} + remote isolated function getMeetingById(@display {label: "Meeting Id"} int meetingId, @display {label: "Occurence Id"} string? occurrence_id = (), @display {label: "Show Previous Occurrences"} boolean? show_previous_occurrences = ()) returns CompoundGetMeetingByIdResponse|error { + string path = string `/meetings/${meetingId}`; + map queryParam = {occurrence_id: occurrence_id, show_previous_occurrences: show_previous_occurrences}; + path = path + getPathForQueryParam(queryParam); + CompoundGetMeetingByIdResponse response = check self.clientEp-> get(path, targetType = CompoundGetMeetingByIdResponse); + return response; + } + # Delete a meeting + # + # + meetingId - The meeting ID in **long** format. The data type of this field is "long"(represented as int64 in JSON). + # + occurrence_id - The meeting occurrence ID. + # + schedule_for_reminder - `true`: Notify host and alternative host about the meeting cancellation via email. + # + cancel_meeting_reminder - `true`: Notify registrants about the meeting cancellation via email. + # + return - **HTTP Status Code**: `204` Meeting deleted. + @display {label: "Delete Meeting"} + remote isolated function deleteMeeting(@display {label: "Meeting Id"} int meetingId, @display {label: "Occurence Id"} string? occurrence_id = (), @display {label: "Schedule for Reminder"} boolean? schedule_for_reminder = (), @display {label: "Meeting Cancellation Reminder"} string? cancel_meeting_reminder = ()) returns error? { + string path = string `/meetings/${meetingId}`; + map queryParam = {occurrence_id: occurrence_id, schedule_for_reminder: schedule_for_reminder, cancel_meeting_reminder: cancel_meeting_reminder}; + path = path + getPathForQueryParam(queryParam); + http:Request request = new; + //TODO: Update the request as needed; + _ = check self.clientEp-> delete(path, request, targetType =http:Response); + } + # List past meeting participants + # + # + meetingUUID - The meeting UUID. Each meeting instance will generate its own Meeting UUID (i.e., after a meeting ends, a new UUID will be generated for the next instance of the meeting). Please double encode your UUID when using it for other API calls if the UUID begins with a '/'or contains '//' in it. + # + page_size - The number of records returned within a single API call. + # + next_page_token - The next page token is used to paginate through large result sets. A next page token will be returned whenever the set of available results exceeds the current page size. The expiration period for this token is 15 minutes. + # + return - **HTTP Status Code:** `200`
+ @display {label: "List Past Meeting Participants"} + remote isolated function listPastMeetingParticipants(@display {label: "Meeting UUID"} string meetingUUID, @display {label: "Page Size"} int? page_size = 30, @display {label: "Next Page Token"} string? next_page_token = ()) returns CompoundListPastMeetingParticipantsResponse|error { + string path = string `/past_meetings/${meetingUUID}/participants`; + map queryParam = {page_size: page_size, next_page_token: next_page_token}; + path = path + getPathForQueryParam(queryParam); + CompoundListPastMeetingParticipantsResponse response = check self.clientEp-> get(path, targetType = CompoundListPastMeetingParticipantsResponse); + return response; + } + # List webinar registrants + # + # + webinarId - The webinar ID in "**long**" format(represented as int64 data type in JSON). + # + occurrence_id - The meeting occurrence ID. + # + status - The registrant status: `pending` - Registrant's status is pending. `approved` - Registrant's status is approved.`denied` - Registrant's status is denied. + # + tracking_source_id - The tracking source ID for the registrants. Useful if you share the webinar registration page in multiple locations. See [Creating source tracking links for webinar registration](https://support.zoom.us/hc/en-us/articles/360000315683-Creating-source-tracking-links-for-webinar-registration) for details. + # + page_size - The number of records returned within a single API call. + # + page_number - The page number of the current page in the returned records. + # + next_page_token - The next page token is used to paginate through large result sets. A next page token will be returned whenever the set of available results exceeds the current page size. The expiration period for this token is 15 minutes. + # + return - HTTP Status Code: `200` Webinar plan subscription is missing. Enable webinar for this user once the subscription is added. + @display {label: "List Webinar Meeting Registrants"} + remote isolated function listWebinarRegistrants(@display {label: "Webinar Id"} int webinarId, @display {label: "Meeting Occurence Id"} string? occurrence_id = (), @display {label: "Status"} string? status = "approved", @display {label: "Tracking Source Id"} string? tracking_source_id = (), @display {label: "Page Size"} int? page_size = 30, @display {label: "Page Number"} int? page_number = 1, @display {label: "Next Page Token"} string? next_page_token = ()) returns CompoundListWebinarRegistrantsResponse|error { + string path = string `/webinars/${webinarId}/registrants`; + map queryParam = {occurrence_id: occurrence_id, status: status, tracking_source_id: tracking_source_id, page_size: page_size, page_number: page_number, next_page_token: next_page_token}; + path = path + getPathForQueryParam(queryParam); + CompoundListWebinarRegistrantsResponse response = check self.clientEp-> get(path, targetType = CompoundListWebinarRegistrantsResponse); + return response; + } + # List webinar participants + # + # + webinarId - Unique identifier of the webinar. You can retrieve the value of this field by calling the [list webinars](https://marketplace.zoom.us/docs/api-reference/zoom-api/webinars/webinars) API. + # + page_size - The number of records returned within a single API call. + # + next_page_token - The next page token is used to paginate through large result sets. A next page token will be returned whenever the set of available results exceeds the current page size. The expiration period for this token is 15 minutes. + # + return - Webinar participants' details + @display {label: "List Webinar Participants"} + remote isolated function listWebinarParticipants(@display {label: "Webinar Id"} string webinarId, @display {label: "Page Size"} int? page_size = 30, @display {label: "Next Page Token"} string? next_page_token = ()) returns ListWebinarParticipantsResponse|error { + string path = string `/past_webinars/${webinarId}/participants`; + map queryParam = {page_size: page_size, next_page_token: next_page_token}; + path = path + getPathForQueryParam(queryParam); + ListWebinarParticipantsResponse response = check self.clientEp-> get(path, targetType = ListWebinarParticipantsResponse); + return response; + } + # List webinar absentees + # + # + WebinarUUID - The Webinar UUID. Each Webinar instance will generate its own Webinar UUID (i.e., after a Webinar ends, a new UUID will be generated for the next instance of the Webinar). Please double encode your UUID when using it for API calls if the UUID begins with a '/' or contains '//' in it. + # + occurrence_id - The meeting occurrence ID. + # + page_size - The number of records returned within a single API call. + # + next_page_token - The next page token is used to paginate through large result sets. A next page token will be returned whenever the set of available results exceeds the current page size. The expiration period for this token is 15 minutes. + # + return - **HTTP Status Code:** `200` + @display {label: "List Webinar Absentees"} + remote isolated function listWebinarAbsentees(@display {label: "Webinar UUID"} string WebinarUUID, @display {label: "Occurence Id"} string? occurrence_id = (), @display {label: "Page Size"} int? page_size = 30, @display {label: "Next Page Token"} string? next_page_token = ()) returns CompoundListWebinarAbsenteesResponse|error { + string path = string `/past_webinars/${WebinarUUID}/absentees`; + map queryParam = {occurrence_id: occurrence_id, page_size: page_size, next_page_token: next_page_token}; + path = path + getPathForQueryParam(queryParam); + CompoundListWebinarAbsenteesResponse response = check self.clientEp-> get(path, targetType = CompoundListWebinarAbsenteesResponse); + return response; + } +} + +# Generate query path with query parameter. +# +# + queryParam - Query parameter map +# + return - Returns generated Path or error at failure of client initialization +isolated function getPathForQueryParam(map queryParam) returns string { + string[] param = []; + param[param.length()] = "?"; + foreach var [key, value] in queryParam.entries() { + if value is () { + _ = queryParam.remove(key); + } else { + if string:startsWith( key, "'") { + param[param.length()] = string:substring(key, 1, key.length()); + } else { + param[param.length()] = key; + } + param[param.length()] = "="; + if value is string { + string updateV = checkpanic url:encode(value, "UTF-8"); + param[param.length()] = updateV; + } else { + param[param.length()] = value.toString(); + } + param[param.length()] = "&"; + } + } + _ = param.remove(param.length()-1); + if param.length() == 1 { + _ = param.remove(0); + } + string restOfPath = string:'join("", ...param); + return restOfPath; +} diff --git a/openapi/zoom/openapi.yaml b/openapi/zoom/openapi.yaml new file mode 100644 index 000000000..2d2a2df2d --- /dev/null +++ b/openapi/zoom/openapi.yaml @@ -0,0 +1,3009 @@ +openapi: 3.0.0 +servers: + - url: https://api.zoom.us/v2 +info: + contact: + email: developersupport@zoom.us + name: Zoom Developers + url: https://developer.zoom.us/ + description: Client endpoint for Zoom API + license: + name: MIT for OAS 2.0 + url: https://opensource.org/licenses/MIT + termsOfService: https://zoom.us/docs/en-us/zoom_api_license_and_tou.html + title: Zoom API + version: 2.0.0 + x-display: + label: Zoom Client +security: + - OAuth: [] +tags: + - description: Meeting operations + name: Meetings + - description: Meeting operations + name: Webinars +paths: + "/users/{userId}/meetings": + get: + description: >- + List all the meetings that were scheduled for a user (meeting + host). This API only supports scheduled meetings and thus, details on + instant meetings are not returned via this API. + + **Scopes:** `meeting:read:admin` `meeting:read` + + **[Rate Limit Label](https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits):** `Medium` + summary: List meetings + operationId: listMeetings + x-display: + label: List Meetings + parameters: + - description: The user ID or email address of the user. For user-level apps, pass + `me` as the value for userId. + in: path + name: userId + required: true + schema: + type: string + x-display: + label: User Id + - description: "The meeting types. Scheduled, live or upcoming" + in: query + name: type + schema: + default: live + enum: + - scheduled + - live + - upcoming + type: string + x-display: + label: Meeting Type + x-enum-descriptions: + - all the scheduled meetings + - all the live meetings + - all the upcoming meetings + - description: "The number of records returned within a single API call." + in: query + name: page_size + schema: + default: 30 + maximum: 300 + type: integer + x-display: + label: Page Size + - description: "The next page token is used to paginate through large result sets. A next page token will be returned whenever the set of available results exceeds the current page size. The expiration period for this token is 15 minutes." + in: query + name: next_page_token + schema: + type: string + x-display: + label: Next Page Token + - description: "The page number of the current page in the returned records." + in: query + name: page_number + schema: + type: string + x-display: + label: Page Number + responses: + "200": + content: + application/json: + examples: + response: + value: + meetings: + - created_at: 2019-08-16T01:13:12Z + duration: 30 + host_id: abckjdfhsdkjf + id: 11111 + join_url: https://zoom.us/j/11111 + start_time: 2019-08-16T02:00:00Z + timezone: America/Los_Angeles + topic: Zoom Meeting + type: 2 + uuid: mlghmfghlBBB + - agenda: RegistrationDeniedTest + created_at: 2019-08-16T18:30:46Z + duration: 60 + host_id: abckjdfhsdkjf + id: 2222 + join_url: https://zoom.us/j/2222 + start_time: 2019-08-16T19:00:00Z + timezone: America/Los_Angeles + topic: TestMeeting + type: 2 + uuid: J8H8eavweUcd321== + - created_at: 2019-08-16T21:15:56Z + duration: 60 + host_id: abckjdfhsdkjf + id: 33333 + join_url: https://zoom.us/j/33333 + start_time: 2019-08-16T22:00:00Z + timezone: America/Los_Angeles + topic: My Meeting + type: 2 + uuid: SGVTAcfSfCbbbb + - created_at: 2019-08-29T17:32:33Z + duration: 60 + host_id: abckjdfhsdkjf + id: 44444 + join_url: https://zoom.us/j/4444 + start_time: 2019-08-29T18:00:00Z + timezone: America/Los_Angeles + topic: MyTestPollMeeting + type: 2 + uuid: 64123avdfsMVA== + page_count: 1 + page_number: 1 + page_size: 30 + total_records: 4 + schema: + allOf: + - $ref: '#/components/schemas/PaginationObject' + - $ref: '#/components/schemas/MeetingList' + description: List of meetings + title: Group List + application/xml: + schema: + allOf: + - $ref: '#/components/schemas/PaginationObject' + - $ref: '#/components/schemas/MeetingList' + description: List of meetings + title: Group List + description: "HTTP Status Code:200. List of meetings returned." + "404": + description: "HTTP Status Code:404 User ID not found. Error Code:1001, User not exist or not belong to this account." + security: + - OAuth: [] + tags: + - Meetings + post: + description: >- + [Create a + meeting](https://support.zoom.us/hc/en-us/articles/201362413-Scheduling-meetings) + for a user. This API has a daily rate limit of 100 requests per day. + Therefore, only 100 **Create a Meeting** API requests are permitted + within a 24 hour window for a user. + + + + + Scopes: `meeting:write:admin` `meeting:write` + + **[Rate Limit Label](https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits):** `Medium` + operationId: createMeeting + x-display: + label: Create Meeting + parameters: + - description: "The user ID or email address of the user. For user-level apps, pass me as the value for userId." + in: path + name: userId + required: true + schema: + type: string + x-display: + label: User Id + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/MeetingDetails' + multipart/form-data: + schema: + $ref: '#/components/schemas/MeetingDetails' + description: Meeting detailed. + x-display: + label: Meeting Details + required: true + x-examples: + application/json: + agenda: string + duration: integer + password: string + recurrence: + end_date_time: string [date-time] + end_times: integer + monthly_day: integer + monthly_week: integer + monthly_week_day: integer + repeat_interval: integer + type: integer + weekly_days: string + schedule_for: string + settings: + alternative_hosts: string + approval_type: integer + audio: string + auto_recording: string + cn_meeting: boolean + enforce_login: boolean + enforce_login_domains: string + global_dial_in_countries: + - string + host_video: boolean + in_meeting: boolean + join_before_host: boolean + mute_upon_entry: boolean + participant_video: boolean + registrants_email_notification: boolean + registration_type: integer + use_pmi: boolean + watermark: boolean + start_time: string [date-time] + timezone: string + topic: string + type: integer + responses: + "201": + content: + application/json: + examples: + response: + value: + created_at: 2019-09-05T16:54:14Z + duration: 60 + host_id: AbcDefGHi + id: 1100000 + join_url: https://zoom.us/j/1100000 + settings: + alternative_hosts: "" + approval_type: 2 + audio: both + auto_recording: local + breakout_room: + enable: false + host_video: false + in_meeting: false + join_before_host: true + mute_upon_entry: false + participant_video: false + registrants_confirmation_email: true + registrants_email_notification: true + rooms: + - name: room1 + participants: + - james.user01@somemail1234.com + - james.user02@somemail1234.com + - name: room2 + participants: + - james.user03@somemail1234.com + use_pmi: false + waiting_room: false + watermark: false + close_registration: false + cn_meeting: false + enforce_login: false + enforce_login_domains: "" + global_dial_in_countries: + - US + global_dial_in_numbers: + - city: New York + country: US + country_name: US + number: +1 1000200200 + type: toll + - city: San Jose + country: US + country_name: US + number: +1 6699006833 + type: toll + - city: San Jose + country: US + country_name: US + number: +1 408000000 + type: toll + start_time: 2019-08-30T22:00:00Z + start_url: https://zoom.us/s/1100000?iIifQ.wfY2ldlb82SWo3TsR77lBiJjR53TNeFUiKbLyCvZZjw + status: waiting + timezone: America/New_York + topic: API Test + type: 2 + uuid: ng1MzyWNQaObxcf3+Gfm6A== + schema: + allOf: + - $ref: '#/components/schemas/MeetingMetadata' + - $ref: '#/components/schemas/RequestedMeetingDetails' + description: Details of the created meeting. + application/xml: + schema: + allOf: + - $ref: '#/components/schemas/MeetingMetadata' + - $ref: '#/components/schemas/RequestedMeetingDetails' + description: Details of the created meeting. + description: "HTTP Status Code:201 - Meeting created." + headers: + Content-Location: + description: Location of created Meeting + schema: + type: string + "300": + description: > + **HTTP Status Code:** `300` + + Invalid enforce_login_domains, separate multiple domains by semicolon. + + A maximum of {rateLimitNumber} meetings can be created/updated for a single user in one day. + "404": + description: > + **HTTP Status Code:** `404` **Not Found** + + User not found. + + + **Error Code:** `1001` User {userId} not exist or not belong to this account. + summary: Create a meeting + tags: + - Meetings + "/meetings/{meetingId}/registrants": + get: + description: A host or a user with admin permission can require [registration + for a Zoom meeting + operationId: listMeetingRegistrants + x-display: + label: List Meeting Registrants + parameters: + - description: MThe meeting ID in **long** format. The data type of this field is + "long"(represented as int64 in JSON). + in: path + name: meetingId + required: true + schema: + format: int64 + type: integer + x-display: + label: Meeting Id + - description: The meeting occurrence ID. + in: query + name: occurrence_id + schema: + type: string + x-display: + label: Occurence Id + - description: The registrant status + in: query + name: status + schema: + default: approved + enum: + - pending + - approved + - denied + type: string + x-display: + label: Registrant Status + x-enum-descriptions: + - registrants status is pending + - registrants status is approved + - registrants status is denied + - description: The number of records returned within a single API call. + in: query + name: page_size + schema: + default: 30 + maximum: 300 + type: integer + x-display: + label: Page Size + - description: "Deprecated - The page number of the current page in the returned records." + in: query + name: page_number + schema: + default: 1 + type: integer + x-display: + label: Page Number + - description: The next page token is used to paginate through large result sets. A next page token will be returned whenever the set of available results exceeds the current page size. The expiration period for this token is 15 minutes. + in: query + name: next_page_token + schema: + type: string + x-display: + label: Next Page Token + responses: + "200": + content: + application/json: + examples: + response: + value: + page_count: 1 + page_number: 1 + page_size: 1 + registrants: + - address: 11111 Awesome St + city: Paris + comments: Love using Zoom APIs + country: France + create_time: 2012-04-14T16:55:30.231Z + custom_questions: + - title: Did you enjoy the registration process? + value: Yes, alot. + - title: Would you like to register for our next meeting? + value: Absolutely. + email: somemeail@emailprovider.com + first_name: Tim + id: zjkfsdfjdfhg + industry: Tech + job_title: Developer + join_url: https://success.zoom.us/j/0000000000000 + last_name: S. + no_of_employees: 1-20 + org: Growth + phone: "00000" + purchasing_time_frame: Within a month + role_in_purchase_process: Not involved + state: Ile-de-France + status: approved + zip: "11000" + total_records: 1 + schema: + allOf: + - $ref: '#/components/schemas/PaginationObject' + - $ref: '#/components/schemas/RegistrantsList' + description: List of users. + title: Registration List + application/xml: + schema: + allOf: + - $ref: '#/components/schemas/PaginationObject' + - $ref: '#/components/schemas/RegistrantsList' + description: List of users. + title: Registration List + description: "HTTP Status Code:200. Successfully listed meeting registrants." + security: + - OAuth: [] + summary: List meeting registrants + tags: + - Meetings + post: + description: >- + Register a participant for a meeting. Note that there is a + maximum limit of 4999 registrants per meeting and users will see an + error if the capacity has reached. + + + **Prerequisite:** + + * Host user type must be "Licensed". + + + **Scopes:** `meeting:write:admin` `meeting:write` + **[Rate Limit Label](https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits):** `Light` + operationId: addMeetingRegistrant + x-display: + label: Add Meeting Registrant + parameters: + - description: The meeting ID in **long** format. The data type of this field is + "long"(represented as int64 in JSON). + in: path + name: meetingId + required: true + schema: + format: int64 + type: integer + x-display: + label: Meeting Id + - description: "Occurrence IDs. You can find these with the meeting get API. Multiple values separated by comma." + in: query + name: occurrence_ids + schema: + type: string + required: false + x-display: + label: Occurence Id + requestBody: + content: + application/json: + schema: + allOf: + - description: Registrant base object + x-display: + label: Registrant Details + properties: + address: + description: Registrant's address. + type: string + x-display: + label: Registrant's Address + city: + description: Registrant's city. + type: string + x-display: + label: Registrant's City + comments: + description: A field that allows registrants to provide any questions or + comments that they might have. + type: string + x-display: + label: Comments + country: + description: Registrant's country. The value of this field must be in two-letter + abbreviated form and must match the ID field provided in + the + [Countries](https://marketplace.zoom.us/docs/api-reference/other-references/abbreviation-lists#countries) + table. + type: string + x-display: + label: Registrant's Country + custom_questions: + description: Custom questions. + x-display: + label: Custom Questions + items: + description: Custom Question. + properties: + title: + type: string + x-display: + label: Title + value: + type: string + x-display: + label: Value + type: object + type: array + email: + description: A valid email address of the registrant. + maxLength: 128 + type: string + x-display: + label: Email + first_name: + description: Registrant's first name. + maxLength: 64 + type: string + x-display: + label: First Name + industry: + description: Registrant's Industry. + type: string + x-display: + label: Industry + job_title: + description: Registrant's job title. + type: string + x-display: + label: Job Title + last_name: + description: Registrant's last name. + maxLength: 64 + type: string + x-display: + label: Last Name + no_of_employees: + description: "Number of Employees: `1-20`, `21-50`, `51-100`, `101-500`, `500-1,000`, `1,001-5,000`, `5,001-10,000`, `More than 10,000`" + type: string + x-display: + label: No of Employees + org: + description: Registrant's Organization. + type: string + x-display: + label: Registrant's Organization. + phone: + description: Registrant's Phone number. + type: string + x-display: + label: Registrant's Phone Number + purchasing_time_frame: + description: >- + This field can be included to gauge interest of webinar attendees + towards buying your product or service. + + + Purchasing Time Frame:`Within a month``1-3 months``4-6 months``More than 6 months``No timeframe` + type: string + x-display: + label: Purchasing Time Frame + role_in_purchase_process: + description: "Role in Purchase Process: `Decision Maker`, `Evaluator/Recommender`, `Influencer`, `Not involved` " + type: string + x-display: + label: Role in Purchase Process + state: + description: Registrant's State/Province. + type: string + x-display: + label: Registrant's State/Province + zip: + description: Registrant's Zip/Postal Code. + type: string + x-display: + label: Registrant's Zip/Postal Code + required: + - email + - first_name + type: object + - properties: + language: + description: "Registrant's language preference for confirmation emails. The value can be one of the following: `en-US`,`de-DE`,`es-ES`,`fr-FR`,`jp-JP`,`pt-PT`,`ru-RU`,`zh-CN`, `zh-TW`, `ko-KO`, `it-IT`, `vi-VN`." + type: string + x-display: + label: Language + - properties: + auto_approve: + type: boolean + x-display: + label: Enable Auto Approve + description: " Registrant." + type: object + x-display: + label: Registrant's Details + multipart/form-data: + schema: + allOf: + - description: Registrant base object + properties: + address: + description: Registrant's address. + type: string + city: + description: Registrant's city. + type: string + comments: + description: A field that allows registrants to provide any questions or + comments that they might have. + type: string + country: + description: Registrant's country. The value of this field must be in two-letter + abbreviated form and must match the ID field provided in + the + [Countries](https://marketplace.zoom.us/docs/api-reference/other-references/abbreviation-lists#countries) + table. + type: string + custom_questions: + description: Custom questions. + items: + description: Custom Question. + properties: + title: + type: string + value: + type: string + type: object + type: array + email: + description: A valid email address of the registrant. + maxLength: 128 + type: string + first_name: + description: Registrant's first name. + maxLength: 64 + type: string + industry: + description: Registrant's Industry. + type: string + job_title: + description: Registrant's job title. + type: string + last_name: + description: Registrant's last name. + maxLength: 64 + type: string + no_of_employees: + description: "Number of Employees: `1-20`, `21-50`, `51-100`, `101-500`, `500-1,000`, `1,001-5,000`, `5,001-10,000`, `More than 10,000`" + type: string + org: + description: Registrant's Organization. + type: string + phone: + description: Registrant's Phone number. + type: string + purchasing_time_frame: + description: >- + This field can be included to gauge interest of webinar attendees + towards buying your product or service. + + + Purchasing Time Frame:`Within a month``1-3 months``4-6 months``More than 6 months``No timeframe` + type: string + role_in_purchase_process: + description: "Role in Purchase Process: `Decision Maker`, `Evaluator/Recommender`, `Influencer`, `Not involved` " + type: string + state: + description: Registrant's State/Province. + type: string + zip: + description: Registrant's Zip/Postal Code. + type: string + required: + - email + - first_name + type: object + - properties: + language: + description: >- + Registrant's language preference for confirmation emails. The + value can be one of the following: + + `en-US`,`de-DE`,`es-ES`,`fr-FR`,`jp-JP`,`pt-PT`,`ru-RU`,`zh-CN`, `zh-TW`, `ko-KO`, `it-IT`, `vi-VN`. + type: string + - properties: + auto_approve: + type: boolean + description: " Registrant." + type: object + required: true + description: Meeting Registrant Details + x-examples: + application/json: + address: 123 Main ST + city: San Jose + comments: Excited to host you. + country: US + custom_questions: + - title: Favorite thing about Zoom + value: Meet Happy + email: myemail@mycompany.com + first_name: Mike + industry: Tech + job_title: DA + last_name: Brown + no_of_employees: 1-20 + org: IT + phone: 111-444-4444 + purchasing_time_frame: More Than 6 Months + role_in_purchase_process: Influencer + state: CA + zip: "95550" + responses: + "201": + content: + application/json: + examples: + response: + value: + id: 85746065 + join_url: amet + registrant_id: a + start_time: culpa mollit + topic: reprehenderit ea ut ex Excepteur + schema: + properties: + id: + description: '[Meeting + ID](https://support.zoom.us/hc/en-us/articles/201362373-What-is-a-Meeting-ID-): + Unique identifier of the meeting in "**long**" + format(represented as int64 data type in JSON), also known + as the meeting number.' + format: int64 + type: integer + join_url: + description: >- + Unique URL for this registrant to join the meeting. This URL should + only be shared with the registrant for whom the API + request was made. + + If the meeting was [created](https://marketplace.zoom.us/docs/api-reference/zoom-api/meetings/meetingcreate) with manual approval type (`approval_type`: 1), the join URL will not be returned in the response. + type: string + registrant_id: + description: Unique identifier of the registrant. + type: string + start_time: + description: The start time for the meeting. + type: string + topic: + description: Topic of the meeting. + type: string + type: object + application/xml: + schema: + properties: + id: + description: '[Meeting + ID](https://support.zoom.us/hc/en-us/articles/201362373-What-is-a-Meeting-ID-): + Unique identifier of the meeting in "**long**" + format(represented as int64 data type in JSON), also known + as the meeting number.' + format: int64 + type: integer + join_url: + description: >- + Unique URL for this registrant to join the meeting. This URL should + only be shared with the registrant for whom the API + request was made. + + If the meeting was [created](https://marketplace.zoom.us/docs/api-reference/zoom-api/meetings/meetingcreate) with manual approval type (`approval_type`: 1), the join URL will not be returned in the response. + type: string + registrant_id: + description: Unique identifier of the registrant. + type: string + start_time: + description: The start time for the meeting. + type: string + topic: + description: Topic of the meeting. + type: string + type: object + description: Add meeting registrant respond + security: + - OAuth: [] + summary: Add meeting registrant + tags: + - Meetings + "/meetings/{meetingId}": + delete: + description: >+ + Delete a meeting. + + **Scopes:** `meeting:write:admin` `meeting:write` + + **[Rate Limit Label](https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits):** `Light` + + operationId: deleteMeeting + x-display: + label: Delete Meeting + parameters: + - description: >- + The meeting ID in **long** format. The data type of this field is + "long"(represented as int64 in JSON). + + + While storing it in your database, store it as a **long** data type and **not as an integer**, as the Meeting IDs can be longer than 10 digits. + in: path + name: meetingId + required: true + schema: + format: int64 + type: integer + x-display: + label: Meeting Id + - description: The meeting occurrence ID. + in: query + name: occurrence_id + schema: + type: string + x-display: + label: Occurence Id + - description: >- + `true`: Notify host and alternative host about the meeting + cancellation via email. + + `false`: Do not send any email notification. + in: query + name: schedule_for_reminder + schema: + type: boolean + x-display: + label: Schedule for Reminder + - description: >- + `true`: Notify registrants about the meeting cancellation via + email. + + + `false`: Do not send any email notification to meeting registrants. + + + The default value of this field is `false`. + in: query + name: cancel_meeting_reminder + schema: + type: string + x-display: + label: Meeting Cancellation Reminder + responses: + "204": + description: "**HTTP Status Code**: `204` Meeting deleted." + "400": + description: >+ + **HTTP Status Code**: `400` + + **Error Code**: `1010` + + User does not belong to this account: {accountId}. + + **Error Code**: `3000` Cannot access meeting information.Invalid occurrence_id. + + **Error Code**: `3002` + + Sorry, you cannot delete this meeting since it is in progress.**Error Code**: `3003` You are not the meeting host. + + **Error Code**: `3007` Sorry, you cannot delete this meeting since it has ended.**Error Code**: `3018` + + Not allowed to delete PMI.**Error Code**: `3037` Not allowed to delete PAC. + "404": + description: |- + **HTTP Status Code**: `404` + Meeting not found. + **Error Code**: `1001` + User does not exist: {userId}. + **Error Code**: `3001` + Meeting with this {meetingId} is not found or has expired. + security: + - OAuth: [] + summary: Delete a meeting + tags: + - Meetings + get: + description: >+ + Retrieve the details of a meeting. + + **Scopes:** `meeting:read:admin` `meeting:read` + + **[Rate Limit Label](https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits):** `Light` + + operationId: getMeetingById + x-display: + label: Get Meeting Details + parameters: + - description: >- + The meeting ID in **long** format. The data type of this field is + "long"(represented as int64 in JSON). + + + While storing it in your database, store it as a **long** data type and **not as an integer**, as the Meeting IDs can be longer than 10 digits. + in: path + name: meetingId + required: true + schema: + format: int64 + type: integer + x-display: + label: Meeting Id + - description: Meeting Occurrence ID. Provide this field to view meeting details + of a particular occurrence of the [recurring + meeting](https://support.zoom.us/hc/en-us/articles/214973206-Scheduling-Recurring-Meetings). + in: query + name: occurrence_id + schema: + type: string + x-display: + label: Occurence Id + - description: "Set the value of this field to `true` if you would like to view + meeting details of all previous occurrences of a [recurring + meeting](https://support.zoom.us/hc/en-us/articles/214973206-Schedu\ + ling-Recurring-Meetings). " + in: query + name: show_previous_occurrences + schema: + type: boolean + x-display: + label: Show Previous Occurrences + responses: + "200": + content: + application/json: + examples: + response: + value: + agenda: API overview + created_at: 2019-09-09T15:54:24Z + duration: 60 + host_id: ABcdofjdogh11111 + id: 1234555466 + join_url: https://zoom.us/j/1234555466 + settings: + alternative_hosts: kjxckfjxgfgjdfk@dkjfhdskhf.com + approval_type: 2 + audio: both + auto_recording: local + close_registration: false + cn_meeting: false + enforce_login: false + enforce_login_domains: mycompanydomain.com + global_dial_in_countries: + - US + global_dial_in_numbers: + - city: New York + country: US + country_name: US + number: +1 000011100 + type: toll + - city: San Jose + country: US + country_name: US + number: +1 6699006833 + type: toll + - city: San Jose + country: US + country_name: US + number: +1 221122112211 + type: toll + host_video: false + in_meeting: false + join_before_host: true + mute_upon_entry: false + participant_video: false + registrants_confirmation_email: true + registrants_email_notification: true + use_pmi: false + waiting_room: false + watermark: false + start_time: 2019-08-30T22:00:00Z + start_url: https://zoom.us/1234555466/cdknfdffgggdfg4MDUxNjY0LCJpYXQiOjE1NjgwNDQ0NjQsImFpZCI6IjRBOWR2QkRqVHphd2J0amxoejNQZ1EiLCJjaWQiOiIifQ.Pz_msGuQwtylTtYQ + status: waiting + timezone: America/New_York + topic: My API Test + type: 2 + uuid: iAABBBcccdddd7A== + schema: + allOf: + - $ref: '#/components/schemas/MeetingFullMetadata' + - $ref: '#/components/schemas/RequestedMeetingDetails' + description: Details of the meeting. + application/xml: + schema: + allOf: + - $ref: '#/components/schemas/MeetingFullMetadata' + - $ref: '#/components/schemas/RequestedMeetingDetails' + description: Details of the meeting. + description: "**HTTP Status Code:** `200` Meeting object returned." + "400": + description: >- + **HTTP Status Code:** `400` + + **Error Code:** `1010` + + User not found on this account: {accountId}.**Error Code:** `3000` + + Cannot access webinar info. + "404": + description: |- + **HTTP Status Code:** `404` + Meeting not found. + **Error Code:** `1001` + User not exist: {userId}.**Error Code:** `3001` + Meeting {meetingId} is not found or has expired. + security: + - OAuth: [] + summary: Get a meeting + tags: + - Meetings + "/past_meetings/{meetingUUID}/participants": + get: + description: > + Retrieve information on participants from a past meeting.

+ + **Scopes:** `meeting:read:admin` `meeting:read` + + **[Rate Limit Label](https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits):** `Medium` + **Prerequisites:**
+ + * Paid account on a Pro or higher plan. + + +

**Note**: Please double encode your UUID when using this API if the UUID begins with a '/'or contains '//' in it. + operationId: listPastMeetingParticipants + x-display: + label: List Past Meeting Participants + parameters: + - description: The meeting UUID. Each meeting instance will generate its own + Meeting UUID (i.e., after a meeting ends, a new UUID will be + generated for the next instance of the meeting). Please double + encode your UUID when using it for other API calls if the UUID + begins with a '/'or contains '//' in it. + in: path + name: meetingUUID + required: true + schema: + type: string + x-display: + label: Meeting UUID + - description: The number of records returned within a single API call. + in: query + name: page_size + schema: + default: 30 + maximum: 300 + type: integer + x-display: + label: Page Size + - description: The next page token is used to paginate through large result sets. + A next page token will be returned whenever the set of available + results exceeds the current page size. The expiration period for + this token is 15 minutes. + in: query + name: next_page_token + schema: + type: string + x-display: + label: Next Page Token + responses: + "200": + content: + application/json: + examples: + response: + value: + next_page_token: aliqua + page_count: 1 + page_size: 30 + participants: + - id: 8b29rgg4bb + name: Ram Shekhar + user_email: ram.shekhar.123@fkdngfjg.fdghdfgj + total_records: 1 + schema: + allOf: + - $ref: '#/components/schemas/PaginationObject' + - $ref: '#/components/schemas/MeetingPartcipantsList' + description: List of participants + application/xml: + schema: + allOf: + - $ref: '#/components/schemas/PaginationObject' + - $ref: '#/components/schemas/MeetingPartcipantsList' + description: |- + **HTTP Status Code:** `200`
+ Meeting participants' report returned. + "400": + description: |+ + **HTTP Status Code:** `400`
+ **Error Code:** `1010`
+ User {userId} not exist or not belong to this account.

+ **Error Code:** `300`
+ Cannot access meeting information.

+ **Error Code:** `200`
+ Only available for paid account: {accountId} + + "404": + description: |- + **HTTP Status Code:** `404`
+ Meeting not found
+ **Error Code:** `1001`
+ User {userId} not exist or not belong to this account.
+ User not exist: {userId}

+ **Error Code:** `3001`
+ This meeting is not available or ID is not valid.
+ Meeting ID is invalid or not end. + security: + - OAuth: [] + summary: List past meeting participants + tags: + - Meetings + "/webinars/{webinarId}/registrants": + get: + description: >+ + Zoom users with a [Webinar Plan](https://zoom.us/webinar) have + access to creating and managing Webinars. Webinar allows a host to + broadcast a Zoom meeting to up to 10,000 attendees. Scheduling a + [Webinar with + registration](https://support.zoom.us/hc/en-us/articles/204619915-Scheduling-a-Webinar-with-Registration) + requires your registrants to complete a brief form before receiving the + link to join the Webinar. + + Use this API to list all the users that have registered for a webinar. + + **Prerequisites:** + + * Pro or higher plan with a Webinar Add-on. + + **Scopes:** `webinar:read:admin` `webinar:read` + **[Rate Limit Label](https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits):** `Medium` + + operationId: listWebinarRegistrants + x-display: + label: List Webinar Meeting Registrants + parameters: + - description: 'The webinar ID in "**long**" format(represented as int64 data type + in JSON). ' + in: path + name: webinarId + required: true + schema: + format: int64 + type: integer + x-display: + label: Webinar Id + - description: The meeting occurrence ID. + in: query + name: occurrence_id + schema: + type: string + x-display: + label: Meeting Occurence Id + - description: "The registrant status: `pending` - Registrant's status is pending. `approved` - Registrant's status is approved.`denied` - Registrant's status is denied." + in: query + name: status + schema: + default: approved + enum: + - pending + - approved + - denied + type: string + x-display: + label: Status + x-enum-descriptions: + - registrants status is pending + - registrants status is approved + - registrants status is denied + - description: The tracking source ID for the registrants. Useful if you share the + webinar registration page in multiple locations. See [Creating + source tracking links for webinar + registration](https://support.zoom.us/hc/en-us/articles/360000315683-Creating-source-tracking-links-for-webinar-registration) + for details. + in: query + name: tracking_source_id + schema: + type: string + x-display: + label: Tracking Source Id + - description: The number of records returned within a single API call. + in: query + name: page_size + schema: + default: 30 + maximum: 300 + type: integer + x-display: + label: Page Size + - description: The page number of the current page in the returned records. + in: query + name: page_number + schema: + default: 1 + type: integer + x-display: + label: Page Number + - description: The next page token is used to paginate through large result sets. + A next page token will be returned whenever the set of available + results exceeds the current page size. The expiration period for + this token is 15 minutes. + in: query + name: next_page_token + schema: + type: string + x-display: + label: Next Page Token + responses: + "200": + content: + application/json: + examples: + response: + value: + page_count: "1" + page_number: "1" + page_size: "30" + registrants: + - address: dsfhkdjsfh st + city: jackson heights + comments: Looking forward to the Webinar + country: US + create_time: 2019-02-26T23:01:16.899Z + custom_questions: + - title: What do you hope to learn from this Webinar? + value: Look forward to learning how you come up with new recipes and what other + services you offer. + email: sjfkghdsg@someemail.dfgjd + first_name: Jill + id: "24000002122" + industry: Food + job_title: Chef + join_url: https://zoom.us/webinar/mywebinarissocooldighdghodghodg + last_name: Chill + no_of_employees: "10" + org: Cooking Org + phone: "00000000" + purchasing_time_frame: 1-3 months + role_in_purchase_process: Influencer + state: NY + status: approved + zip: "11371" + total_records: "1" + schema: + allOf: + - $ref: '#/components/schemas/PaginationObject' + - $ref: '#/components/schemas/RegistrantsList' + description: List of users. + title: Registration List + type: object + application/xml: + schema: + allOf: + - $ref: '#/components/schemas/PaginationObject' + - $ref: '#/components/schemas/RegistrantsList' + description: List of users. + title: Registration List + type: object + description: "HTTP Status Code: `200` Webinar plan subscription is missing. Enable webinar for this user once the subscription is added." + "300": + description: "**HTTP Status Code:** `300` Invalid webinar ID." + "400": + description: |- + **HTTP Status Code:** `400` + Bad request + **Error Code:** `1010` + User does not belong to this account:{accountId}. + "404": + description: |- + **HTTP Status Code:** `404` + Webinar not found. + **Error Code:** `1001` + User {userId} does not exist or does not belong to this account. + **Error Code:** `3001` + Webinar {webinarId} not found or has expired. + security: + - OAuth: [] + summary: List webinar registrants + tags: + - Webinars + parameters: + - in: path + name: webinarId + required: true + schema: + type: string + x-display: + label: Webinar Id + "/past_webinars/{webinarId}/participants": + get: + description: >+ + Use this API to list all the participants who attended a webinar + hosted in the past. + + + **Prerequisites:** + + * Pro or higher plan with a Webinar Add-on. + + **Scopes:** `webinar:read:admin` `webinar:read` + + + + **[Rate Limit Label](https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits):** `Medium` + + + + operationId: listWebinarParticipants + x-display: + label: List Webinar Participants + parameters: + - description: Unique identifier of the webinar. You can retrieve the value of + this field by calling the [list + webinars](https://marketplace.zoom.us/docs/api-reference/zoom-api/webinars/webinars) + API. + in: path + name: webinarId + required: true + schema: + type: string + x-display: + label: Webinar Id + - description: The number of records returned within a single API call. + in: query + name: page_size + schema: + default: 30 + maximum: 300 + type: integer + x-display: + label: Page Size + - description: The next page token is used to paginate through large result sets. + A next page token will be returned whenever the set of available + results exceeds the current page size. The expiration period for + this token is 15 minutes. + in: query + name: next_page_token + schema: + type: string + x-display: + label: Next Page Token + responses: + "200": + content: + application/json: + examples: + response: + value: + next_page_token: mdnf23qbsf4wr + page_count: 1 + page_size: 1 + participants: + - id: sdjhf3ui + name: Matt + user_email: matt@123.jhdyuerys + total_records: 1 + schema: + properties: + next_page_token: + description: The next page token is used to paginate through large result sets. + A next page token will be returned whenever the set of + available results exceeds the current page size. The + expiration period for this token is 15 minutes. + type: string + page_count: + description: The number of pages returned for this request. + type: integer + page_size: + default: 30 + description: The total number of records returned from a single API call. + maximum: 300 + type: integer + participants: + description: ParticipantsDetails + items: + properties: + id: + description: Unique identifier of the participant. + type: string + name: + description: Name of the participant. + type: string + user_email: + description: Email address of the participant. + format: email + type: string + type: object + type: array + total_records: + description: The total number of records available across all pages. + type: integer + type: object + application/xml: + schema: + properties: + next_page_token: + description: The next page token is used to paginate through large result sets. + A next page token will be returned whenever the set of + available results exceeds the current page size. The + expiration period for this token is 15 minutes. + type: string + page_count: + description: The number of pages returned for this request. + type: integer + page_size: + default: 30 + description: The total number of records returned from a single API call. + maximum: 300 + type: integer + participants: + items: + properties: + id: + description: Unique identifier of the participant. + type: string + name: + description: Name of the participant. + type: string + user_email: + description: Email address of the participant. + format: email + type: string + type: object + type: array + total_records: + description: The total number of records available across all pages. + type: integer + type: object + description: "Webinar participants' details" + "400": + description: | + **HTTP Status Code:** `400` **Bad request** + + **Error Code:** `200` + No permission. + Only available for paid account: {accountId}. + **Error Code:** `300` + The next page token is invalid or expired. + "404": + description: |- + **HTTP Status Code:** `404` + **Error Code:**`3001` + Webinar does not exist. + summary: List webinar participants + tags: + - Webinars + parameters: + - in: path + name: webinarId + required: true + schema: + type: string + x-display: + label: Webinar Id + "/past_webinars/{WebinarUUID}/absentees": + get: + description: >- + List absentees of a webinar. + + **Scopes:** `webinar:read:admin` `webinar:read` + **[Rate Limit Label](https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits):** `Heavy` + operationId: listWebinarAbsentees + x-display: + label: List Webinar Absentees + parameters: + - description: The meeting occurrence ID. + in: query + name: occurrence_id + schema: + type: string + x-display: + label: Occurence Id + - description: The number of records returned within a single API call. + in: query + name: page_size + schema: + default: 30 + maximum: 300 + type: integer + x-display: + label: Page Size + - description: The next page token is used to paginate through large result sets. + A next page token will be returned whenever the set of available + results exceeds the current page size. The expiration period for + this token is 15 minutes. + in: query + name: next_page_token + schema: + type: string + x-display: + label: Next Page Token + - description: The Webinar UUID. Each Webinar instance will generate its own + Webinar UUID (i.e., after a Webinar ends, a new UUID will be + generated for the next instance of the Webinar). Please double + encode your UUID when using it for API calls if the UUID begins with + a '/' or contains '//' in it. + in: path + name: WebinarUUID + required: true + schema: + type: string + x-display: + label: Webinar UUID + responses: + "200": + content: + application/json: + examples: + response: + value: + page_count: 1 + page_number: 1 + page_size: 30 + registrants: + - address: dsfhkdjsfh st + city: jackson heights + comments: Looking forward to the Webinar + country: USA + create_time: 2019-02-26T23:01:16.899Z + custom_questions: + - title: What do you hope to learn from this Webinar? + value: Look forward to learning how you come up with new recipes and what other + services you offer. + email: sjfkghdsg@someemail.dfgjd + first_name: Jill + id: "24000002122" + industry: Food + job_title: Chef + join_url: https://zoom.us/webinar/mywebinarissocooldighdghodghodg + last_name: Chill + no_of_employees: "10" + org: Cooking Org + phone: "00000000" + purchasing_time_frame: 1-3 months + role_in_purchase_process: Influencer + state: NY + status: approved + zip: "11371" + total_records: 1 + schema: + allOf: + - $ref: '#/components/schemas/PaginationObject' + - $ref: '#/components/schemas/RegistrantsList' + description: List of users. + title: Registration List + type: object + application/xml: + schema: + allOf: + - $ref: '#/components/schemas/PaginationObject' + - $ref: '#/components/schemas/RegistrantsList' + description: List of users. + title: Registration List + type: object + description: >- + **HTTP Status Code:** `200` + + Success. **Error Code:** `200` + + Webinar plan subscription is missing. Enable webinar for this user once the subscription is added:{userId}. + "300": + description: "**Error Code:** `300` Invalid webinar UUID." + "400": + description: >- + **HTTP Status Code:** `400` + + **Error Code:** `300` + + The request could not be completed because you have provided an invalid occurence ID: {occurenceId} + + **Error Code:** `1010` + + User does not belong to this account:{accountId}. + + **Error Code:** `3000` + + This Webinar has not registration required: {webinarUUID} + "404": + description: |+ + **HTTP Status Code:** `404` + **Error Code:** `1001` + User {userId} does not exist or does not belong to this account. + **Error Code:** `3001` Meeting ID is invalid or not end. + + security: + - OAuth: [] + summary: List webinar absentees + tags: + - Webinars +components: + schemas: + MeetingDetails: + description: Base object for meeting + x-display: + label: Meeting Details + properties: + agenda: + description: Meeting description. + maxLength: 2000 + type: string + x-display: + label: Description + duration: + description: "Meeting duration (minutes). Used for scheduled meetings only." + type: integer + x-display: + label: Duration + password: + description: "Passcode to join the meeting." + maxLength: 10 + type: string + x-display: + label: Password + recurrence: + $ref: '#/components/schemas/ReccurenceDetails' + schedule_for: + description: "If you would like to schedule this meeting for someone else in your account, provide the Zoom user id or email address of the user here." + type: string + x-display: + label: Scheduled For + settings: + $ref: '#/components/schemas/MeetingSettingsInRequest' + start_time: + description: "Meeting start time. We support two formats for `start_time` - local time and GMT.To set time as GMT the format should be `yyyy-MM-dd`T`HH:mm:ssZ`. To set time using a specific timezone, use `yyyy-MM-dd`T`HH:mm:ss` format and specify the timezone id in the `timezone` field OR leave it blank and the timezone set on your Zoom account will be used. You can also set the time as UTC as the timezone field" + type: string + format: date-time + x-display: + label: Meeting Start Time + template_id: + description: "Unique identifier of the admin meeting template. To create admin meeting templates, contact the Zoom support team." + type: string + x-display: + label: Template Id + timezone: + description: Time zone to format start_time. For example, "America/Los_Angeles". + For scheduled meetings only. Please reference our [time + zone](https://marketplace.zoom.us/docs/api-reference/other-references/abbreviation-lists#timezones) + list for supported time zones and their formats. + type: string + x-display: + label: Timezone + topic: + description: Meeting topic. + type: string + x-display: + label: Meeting Topic + tracking_fields: + description: Tracking fields + x-display: + label: Tracking Fields + items: + properties: + field: + description: Label of the tracking field. + type: string + x-display: + label: Label + value: + description: Tracking fields value + type: string + x-display: + label: Value + required: + - field + type: object + type: array + type: + default: 2 + description: "Meeting Type: 1 - Instant meeting. 2 - Scheduled meeting. 3 - Recurring meeting with no fixed time. 8 - Recurring meeting with fixed time." + enum: + - 1 + - 2 + - 3 + - 8 + type: integer + x-display: + label: Meeting Type + x-enum-descriptions: + - Instant Meeting + - Scheduled Meeting + - Recurring Meeting with no fixed time + - Recurring Meeting with fixed time + type: object + MeetingFullMetadata: + properties: + assistant_id: + description: Unique identifier of the scheduler who scheduled this meeting on + behalf of the host. This field is only returned if you + used "schedule_for" option in the [Create a Meeting + API + request](https://marketplace.zoom.us/docs/api-reference/zoom-api/meetings/meetingcreate). + type: string + host_email: + description: Email address of the meeting host. + format: email + type: string + host_id: + description: ID of the user who is set as host of meeting. + type: string + id: + description: '[Meeting + ID](https://support.zoom.us/hc/en-us/articles/201362373-What-is-a-Meeting-ID-): + Unique identifier of the meeting in "**long**" + format(represented as int64 data type in JSON), also + known as the meeting number.' + format: int64 + type: integer + uuid: + description: > + Unique meeting ID. Each meeting instance will generate its own + Meeting UUID (i.e., after a meeting ends, a new UUID + will be generated for the next instance of the + meeting). You can retrieve a list of UUIDs from past + meeting instances using [this + API](https://marketplace.zoom.us/docs/api-reference/zoom-api/meetings/pastmeetings) + . Please double encode your UUID when using it for API + calls if the UUID begins with a '/'or contains '//' in + it. + type: string + type: object + description: Detailed Meeting Metadata + MeetingSettingsInRequest: + description: Meeting settings + x-display: + label: Meeting Settings + properties: + additional_data_center_regions: + description: "Enable additional data center regions for this meeting. Provide the value in the form of array of country code(s) for the countries which are available as data center regions" + items: + type: string + type: array + x-display: + label: Additiona Data Center Regions + allow_multiple_devices: + description: "If set to `true`, attendees will be allowed to join a meeting from multiple devices." + type: boolean + x-display: + label: Allow Multiple Devices + alternative_hosts: + description: "Alternative host's emails or IDs: multiple values separated by a comma." + type: string + x-display: + label: Allternative Hosts + alternative_hosts_email_notification: + default: true + description: "Flag to determine whether to send email notifications to alternative hosts, default value is true." + type: boolean + x-display: + label: Enable Email Notifications for Alternative Hosts + approval_type: + default: 2 + description: "The default value is `2`. To enable registration required, set the approval type to `0` or `1`. `0` - Automatically approve. `1` - Manually approve. `2` - No registration required." + enum: + - 0 + - 1 + - 2 + type: integer + x-display: + label: Approval Type + x-enum-descriptions: + - Automatically Approve + - Manually Approve + - No Registration Required + approved_or_denied_countries_or_regions: + description: "Approve or block users from specific regions/countries from joining this meeting." + x-display: + label: Approval or Denial Info + properties: + approved_list: + description: "List of countries/regions from where participants can join this meeting. " + items: + type: string + type: array + x-display: + label: Approved Regions List + denied_list: + description: "List of countries/regions from where participants can not join this meeting. " + items: + type: string + type: array + x-display: + label: Denied Regions List + enable: + description: "`true`: Setting enabled to either allow users or block users from specific regions to join your meetings. `false`: Setting disabled." + type: boolean + x-display: + label: Enable + method: + description: "Specify whether to allow users from specific regions to join thismeeting; or block users from specific regions from oining this meeting. Values: approve or deny" + enum: + - approve + - deny + type: string + x-display: + label: Method + type: object + audio: + default: both + description: "Determine how participants can join the audio portion of the meeting. both : Both Telephony and VoIP, telephony :Telephony only, voip:VoIP only." + enum: + - both + - telephony + - voip + type: string + x-enum-descriptions: + - Both Telephony and VoIP + - Telephony only + - VoIP only + x-display: + label: Audio Type + authentication_domains: + description: "Meeting authentication domains. This option, allows you to specify the rule so that Zoom users, whose email address contains a certain domain, can join the meeting." + type: string + x-display: + label: Authentication Domains + authentication_option: + description: "Specify the authentication type for users to join a meeting with `meeting_authentication` setting set to `true`. " + type: string + x-display: + label: Authentication Option + auto_recording: + default: none + description: "Automatic recording: local - Record on local.cloud - Record on cloud.none - Disabled." + enum: + - local + - cloud + - none + type: string + x-enum-descriptions: + - Record to local device + - Record to cloud + - No Recording + x-display: + label: Auto Recording + breakout_room: + description: "Setting to pre-assign breakout rooms" + x-display: + label: Breakout Room Settings + properties: + enable: + description: "Set the value of this field to `true` if you would like to enable the pre-assigned breakout rooms. " + type: boolean + x-display: + label: Enable Pre-Assigned Breakout Rooms + rooms: + description: Create room(s). + x-display: + label: Breakout Room Details + items: + properties: + name: + description: Name of the breakout room. + type: string + x-display: + label: Name + participants: + description: "Email addresses of the participants who are to be assigned to the breakout room." + items: + type: string + x-display: + label: Participant List + type: array + type: object + type: array + type: object + close_registration: + default: false + description: Close registration after event date + type: boolean + x-display: + label: Close Registration + cn_meeting: + default: false + description: Host meeting in China. + type: boolean + x-display: + label: Host Meeting in China + contact_email: + description: Contact email for registration + type: string + x-display: + label: Contact Email + contact_name: + description: Contact name for registration + type: string + x-display: + label: Contact Name + encryption_type: + description: "Choose between enhanced encryption and end-to-end encryption. Values: enhanced_encryption, e2ee" + enum: + - enhanced_encryption + - e2ee + type: string + x-display: + label: Encryption Type + global_dial_in_countries: + description: List of global dial-in countries + items: + type: string + type: array + x-display: + label: Global Dial-In Countries + host_video: + description: Start video when the host joins the meeting. + type: boolean + x-display: + label: Enable Host Video + in_meeting: + default: false + description: Host meeting in India. + type: boolean + x-display: + label: Host Meeting in India + jbh_time: + description: " If the value of join_before_host field is set to true, this field can be used to indicate time limits within which a participant may join a meeting before a host. The value of this field can be one of the following: 0: Allow participant to join anytime. 5: Allow participant to join 5 minutes before meeting start time. 10: Allow participant to join 10 minutes before meeting start time." + enum: + - 0 + - 5 + - 10 + type: integer + x-display: + label: Join Before Host Time + join_before_host: + default: false + description: "Allow participants to join the meeting before the host starts the meeting. This field can only used for scheduled or recurring meetings." + type: boolean + x-display: + label: Enable Join Before Host + language_interpretation: + description: "Language interpretation for meetings. " + x-display: + label: Language Interpretation + properties: + enable: + description: "Indicate whether or not you would like to enable language interpretation or this meeting." + type: boolean + x-display: + label: Enable + interpreters: + description: Information associated with the interpreter. + x-display: + label: interpreter Information + items: + properties: + email: + description: Email address of the interpreter. + format: email + type: string + x-display: + label: Email + languages: + description: "Languages for interpretation. The string must contain two separated by a comma. For example, if the language is to be interpreted from English to Chinese, the value of this field should be US,CN." + type: string + x-display: + label: Languages + type: object + type: array + type: object + meeting_authentication: + description: "Only authenticated users can join meeting if the value of this field is set to `true`." + type: boolean + x-display: + label: Meeting Authentication + mute_upon_entry: + default: false + description: Mute participants upon entry. + type: boolean + x-display: + label: Enable Mute Upon Entry + participant_video: + description: Start video when participants join the meeting. + type: boolean + x-display: + label: Start Participant Video On Entry + registrants_email_notification: + description: "Send email notifications to registrants about approval, cancellation, denial of the registration. The value of this field must be set to true in order to use the `registrants_confirmation_email` field." + type: boolean + x-display: + label: Enable Email Notifications for Registrants + registration_type: + default: 1 + description: "Registration type. Used for recurring meeting with fixed time only. `1` - Attendees register once and can attend any of the occurrences. `2` - Attendees need to register for each occurrence to attend. `3` - occurrences to attend." + enum: + - 1 + - 2 + - 3 + type: integer + x-display: + label: Registration Type + x-enum-descriptions: + - Attendees register once and can attend any of the + occurrences + - Attendees need to register for each occurrence to + attend + - Attendees register once and can choose one or more + occurrences to attend + show_share_button: + description: "If set to `true`, the registration page for the meeting will + include social share buttons. " + type: boolean + x-display: + label: Enable Social Share + use_pmi: + default: false + description: Use Personal Meeting ID instead of an automatically generated + meeting ID. It can only be used for scheduled meetings, + instant meetings and recurring meetings with no fixed + time. + type: boolean + x-display: + label: User Personal Meeting Id + waiting_room: + description: Enable waiting room. Note that if the value of this field is set to + `true`, it will override and disable the + `join_before_host` setting. + type: boolean + x-display: + label: Enable Waiting Room + watermark: + default: false + description: Add watermark when viewing a shared screen. + type: boolean + x-display: + label: Enable Watermark + type: object + RegistrantBaseObject: + description: Registrant base object + properties: + address: + description: Registrant's address. + type: string + city: + description: Registrant's city. + type: string + comments: + description: A field that allows registrants to provide any questions or + comments that they might have. + type: string + country: + description: Registrant's country. The value of this field must be in two-letter + abbreviated form and must match the ID field provided in + the + [Countries](https://marketplace.zoom.us/docs/api-reference/other-references/abbreviation-lists#countries) + table. + type: string + custom_questions: + description: Custom questions. + items: + description: Custom Question. + properties: + title: + type: string + value: + type: string + type: object + type: array + email: + description: A valid email address of the registrant. + maxLength: 128 + type: string + first_name: + description: Registrant's first name. + maxLength: 64 + type: string + industry: + description: Registrant's Industry. + type: string + job_title: + description: Registrant's job title. + type: string + last_name: + description: Registrant's last name. + maxLength: 64 + type: string + no_of_employees: + description: "Number of Employees: `1-20`, `21-50`, `51-100`, `101-500`, `500-1,000`, `1,001-5,000`, `5,001-10,000`, `More than 10,000`" + type: string + org: + description: Registrant's Organization. + type: string + phone: + description: Registrant's Phone number. + type: string + purchasing_time_frame: + description: >- + This field can be included to gauge interest of webinar attendees + towards buying your product or service. + + + Purchasing Time Frame:`Within a month``1-3 months``4-6 months``More than 6 months``No timeframe` + type: string + role_in_purchase_process: + description: "Role in Purchase Process: `Decision Maker`, `Evaluator/Recommender`, `Influencer`, `Not involved` " + type: string + state: + description: Registrant's State/Province. + type: string + zip: + description: Registrant's Zip/Postal Code. + type: string + required: + - email + - first_name + type: object + RegistrantsList: + description: Meeting Registrnats's Details + properties: + registrants: + description: List of registrant objects. + items: + allOf: + - properties: + id: + description: Registrant ID. + type: string + type: object + - description: Registrant base object + properties: + address: + description: Registrant's address. + type: string + city: + description: Registrant's city. + type: string + comments: + description: A field that allows registrants to provide any questions or + comments that they might have. + type: string + country: + description: Registrant's country. + type: string + custom_questions: + description: Custom questions. + items: + description: Custom Question. + properties: + title: + type: string + value: + type: string + type: object + type: array + email: + description: A valid email address of the registrant. + maxLength: 128 + type: string + first_name: + description: Registrant's first name. + maxLength: 64 + type: string + industry: + description: Registrant's Industry. + type: string + job_title: + description: Registrant's job title. + type: string + last_name: + description: Registrant's last name. + maxLength: 64 + type: string + no_of_employees: + description: "Number of Employees: `1-20`, `21-50`, `51-100`, `101-500`, `500-1,000`, `1,001-5,000`, `5,001-10,000`, `More than 10,000`" + type: string + org: + description: Registrant's Organization. + type: string + phone: + description: Registrant's Phone number. + type: string + purchasing_time_frame: + description: >- + This field can be included to gauge interest of webinar attendees + towards buying your product or + service. + + + Purchasing Time Frame:`Within a month``1-3 months``4-6 months``More than 6 months``No timeframe` + type: string + role_in_purchase_process: + description: "Role in Purchase Process: `Decision Maker`, `Evaluator/Recommender`, `Influencer`, `Not involved` " + type: string + state: + description: Registrant's State/Province. + type: string + zip: + description: Registrant's Zip/Postal Code. + type: string + required: + - email + - first_name + type: object + - properties: + create_time: + description: The time at which the registrant registered. + format: date-time + type: string + join_url: + description: The URL using which an approved registrant can join the webinar. + format: string + type: string + status: + description: "The status of the registrant's registration. `approved`: User + has been successfully approved for the + webinar. `pending`: The + registration is still pending. + `denied`: User has been denied from + joining the webinar." + type: string + type: object + type: array + PaginationObject: + description: Pagination Object + properties: + next_page_token: + description: The next page token is used to paginate through large result sets. A next page token will be returned whenever the set of available results exceeds the current page size. The expiration period for this token is 15 minutes. + type: string + page_count: + description: The number of pages returned for the request made. + type: integer + page_number: + default: 1 + description: This field has been deprecated. + type: integer + page_size: + default: 30 + description: The number of records returned with a single API call. + maximum: 300 + type: integer + total_records: + description: The total number of all the records available across pages. + type: integer + type: object + MeetingSettings: + description: Meeting settings + properties: + allow_multiple_devices: + description: Allow attendees to join the meeting from multiple devices. This + setting only works for meetings that require + [registration](https://support.zoom.us/hc/en-us/articles/211579443-Setting-up-registration-for-a-meeting). + type: boolean + alternative_hosts: + description: "Alternative host's emails or IDs: multiple values are separated by + a semicolon." + type: string + alternative_hosts_email_notification: + default: true + description: Flag to determine whether to send email notifications to + alternative hosts, default value is true. + type: boolean + approval_type: + default: 2 + description: "The default value is `2`. To enable registration required, set the approval type to `0` or `1`. `0` - Automatically approve. `1` - Manually approve. `2` - No registration required." + enum: + - 0 + - 1 + - 2 + type: integer + x-enum-descriptions: + - Automatically Approve + - Manually Approve + - No Registration Required + approved_or_denied_countries_or_regions: + description: > + Approve or block users from specific regions/countries from joining + this meeting. + properties: + approved_list: + description: "List of countries/regions from where participants can join this + meeting. " + items: + type: string + type: array + denied_list: + description: "List of countries/regions from where participants can not join + this meeting. " + items: + type: string + type: array + enable: + description: >- + `true`: Setting enabled to either allow users or block users from + specific regions to join your meetings. + + + `false`: Setting disabled. + type: boolean + method: + description: >- + Specify whether to allow users from specific regions to join this + meeting; or block users from specific regions + from joining this meeting. + + `approve`: Allow users from specific regions/countries to join this meeting. If this setting is selected, the approved regions/countries must be included in the `approved_list`. + + `deny`: Block users from specific regions/countries from joining this meeting. If this setting is selected, the approved regions/countries must be included in the `denied_list` + enum: + - approve + - deny + type: string + type: object + audio: + default: both + description: "Determine how participants can join the audio portion of the meeting. both : Both Telephony and VoIP, telephony :Telephony only, voip:VoIP only." + enum: + - both + - telephony + - voip + type: string + x-enum-descriptions: + - Both Telephony and VoIP + - Telephony only + - VoIP only + authentication_domains: + description: If user has configured ["Sign Into Zoom with Specified + Domains"](https://support.zoom.us/hc/en-us/articles/360037117472-Authentication-Profiles-for-Meetings-and-Webinars#h_5c0df2e1-cfd2-469f-bb4a-c77d7c0cca6f) + option, this will list the domains that are + authenticated. + type: string + authentication_exception: + description: The participants added here will receive unique meeting invite + links and bypass authentication. + items: + properties: + email: + description: Email address of the participant. + format: email + type: string + name: + description: Name of the participant. + type: string + type: object + type: array + authentication_name: + description: Authentication name set in the [authentication + profile](https://support.zoom.us/hc/en-us/articles/360037117472-Authentication-Profiles-for-Meetings-and-Webinars#h_5c0df2e1-cfd2-469f-bb4a-c77d7c0cca6f). + type: string + authentication_option: + description: "Specify the authentication type for users to join a meeting with `meeting_authentication` setting set to `true`. " + type: string + auto_recording: + default: none + description: "Automatic recording: `local` - Record on local. `cloud` - Record on cloud. `none` - Disabled." + enum: + - local + - cloud + - none + type: string + x-enum-descriptions: + - Record to local device + - Record to cloud + - No Recording + breakout_room: + description: Setting to [pre-assign breakout + rooms](https://support.zoom.us/hc/en-us/articles/360032752671-Pre-assigning-participants-to-breakout-rooms#h_36f71353-4190-48a2-b999-ca129861c1f4). + properties: + enable: + description: Set the value of this field to `true` if you would like to enable + the [breakout room + pre-assign](https://support.zoom.us/hc/en-us/articles/360032752671-Pre-assigning-participants-to-breakout-rooms#h_36f71353-4190-48a2-b999-ca129861c1f4) + option. + type: boolean + rooms: + description: Create room(s). + items: + properties: + name: + description: Name of the breakout room. + type: string + participants: + description: Email addresses of the participants who are to be assigned to the + breakout room. + items: + type: string + type: array + type: object + type: array + type: object + close_registration: + default: false + description: Close registration after event date + type: boolean + cn_meeting: + default: false + description: Host meeting in China. + type: boolean + contact_email: + description: Contact email for registration + type: string + contact_name: + description: Contact name for registration + type: string + custom_keys: + description: Custom keys and values assigned to the meeting. + items: + properties: + key: + description: Custom key associated with the user. + maxLength: 64 + type: string + value: + description: Value of the custom key associated with the user. + maxLength: 256 + type: string + type: object + maxItems: 10 + type: array + encryption_type: + description: >- + Choose between enhanced encryption and [end-to-end + encryption](https://support.zoom.us/hc/en-us/articles/360048660871) + when starting or a meeting. When using end-to-end + encryption, several features (e.g. cloud + recording, phone/SIP/H.323 dial-in) will be + **automatically disabled**. The value of + this field can be one of the following: + + `enhanced_encryption`: Enhanced encryption. Encryption is stored in the cloud if you enable this option. + + + `e2ee`: [End-to-end encryption](https://support.zoom.us/hc/en-us/articles/360048660871). The encryption key is stored in your local device and can not be obtained by anyone else. Enabling this setting also **disables** the following features: join before host, cloud recording, streaming, live transcription, breakout rooms, polling, 1:1 private chat, and meeting reactions. + enum: + - enhanced_encryption + - e2ee + type: string + enforce_login: + description: >- + Only signed in users can join this meeting. + + + **This field is deprecated and will not be supported in the future.** As an alternative, use the "meeting_authentication", "authentication_option" and "authentication_domains" fields to understand the [authentication configurations](https://support.zoom.us/hc/en-us/articles/360037117472-Authentication-Profiles-for-Meetings-and-Webinars) set for the meeting. + type: boolean + enforce_login_domains: + description: >- + Only signed in users with specified domains can join meetings. + + + **This field is deprecated and will not be supported in the future.** As an alternative, use the "meeting_authentication", "authentication_option" and "authentication_domains" fields to understand the [authentication configurations](https://support.zoom.us/hc/en-us/articles/360037117472-Authentication-Profiles-for-Meetings-and-Webinars) set for the meeting. + type: string + global_dial_in_countries: + description: List of global dial-in countries + items: + type: string + type: array + global_dial_in_numbers: + description: Global Dial-in Countries/Regions + items: + properties: + city: + description: City of the number, if any. For example, Chicago. + type: string + country: + description: Country code. For example, BR. + type: string + country_name: + description: Full name of country. For example, Brazil. + type: string + number: + description: Phone number. For example, +1 2332357613. + type: string + type: + description: "Type of number. " + enum: + - toll + - tollfree + type: string + type: object + type: array + host_video: + description: Start video when the host joins the meeting. + type: boolean + in_meeting: + default: false + description: Host meeting in India. + type: boolean + jbh_time: + description: >- + If the value of "join_before_host" field is set to true, this field + can be used to indicate time limits within which a + participant may join a meeting before a host. The + value of this field can be one of the following: + + + * `0`: Allow participant to join anytime. + + * `5`: Allow participant to join 5 minutes before meeting start time. + * `10`: Allow participant to join 10 minutes before meeting start time. + enum: + - 0 + - 5 + - 10 + type: integer + join_before_host: + default: false + description: Allow participants to join the meeting before the host starts the + meeting. Only used for scheduled or recurring + meetings. + type: boolean + language_interpretation: + description: "Language interpretation for meetings. " + properties: + enable: + type: boolean + interpreters: + description: Information associated with the interpreter. + items: + properties: + email: + description: Email address of the interpreter. + format: email + type: string + languages: + description: >- + Languages for interpretation. The string must contain two [country + Ids](https://marketplace.zoom.us/docs/api-reference/other-references/abbreviation-lists#countries) + separated by a comma. + + + For example, if the language is to be interpreted from English to Chinese, the value of this field should be "US,CN". + type: string + type: object + type: array + type: object + meeting_authentication: + description: "`true` - Only authenticated users can join meetings." + type: boolean + mute_upon_entry: + default: false + description: Mute participants upon entry. + type: boolean + participant_video: + description: Start video when participants join the meeting. + type: boolean + registrants_confirmation_email: + description: Send confirmation email to registrants upon successful + registration. + type: boolean + registrants_email_notification: + description: Send email notifications to registrants about approval, + cancellation, denial of the registration. The + value of this field must be set to true in order + to use the `registrants_confirmation_email` field. + type: boolean + registration_type: + default: 1 + description: "Registration type. Used for recurring meeting with fixed time only. `1` - Attendees register once and can attend any of the occurrences. `2` - Attendees need to register for each occurrence to attend. `3` - occurrences to attend." + enum: + - 1 + - 2 + - 3 + type: integer + x-enum-descriptions: + - Attendees register once and can attend any of + the occurrences + - Attendees need to register for each occurrence + to attend + - Attendees register once and can choose one or + more occurrences to attend + show_share_button: + description: >- + Show social share buttons on the meeting registration page. + + This setting only works for meetings that require [registration](https://support.zoom.us/hc/en-us/articles/211579443-Setting-up-registration-for-a-meeting). + type: boolean + use_pmi: + default: false + description: Use a personal meeting ID. Only used for scheduled meetings and + recurring meetings with no fixed time. + type: boolean + waiting_room: + default: false + description: Enable waiting room + type: boolean + watermark: + default: false + description: Add watermark when viewing a shared screen. + type: boolean + type: object + ReccurenceDetails: + description: "Recurrence related meeting informations" + properties: + end_date_time: + description: Select the final date on which the meeting will recur before it is + canceled. Should be in UTC time, such as + 2017-11-25T12:00:00Z. (Cannot be used with + "end_times".) + format: date-time + type: string + end_times: + default: 1 + description: Select how many times the meeting should recur before it is + canceled. (Cannot be used with "end_date_time".) + maximum: 365 + type: integer + monthly_day: + default: 1 + description: >- + Use this field **only if you're scheduling a recurring meeting of + type** `3` to state which day in a month, the + meeting should recur. The value range is from 1 to + 31. + + + For instance, if you would like the meeting to recur on 23rd of each month, provide `23` as the value of this field and `1` as the value of the `repeat_interval` field. Instead, if you would like the meeting to recur every three months, on 23rd of the month, change the value of the `repeat_interval` field to `3`. + type: integer + monthly_week: + description: Use this field **only if you're scheduling a recurring meeting of + type** `3` to state the week of the month when the + meeting should recur. If you use this field, **you + must also use the `monthly_week_day` field to + state the day of the week when the meeting should + recur.** `-1` - Last week of the month.`1` + - First week of the month.`2` - Second week of + the month.`3` - Third week of the + month.`4` - Fourth week of the month. + enum: + - -1 + - 1 + - 2 + - 3 + - 4 + type: integer + x-enum-descriptions: + - Last week + - First week + - Second week + - Third week + - Fourth week + monthly_week_day: + description: >- + Use this field **only if you're scheduling a recurring meeting of + type** `3` to state a specific day in a week when + the monthly meeting should recur. To use this + field, you must also use the `monthly_week` + field. + + + `1` - Sunday.`2` - Monday.`3` - Tuesday.`4` - Wednesday.`5` - Thursday.`6` - Friday.`7` - Saturday. + enum: + - 1 + - 2 + - 3 + - 4 + - 5 + - 6 + - 7 + type: integer + x-enum-descriptions: + - Sunday + - Monday + - Tuesday + - Wednesday + - Thursday + - Friday + - Saturday + repeat_interval: + description: >+ + Define the interval at which the meeting should recur. For + instance, if you would like to schedule a meeting + that recurs every two months, you must set the + value of this field as `2` and the value of the + `type` parameter as `3`. + + + For a daily meeting, the maximum interval you can set is `90` days. For a weekly meeting the maximum interval that you can set is of `12` weeks. For a monthly meeting, there is a maximum of `3` months. + + type: integer + type: + description: Recurrence meeting types:`1` - Daily.`2` - Weekly.`3` - + Monthly. + enum: + - 1 + - 2 + - 3 + type: integer + x-enum-descriptions: + - Daily + - Weekly + - Monthly + weekly_days: + default: "1" + description: >- + This field is required **if you're scheduling a recurring meeting + of type** `2` to state which day(s) of the week + the meeting should repeat. The value for + this field could be a number between `1` to `7` in + string format. For instance, if the meeting should + recur on Sunday, provide `"1"` as the value of + this field. **Note:** If you would like + the meeting to occur on multiple days of a week, + you should provide comma separated values for this + field. For instance, if the meeting should recur + on Sundays and Tuesdays provide `"1,3"` as the + value of this field. + + `1` - Sunday. `2` - Monday.`3` - Tuesday.`4` - Wednesday.`5` - Thursday.`6` - Friday.`7` - Saturday. + enum: + - "1" + - "2" + - "3" + - "4" + - "5" + - "6" + - "7" + type: string + required: + - type + type: object + RequestedMeetingDetails: + description: Meeting object + properties: + agenda: + description: Agenda + type: string + created_at: + description: The date and time at which this meeting was created. + format: date-time + type: string + duration: + description: Meeting duration. + type: integer + h323_password: + description: H.323/SIP room system password + type: string + join_url: + description: URL for participants to join the meeting. This URL should only be + shared with users that you would like to invite for + the meeting. + type: string + occurrences: + description: Array of occurrence objects. + items: + description: Occurence object. This object is only returned for Recurring + Webinars. + properties: + duration: + description: Duration. + type: integer + occurrence_id: + description: "Occurrence ID: Unique Identifier that identifies an occurrence of + a recurring webinar. [Recurring + webinars](https://support.zoom.us/hc/en-us/arti\ + cles/216354763-How-to-Schedule-A-Recurring-Webi\ + nar) can have a maximum of 50 occurrences." + type: string + start_time: + description: Start time. + format: date-time + type: string + status: + description: Occurrence status. + type: string + type: object + type: array + password: + description: >+ + Meeting password. Password may only contain the following + characters: `[a-z A-Z 0-9 @ - _ * !]` + + + If "Require a password when scheduling new meetings" setting has been **enabled** **and** [locked](https://support.zoom.us/hc/en-us/articles/115005269866-Using-Tiered-Settings#locked) for the user, the password field will be autogenerated in the response even if it is not provided in the API request. + + + type: string + pmi: + description: Personal Meeting Id. Only used for scheduled meetings and recurring + meetings with no fixed time. + format: int64 + type: integer + recurrence: + $ref: '#/components/schemas/ReccurenceDetails' + settings: + $ref: '#/components/schemas/MeetingSettings' + start_time: + description: 'Meeting start date-time in UTC/GMT. Example: + "2020-03-31T12:02:00Z"' + format: date-time + type: string + start_url: + description: URL to start the meeting. This URL should only be used by the host + of the meeting and **should not be shared with anyone + other than the host** of the meeting as anyone with + this URL will be able to login to the Zoom Client as + the host of the meeting. + type: string + timezone: + description: Timezone to format start_time + type: string + topic: + description: Meeting topic + maxLength: 200 + type: string + tracking_fields: + description: Tracking fields + items: + properties: + field: + description: Label of the tracking field. + type: string + value: + description: Value for the field. + type: string + visible: + description: >- + Indicates whether the [tracking + field](https://support.zoom.us/hc/en-us/articles/115000293426-Scheduling-Tracking-Fields) + is visible in the meeting scheduling options in + the Zoom Web Portal or not. + + + `true`: Tracking field is visible. + + + `false`: Tracking field is not visible to the users in the meeting options in the Zoom Web Portal but the field was used while scheduling this meeting via API. An invisible tracking field can be used by users while scheduling meetings via API only. + type: boolean + type: object + type: array + type: + default: 2 + description: Meeting Type + enum: + - 1 + - 2 + - 3 + - 8 + type: integer + x-enum-descriptions: + - Instant Meeting + - Scheduled Meeting + - Recurring Meeting with no fixed time + - Recurring Meeting with fixed time + type: object + MeetingMetadata: + description: Meeting Metadata + properties: + assistant_id: + description: Unique identifier of the scheduler who scheduled this meeting on + behalf of the host. This field is only returned if you + used "schedule_for" option in the [Create a Meeting + API + request](https://marketplace.zoom.us/docs/api-reference/zoom-api/meetings/meetingcreate). + type: string + host_email: + description: Email address of the meeting host. + format: email + type: string + id: + description: '[Meeting + ID](https://support.zoom.us/hc/en-us/articles/201362373-What-is-a-Meeting-ID-): + Unique identifier of the meeting in "**long**" + format(represented as int64 data type in JSON), also + known as the meeting number.' + format: int64 + type: integer + registration_url: + description: URL using which registrants can register for a meeting. This field + is only returned for meetings that have enabled + registration. + type: string + type: object + required: + - id + MeetingList: + description: List of meetings + title: Group List + type: object + properties: + meetings: + description: List of Meeting objects. + items: + allOf: + - properties: + agenda: + description: Meeting description. The length of agenda gets truncated to 250 + characters when you list all meetings for a user. To + view the complete agenda of a meeting, retrieve + details for a single meeting + [here](https://marketplace.zoom.us/docs/api-reference/zoom-api/meetings/meeting). + type: string + created_at: + description: "Time of creation. " + format: date-time + type: string + duration: + description: Meeting duration. + type: integer + host_id: + description: ID of the user who is set as the host of the meeting. + type: string + id: + description: Meeting ID - also known as the meeting number in double (int64) + format. + format: int64 + type: integer + join_url: + description: Join URL. + type: string + start_time: + description: Meeting start time. + format: date-time + type: string + timezone: + description: "Timezone to format the meeting start time. " + type: string + topic: + description: Meeting topic. + type: string + type: + description: "Meeting Type: 1 - Instant meeting. 2 - Scheduled meeting. 3 - Recurring meeting with no fixed time. 8 - Recurring meeting with fixed time." + enum: + - 1 + - 2 + - 3 + - 8 + type: integer + x-enum-descriptions: + - Instant Meeting + - Scheduled Meeting + - Recurring Meeting with no fixed time + - Recurring Meeting with fixed time + uuid: + description: Unique Meeting ID. Each meeting instance will generate its own + Meeting UUID. + type: string + type: object + type: array + MeetingPartcipantsList: + description: List of meeting participants + properties: + participants: + description: Array of meeting participant objects. + items: + $ref : '#/components/schemas/PartcipantDetails' + type: array + type: object + PartcipantDetails: + description: Participant's details + properties: + id: + description: Universally unique identifier of the Participant. It is the same as + the User ID of the participant if the + participant joins the meeting by logging into + Zoom. If the participant joins the meeting + without logging in, the value of this field will + be blank. + format: uuid + type: string + name: + description: Participant display name. + type: string + user_email: + description: Email address of the user. This field will be returned if the user + logged into Zoom to join the meeting. + type: string + type: object + securitySchemes: + OAuth: + flows: + authorizationCode: + authorizationUrl: https://zoom.us/oauth/authorize + scopes: {} + tokenUrl: https://zoom.us/oauth/token + type: oauth2 \ No newline at end of file diff --git a/openapi/zoom/types.bal b/openapi/zoom/types.bal new file mode 100644 index 000000000..c7ec33446 --- /dev/null +++ b/openapi/zoom/types.bal @@ -0,0 +1,390 @@ +// Copyright (c) 2021 WSO2 Inc. (http://www.wso2.org) All Rights Reserved. +// +// WSO2 Inc. licenses this file to you under the Apache License, +// Version 2.0 (the "License"); you may not use this file except +// in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +# Meeting Registrnats's Details +public type RegistrantsList record { + # List of registrant objects. + anydata[] registrants?; +}; + +# Pagination Object +public type PaginationObject record { + # The next page token is used to paginate through large result sets. A next page token will be returned whenever the set of available results exceeds the current page size. The expiration period for this token is 15 minutes. + string next_page_token?; + # The number of pages returned for the request made. + int page_count?; + # This field has been deprecated. + int page_number?; + # The number of records returned with a single API call. + int page_size?; + # The total number of all the records available across pages. + int total_records?; +}; + +# Registrant base object +public type RegistrantBaseObject record { + # Registrant's address. + string address?; + # Registrant's city. + string city?; + # A field that allows registrants to provide any questions or comments that they might have. + string comments?; + # Registrant's country. The value of this field must be in two-letter abbreviated form and must match the ID field provided in the [Countries](https://marketplace.zoom.us/docs/api-reference/other-references/abbreviation-lists#countries) table. + string country?; + # Custom questions. + record { string title?; string value?;} [] custom_questions?; + # A valid email address of the registrant. + string email; + # Registrant's first name. + string first_name; + # Registrant's Industry. + string industry?; + # Registrant's job title. + string job_title?; + # Registrant's last name. + string last_name?; + # Number of Employees: `1-20`, `21-50`, `51-100`, `101-500`, `500-1,000`, `1,001-5,000`, `5,001-10,000`, `More than 10,000` + string no_of_employees?; + # Registrant's Organization. + string org?; + # Registrant's Phone number. + string phone?; + # This field can be included to gauge interest of webinar attendees towards buying your product or service. + string purchasing_time_frame?; + # Role in Purchase Process: `Decision Maker`, `Evaluator/Recommender`, `Influencer`, `Not involved` + string role_in_purchase_process?; + # Registrant's State/Province. + string state?; + # Registrant's Zip/Postal Code. + string zip?; +}; + +# List of meetings +public type MeetingList record { + # List of Meeting objects. + record {}[] meetings?; +}; + +# List of meeting participants +public type MeetingPartcipantsList record { + # Array of meeting participant objects. + PartcipantDetails[] participants?; +}; + +# Participant's details +public type PartcipantDetails record { + # Universally unique identifier of the Participant. It is the same as the User ID of the participant if the participant joins the meeting by logging into Zoom. If the participant joins the meeting without logging in, the value of this field will be blank. + string id?; + # Participant display name. + string name?; + # Email address of the user. This field will be returned if the user logged into Zoom to join the meeting. + string user_email?; +}; + +# Meeting settings +public type MeetingSettings record { + # Allow attendees to join the meeting from multiple devices. This setting only works for meetings that require [registration](https://support.zoom.us/hc/en-us/articles/211579443-Setting-up-registration-for-a-meeting). + boolean allow_multiple_devices?; + # Alternative host's emails or IDs: multiple values are separated by a semicolon. + string alternative_hosts?; + # Flag to determine whether to send email notifications to alternative hosts, default value is true. + boolean alternative_hosts_email_notification?; + # The default value is `2`. To enable registration required, set the approval type to `0` or `1`. `0` - Automatically approve. `1` - Manually approve. `2` - No registration required. + int approval_type?; + # Approve or block users from specific regions/countries from joining this meeting. + record { # List of countries/regions from where participants can join this meeting. + string[] approved_list?; # List of countries/regions from where participants can not join this meeting. + string[] denied_list?; # `true`: Setting enabled to either allow users or block users from specific regions to join your meetings. + boolean enable?; # Specify whether to allow users from specific regions to join this meeting; or block users from specific regions from joining this meeting. + string method?;} approved_or_denied_countries_or_regions?; + # Determine how participants can join the audio portion of the meeting. both : Both Telephony and VoIP, telephony :Telephony only, voip:VoIP only. + string audio?; + # If user has configured ["Sign Into Zoom with Specified Domains"](https://support.zoom.us/hc/en-us/articles/360037117472-Authentication-Profiles-for-Meetings-and-Webinars#h_5c0df2e1-cfd2-469f-bb4a-c77d7c0cca6f) option, this will list the domains that are authenticated. + string authentication_domains?; + # The participants added here will receive unique meeting invite links and bypass authentication. + record { # Email address of the participant. + string email?; # Name of the participant. + string name?;} [] authentication_exception?; + # Authentication name set in the [authentication profile](https://support.zoom.us/hc/en-us/articles/360037117472-Authentication-Profiles-for-Meetings-and-Webinars#h_5c0df2e1-cfd2-469f-bb4a-c77d7c0cca6f). + string authentication_name?; + # Specify the authentication type for users to join a meeting with `meeting_authentication` setting set to `true`. + string authentication_option?; + # Automatic recording: `local` - Record on local. `cloud` - Record on cloud. `none` - Disabled. + string auto_recording?; + # Setting to [pre-assign breakout rooms](https://support.zoom.us/hc/en-us/articles/360032752671-Pre-assigning-participants-to-breakout-rooms#h_36f71353-4190-48a2-b999-ca129861c1f4). + record { # Set the value of this field to `true` if you would like to enable the [breakout room pre-assign](https://support.zoom.us/hc/en-us/articles/360032752671-Pre-assigning-participants-to-breakout-rooms#h_36f71353-4190-48a2-b999-ca129861c1f4) option. + boolean enable?; # Create room(s). + record { # Name of the breakout room. + string name?; # Email addresses of the participants who are to be assigned to the breakout room. + string[] participants?;} [] rooms?;} breakout_room?; + # Close registration after event date + boolean close_registration?; + # Host meeting in China. + boolean cn_meeting?; + # Contact email for registration + string contact_email?; + # Contact name for registration + string contact_name?; + # Custom keys and values assigned to the meeting. + record { # Custom key associated with the user. + string 'key?; # Value of the custom key associated with the user. + string value?;} [] custom_keys?; + # Choose between enhanced encryption and [end-to-end encryption](https://support.zoom.us/hc/en-us/articles/360048660871) when starting or a meeting. When using end-to-end encryption, several features (e.g. cloud recording, phone/SIP/H.323 dial-in) will be **automatically disabled**. The value of this field can be one of the following: + string encryption_type?; + # Only signed in users can join this meeting. + boolean enforce_login?; + # Only signed in users with specified domains can join meetings. + string enforce_login_domains?; + # List of global dial-in countries + string[] global_dial_in_countries?; + # Global Dial-in Countries/Regions + record { # City of the number, if any. For example, Chicago. + string city?; # Country code. For example, BR. + string country?; # Full name of country. For example, Brazil. + string country_name?; # Phone number. For example, +1 2332357613. + string number?; # Type of number. + string 'type?;} [] global_dial_in_numbers?; + # Start video when the host joins the meeting. + boolean host_video?; + # Host meeting in India. + boolean in_meeting?; + # If the value of "join_before_host" field is set to true, this field can be used to indicate time limits within which a participant may join a meeting before a host. The value of this field can be one of the following: + int jbh_time?; + # Allow participants to join the meeting before the host starts the meeting. Only used for scheduled or recurring meetings. + boolean join_before_host?; + # Language interpretation for meetings. + record { boolean enable?; # Information associated with the interpreter. + record { # Email address of the interpreter. + string email?; # Languages for interpretation. The string must contain two [country Ids](https://marketplace.zoom.us/docs/api-reference/other-references/abbreviation-lists#countries) separated by a comma. + string languages?;} [] interpreters?;} language_interpretation?; + # `true` - Only authenticated users can join meetings. + boolean meeting_authentication?; + # Mute participants upon entry. + boolean mute_upon_entry?; + # Start video when participants join the meeting. + boolean participant_video?; + # Send confirmation email to registrants upon successful registration. + boolean registrants_confirmation_email?; + # Send email notifications to registrants about approval, cancellation, denial of the registration. The value of this field must be set to true in order to use the `registrants_confirmation_email` field. + boolean registrants_email_notification?; + # Registration type. Used for recurring meeting with fixed time only. `1` - Attendees register once and can attend any of the occurrences. `2` - Attendees need to register for each occurrence to attend. `3` - occurrences to attend. + int registration_type?; + # Show social share buttons on the meeting registration page. + boolean show_share_button?; + # Use a personal meeting ID. Only used for scheduled meetings and recurring meetings with no fixed time. + boolean use_pmi?; + # Enable waiting room + boolean waiting_room?; + # Add watermark when viewing a shared screen. + boolean watermark?; +}; + +# Detailed Meeting Metadata +public type MeetingFullMetadata record { + # Unique identifier of the scheduler who scheduled this meeting on behalf of the host. This field is only returned if you used "schedule_for" option in the [Create a Meeting API request](https://marketplace.zoom.us/docs/api-reference/zoom-api/meetings/meetingcreate). + string assistant_id?; + # Email address of the meeting host. + string host_email?; + # ID of the user who is set as host of meeting. + string host_id?; + # [Meeting ID](https://support.zoom.us/hc/en-us/articles/201362373-What-is-a-Meeting-ID-): Unique identifier of the meeting in "**long**" format(represented as int64 data type in JSON), also known as the meeting number. + int id?; + # Unique meeting ID. Each meeting instance will generate its own Meeting UUID (i.e., after a meeting ends, a new UUID will be generated for the next instance of the meeting). You can retrieve a list of UUIDs from past meeting instances using [this API](https://marketplace.zoom.us/docs/api-reference/zoom-api/meetings/pastmeetings) . Please double encode your UUID when using it for API calls if the UUID begins with a '/'or contains '//' in it. + string uuid?; +}; + +# Meeting Metadata +public type MeetingMetadata record { + # Unique identifier of the scheduler who scheduled this meeting on behalf of the host. This field is only returned if you used "schedule_for" option in the [Create a Meeting API request](https://marketplace.zoom.us/docs/api-reference/zoom-api/meetings/meetingcreate). + string assistant_id?; + # Email address of the meeting host. + string host_email?; + # [Meeting ID](https://support.zoom.us/hc/en-us/articles/201362373-What-is-a-Meeting-ID-): Unique identifier of the meeting in "**long**" format(represented as int64 data type in JSON), also known as the meeting number. + int id; + # URL using which registrants can register for a meeting. This field is only returned for meetings that have enabled registration. + string registration_url?; +}; + +# Base object for meeting +public type MeetingDetails record { + # Meeting description. + string agenda?; + # Meeting duration (minutes). Used for scheduled meetings only. + int duration?; + # Passcode to join the meeting. + string password?; + # Recurrence related meeting informations + ReccurenceDetails recurrence?; + # If you would like to schedule this meeting for someone else in your account, provide the Zoom user id or email address of the user here. + string schedule_for?; + # Meeting settings + MeetingSettingsInRequest settings?; + # Meeting start time. We support two formats for `start_time` - local time and GMT.To set time as GMT the format should be `yyyy-MM-dd`T`HH:mm:ssZ`. To set time using a specific timezone, use `yyyy-MM-dd`T`HH:mm:ss` format and specify the timezone id in the `timezone` field OR leave it blank and the timezone set on your Zoom account will be used. You can also set the time as UTC as the timezone field + string start_time?; + # Unique identifier of the admin meeting template. To create admin meeting templates, contact the Zoom support team. + string template_id?; + # Time zone to format start_time. For example, "America/Los_Angeles". For scheduled meetings only. Please reference our [time zone](https://marketplace.zoom.us/docs/api-reference/other-references/abbreviation-lists#timezones) list for supported time zones and their formats. + string timezone?; + # Meeting topic. + string topic?; + # Tracking fields + record { # Label of the tracking field. + string 'field; # Tracking fields value + string value?;} [] tracking_fields?; + # Meeting Type: 1 - Instant meeting. 2 - Scheduled meeting. 3 - Recurring meeting with no fixed time. 8 - Recurring meeting with fixed time. + int 'type?; +}; + +# Meeting object +public type RequestedMeetingDetails record { + # Agenda + string agenda?; + # The date and time at which this meeting was created. + string created_at?; + # Meeting duration. + int duration?; + # H.323/SIP room system password + string h323_password?; + # URL for participants to join the meeting. This URL should only be shared with users that you would like to invite for the meeting. + string join_url?; + # Array of occurrence objects. + record { # Duration. + int duration?; # Occurrence ID: Unique Identifier that identifies an occurrence of a recurring webinar. [Recurring webinars](https://support.zoom.us/hc/en-us/articles/216354763-How-to-Schedule-A-Recurring-Webinar) can have a maximum of 50 occurrences. + string occurrence_id?; # Start time. + string start_time?; # Occurrence status. + string status?;} [] occurrences?; + # Meeting password. Password may only contain the following characters: `[a-z A-Z 0-9 @ - _ * !]` + string password?; + # Personal Meeting Id. Only used for scheduled meetings and recurring meetings with no fixed time. + int pmi?; + # Recurrence related meeting informations + ReccurenceDetails recurrence?; + # Meeting settings + MeetingSettings settings?; + # Meeting start date-time in UTC/GMT. Example: "2020-03-31T12:02:00Z" + string start_time?; + # URL to start the meeting. This URL should only be used by the host of the meeting and **should not be shared with anyone other than the host** of the meeting as anyone with this URL will be able to login to the Zoom Client as the host of the meeting. + string start_url?; + # Timezone to format start_time + string timezone?; + # Meeting topic + string topic?; + # Tracking fields + record { # Label of the tracking field. + string 'field?; # Value for the field. + string value?; # Indicates whether the [tracking field](https://support.zoom.us/hc/en-us/articles/115000293426-Scheduling-Tracking-Fields) is visible in the meeting scheduling options in the Zoom Web Portal or not. + boolean visible?;} [] tracking_fields?; + # Meeting Type + int 'type?; +}; + +# Meeting settings +public type MeetingSettingsInRequest record { + # Enable additional data center regions for this meeting. Provide the value in the form of array of country code(s) for the countries which are available as data center regions + string[] additional_data_center_regions?; + # If set to `true`, attendees will be allowed to join a meeting from multiple devices. + boolean allow_multiple_devices?; + # Alternative host's emails or IDs: multiple values separated by a comma. + string alternative_hosts?; + # Flag to determine whether to send email notifications to alternative hosts, default value is true. + boolean alternative_hosts_email_notification?; + # The default value is `2`. To enable registration required, set the approval type to `0` or `1`. `0` - Automatically approve. `1` - Manually approve. `2` - No registration required. + int approval_type?; + # Approve or block users from specific regions/countries from joining this meeting. + record { # List of countries/regions from where participants can join this meeting. + string[] approved_list?; # List of countries/regions from where participants can not join this meeting. + string[] denied_list?; # `true`: Setting enabled to either allow users or block users from specific regions to join your meetings. `false`: Setting disabled. + boolean enable?; # Specify whether to allow users from specific regions to join thismeeting; or block users from specific regions from oining this meeting. Values: approve or deny + string method?;} approved_or_denied_countries_or_regions?; + # Determine how participants can join the audio portion of the meeting. both : Both Telephony and VoIP, telephony :Telephony only, voip:VoIP only. + string audio?; + # Meeting authentication domains. This option, allows you to specify the rule so that Zoom users, whose email address contains a certain domain, can join the meeting. + string authentication_domains?; + # Specify the authentication type for users to join a meeting with `meeting_authentication` setting set to `true`. + string authentication_option?; + # Automatic recording: local - Record on local.cloud - Record on cloud.none - Disabled. + string auto_recording?; + # Setting to pre-assign breakout rooms + record { # Set the value of this field to `true` if you would like to enable the pre-assigned breakout rooms. + boolean enable?; # Create room(s). + record { # Name of the breakout room. + string name?; # Email addresses of the participants who are to be assigned to the breakout room. + string[] participants?;} [] rooms?;} breakout_room?; + # Close registration after event date + boolean close_registration?; + # Host meeting in China. + boolean cn_meeting?; + # Contact email for registration + string contact_email?; + # Contact name for registration + string contact_name?; + # Choose between enhanced encryption and end-to-end encryption. Values: enhanced_encryption, e2ee + string encryption_type?; + # List of global dial-in countries + string[] global_dial_in_countries?; + # Start video when the host joins the meeting. + boolean host_video?; + # Host meeting in India. + boolean in_meeting?; + # If the value of join_before_host field is set to true, this field can be used to indicate time limits within which a participant may join a meeting before a host. The value of this field can be one of the following: 0: Allow participant to join anytime. 5: Allow participant to join 5 minutes before meeting start time. 10: Allow participant to join 10 minutes before meeting start time. + int jbh_time?; + # Allow participants to join the meeting before the host starts the meeting. This field can only used for scheduled or recurring meetings. + boolean join_before_host?; + # Language interpretation for meetings. + record { # Indicate whether or not you would like to enable language interpretation or this meeting. + boolean enable?; # Information associated with the interpreter. + record { # Email address of the interpreter. + string email?; # Languages for interpretation. The string must contain two separated by a comma. For example, if the language is to be interpreted from English to Chinese, the value of this field should be US,CN. + string languages?;} [] interpreters?;} language_interpretation?; + # Only authenticated users can join meeting if the value of this field is set to `true`. + boolean meeting_authentication?; + # Mute participants upon entry. + boolean mute_upon_entry?; + # Start video when participants join the meeting. + boolean participant_video?; + # Send email notifications to registrants about approval, cancellation, denial of the registration. The value of this field must be set to true in order to use the `registrants_confirmation_email` field. + boolean registrants_email_notification?; + # Registration type. Used for recurring meeting with fixed time only. `1` - Attendees register once and can attend any of the occurrences. `2` - Attendees need to register for each occurrence to attend. `3` - occurrences to attend. + int registration_type?; + # If set to `true`, the registration page for the meeting will include social share buttons. + boolean show_share_button?; + # Use Personal Meeting ID instead of an automatically generated meeting ID. It can only be used for scheduled meetings, instant meetings and recurring meetings with no fixed time. + boolean use_pmi?; + # Enable waiting room. Note that if the value of this field is set to `true`, it will override and disable the `join_before_host` setting. + boolean waiting_room?; + # Add watermark when viewing a shared screen. + boolean watermark?; +}; + +# Recurrence related meeting informations +public type ReccurenceDetails record { + # Select the final date on which the meeting will recur before it is canceled. Should be in UTC time, such as 2017-11-25T12:00:00Z. (Cannot be used with "end_times".) + string end_date_time?; + # Select how many times the meeting should recur before it is canceled. (Cannot be used with "end_date_time".) + int end_times?; + # Use this field **only if you're scheduling a recurring meeting of type** `3` to state which day in a month, the meeting should recur. The value range is from 1 to 31. + int monthly_day?; + # Use this field **only if you're scheduling a recurring meeting of type** `3` to state the week of the month when the meeting should recur. If you use this field, **you must also use the `monthly_week_day` field to state the day of the week when the meeting should recur.** `-1` - Last week of the month.`1` - First week of the month.`2` - Second week of the month.`3` - Third week of the month.`4` - Fourth week of the month. + int monthly_week?; + # Use this field **only if you're scheduling a recurring meeting of type** `3` to state a specific day in a week when the monthly meeting should recur. To use this field, you must also use the `monthly_week` field. + int monthly_week_day?; + # Define the interval at which the meeting should recur. For instance, if you would like to schedule a meeting that recurs every two months, you must set the value of this field as `2` and the value of the `type` parameter as `3`. + int repeat_interval?; + # Recurrence meeting types:`1` - Daily.`2` - Weekly.`3` - Monthly. + int 'type; + # This field is required **if you're scheduling a recurring meeting of type** `2` to state which day(s) of the week the meeting should repeat. The value for this field could be a number between `1` to `7` in string format. For instance, if the meeting should recur on Sunday, provide `"1"` as the value of this field. **Note:** If you would like the meeting to occur on multiple days of a week, you should provide comma separated values for this field. For instance, if the meeting should recur on Sundays and Tuesdays provide `"1,3"` as the value of this field. + string weekly_days?; +}; From 88850697ca2f0f364a3f4c2b02939f74a6f60bcb Mon Sep 17 00:00:00 2001 From: aneeshafedo Date: Fri, 18 Jun 2021 18:04:05 +0530 Subject: [PATCH 05/14] remove checkpanic --- openapi/zoom/client.bal | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/openapi/zoom/client.bal b/openapi/zoom/client.bal index 34d8ab59c..2f4b96927 100644 --- a/openapi/zoom/client.bal +++ b/openapi/zoom/client.bal @@ -150,7 +150,7 @@ public client class Client { remote isolated function listMeetings(@display {label: "User Id"} string userId, @display {label: "Meeting Type"} string? 'type = "live", @display {label: "Page Size"} int? page_size = 30, @display {label: "Next Page Token"} string? next_page_token = (), @display {label: "Page Number"} string? page_number = ()) returns CompoundListMeetingsResponse|error { string path = string `/users/${userId}/meetings`; map queryParam = {'type: 'type, page_size: page_size, next_page_token: next_page_token, page_number: page_number}; - path = path + getPathForQueryParam(queryParam); + path = path + check getPathForQueryParam(queryParam); CompoundListMeetingsResponse response = check self.clientEp-> get(path, targetType = CompoundListMeetingsResponse); return response; } @@ -181,7 +181,7 @@ public client class Client { remote isolated function listMeetingRegistrants(@display {label: "Meeting Id"} int meetingId, @display {label: "Occurence Id"} string? occurrence_id = (), @display {label: "Registrant Status"} string? status = "approved", @display {label: "Page Size"} int? page_size = 30, @display {label: "Page Number"} int? page_number = 1, @display {label: "Next Page Token"} string? next_page_token = ()) returns CompoundListMeetingRegistrantsResponse|error { string path = string `/meetings/${meetingId}/registrants`; map queryParam = {occurrence_id: occurrence_id, status: status, page_size: page_size, page_number: page_number, next_page_token: next_page_token}; - path = path + getPathForQueryParam(queryParam); + path = path + check getPathForQueryParam(queryParam); CompoundListMeetingRegistrantsResponse response = check self.clientEp-> get(path, targetType = CompoundListMeetingRegistrantsResponse); return response; } @@ -195,7 +195,7 @@ public client class Client { remote isolated function addMeetingRegistrant(@display {label: "Meeting Id"} int meetingId, CompoundAddMeetingRegistrantRequest payload, @display {label: "Occurence Id"} string? occurrence_ids = ()) returns AddMeetingRegistrantResponse|error { string path = string `/meetings/${meetingId}/registrants`; map queryParam = {occurrence_ids: occurrence_ids}; - path = path + getPathForQueryParam(queryParam); + path = path + check getPathForQueryParam(queryParam); http:Request request = new; json jsonBody = check payload.cloneWithType(json); request.setPayload(jsonBody); @@ -212,7 +212,7 @@ public client class Client { remote isolated function getMeetingById(@display {label: "Meeting Id"} int meetingId, @display {label: "Occurence Id"} string? occurrence_id = (), @display {label: "Show Previous Occurrences"} boolean? show_previous_occurrences = ()) returns CompoundGetMeetingByIdResponse|error { string path = string `/meetings/${meetingId}`; map queryParam = {occurrence_id: occurrence_id, show_previous_occurrences: show_previous_occurrences}; - path = path + getPathForQueryParam(queryParam); + path = path + check getPathForQueryParam(queryParam); CompoundGetMeetingByIdResponse response = check self.clientEp-> get(path, targetType = CompoundGetMeetingByIdResponse); return response; } @@ -227,7 +227,7 @@ public client class Client { remote isolated function deleteMeeting(@display {label: "Meeting Id"} int meetingId, @display {label: "Occurence Id"} string? occurrence_id = (), @display {label: "Schedule for Reminder"} boolean? schedule_for_reminder = (), @display {label: "Meeting Cancellation Reminder"} string? cancel_meeting_reminder = ()) returns error? { string path = string `/meetings/${meetingId}`; map queryParam = {occurrence_id: occurrence_id, schedule_for_reminder: schedule_for_reminder, cancel_meeting_reminder: cancel_meeting_reminder}; - path = path + getPathForQueryParam(queryParam); + path = path + check getPathForQueryParam(queryParam); http:Request request = new; //TODO: Update the request as needed; _ = check self.clientEp-> delete(path, request, targetType =http:Response); @@ -242,7 +242,7 @@ public client class Client { remote isolated function listPastMeetingParticipants(@display {label: "Meeting UUID"} string meetingUUID, @display {label: "Page Size"} int? page_size = 30, @display {label: "Next Page Token"} string? next_page_token = ()) returns CompoundListPastMeetingParticipantsResponse|error { string path = string `/past_meetings/${meetingUUID}/participants`; map queryParam = {page_size: page_size, next_page_token: next_page_token}; - path = path + getPathForQueryParam(queryParam); + path = path + check getPathForQueryParam(queryParam); CompoundListPastMeetingParticipantsResponse response = check self.clientEp-> get(path, targetType = CompoundListPastMeetingParticipantsResponse); return response; } @@ -260,7 +260,7 @@ public client class Client { remote isolated function listWebinarRegistrants(@display {label: "Webinar Id"} int webinarId, @display {label: "Meeting Occurence Id"} string? occurrence_id = (), @display {label: "Status"} string? status = "approved", @display {label: "Tracking Source Id"} string? tracking_source_id = (), @display {label: "Page Size"} int? page_size = 30, @display {label: "Page Number"} int? page_number = 1, @display {label: "Next Page Token"} string? next_page_token = ()) returns CompoundListWebinarRegistrantsResponse|error { string path = string `/webinars/${webinarId}/registrants`; map queryParam = {occurrence_id: occurrence_id, status: status, tracking_source_id: tracking_source_id, page_size: page_size, page_number: page_number, next_page_token: next_page_token}; - path = path + getPathForQueryParam(queryParam); + path = path + check getPathForQueryParam(queryParam); CompoundListWebinarRegistrantsResponse response = check self.clientEp-> get(path, targetType = CompoundListWebinarRegistrantsResponse); return response; } @@ -274,7 +274,7 @@ public client class Client { remote isolated function listWebinarParticipants(@display {label: "Webinar Id"} string webinarId, @display {label: "Page Size"} int? page_size = 30, @display {label: "Next Page Token"} string? next_page_token = ()) returns ListWebinarParticipantsResponse|error { string path = string `/past_webinars/${webinarId}/participants`; map queryParam = {page_size: page_size, next_page_token: next_page_token}; - path = path + getPathForQueryParam(queryParam); + path = path + check getPathForQueryParam(queryParam); ListWebinarParticipantsResponse response = check self.clientEp-> get(path, targetType = ListWebinarParticipantsResponse); return response; } @@ -289,7 +289,7 @@ public client class Client { remote isolated function listWebinarAbsentees(@display {label: "Webinar UUID"} string WebinarUUID, @display {label: "Occurence Id"} string? occurrence_id = (), @display {label: "Page Size"} int? page_size = 30, @display {label: "Next Page Token"} string? next_page_token = ()) returns CompoundListWebinarAbsenteesResponse|error { string path = string `/past_webinars/${WebinarUUID}/absentees`; map queryParam = {occurrence_id: occurrence_id, page_size: page_size, next_page_token: next_page_token}; - path = path + getPathForQueryParam(queryParam); + path = path + check getPathForQueryParam(queryParam); CompoundListWebinarAbsenteesResponse response = check self.clientEp-> get(path, targetType = CompoundListWebinarAbsenteesResponse); return response; } @@ -299,7 +299,7 @@ public client class Client { # # + queryParam - Query parameter map # + return - Returns generated Path or error at failure of client initialization -isolated function getPathForQueryParam(map queryParam) returns string { +isolated function getPathForQueryParam(map queryParam) returns string|error { string[] param = []; param[param.length()] = "?"; foreach var [key, value] in queryParam.entries() { @@ -313,7 +313,7 @@ isolated function getPathForQueryParam(map queryParam) returns str } param[param.length()] = "="; if value is string { - string updateV = checkpanic url:encode(value, "UTF-8"); + string updateV = check url:encode(value, "UTF-8"); param[param.length()] = updateV; } else { param[param.length()] = value.toString(); From 4eee68a646ad4ff3674b3bdba26845ce013cb922 Mon Sep 17 00:00:00 2001 From: aneeshafedo Date: Fri, 18 Jun 2021 18:20:11 +0530 Subject: [PATCH 06/14] add sendgrid connector --- openapi/sendgrid/.gitignore | 1 + openapi/sendgrid/Ballerina.toml | 11 + openapi/sendgrid/Package.md | 18 + openapi/sendgrid/client.bal | 305 ++++++++ openapi/sendgrid/openapi.yaml | 1247 +++++++++++++++++++++++++++++++ openapi/sendgrid/types.bal | 102 +++ 6 files changed, 1684 insertions(+) create mode 100644 openapi/sendgrid/.gitignore create mode 100644 openapi/sendgrid/Ballerina.toml create mode 100644 openapi/sendgrid/Package.md create mode 100644 openapi/sendgrid/client.bal create mode 100644 openapi/sendgrid/openapi.yaml create mode 100644 openapi/sendgrid/types.bal diff --git a/openapi/sendgrid/.gitignore b/openapi/sendgrid/.gitignore new file mode 100644 index 000000000..1de565933 --- /dev/null +++ b/openapi/sendgrid/.gitignore @@ -0,0 +1 @@ +target \ No newline at end of file diff --git a/openapi/sendgrid/Ballerina.toml b/openapi/sendgrid/Ballerina.toml new file mode 100644 index 000000000..32d1dd0d5 --- /dev/null +++ b/openapi/sendgrid/Ballerina.toml @@ -0,0 +1,11 @@ +[package] +org = "ballerinax" +name = "sendgrid" +version = "0.1.0" +authors = ["Ballerina"] +license= ["Apache-2.0"] +keywords = ["sendgrid", "send mail", "sendgrid alerts"] +repository = "https://github.com/ballerina-platform/ballerinax-openapi-connectors" + +[build-options] +observabilityIncluded = true \ No newline at end of file diff --git a/openapi/sendgrid/Package.md b/openapi/sendgrid/Package.md new file mode 100644 index 000000000..5518e5093 --- /dev/null +++ b/openapi/sendgrid/Package.md @@ -0,0 +1,18 @@ +Connects to Sendgrid API from Ballerina. + +## Module Overview + +The WorldBank connector consume the data exposed in https://api.sendgrid.com/v3. It is currently supporting the following operations. + +- Send Mail +- Retrieve all Alerts +- Create a new Alert +- List all Subusers +- Create Subuser +- Retrieve all Blocks + +## Compatibility + +| Ballerina Language Versions | Sendgrid API | +|:----------------------------:|:------------------------:| +| Swan Lake Alpha 5 | v3 | \ No newline at end of file diff --git a/openapi/sendgrid/client.bal b/openapi/sendgrid/client.bal new file mode 100644 index 000000000..490ccfcbc --- /dev/null +++ b/openapi/sendgrid/client.bal @@ -0,0 +1,305 @@ +// Copyright (c) 2021 WSO2 Inc. (http://www.wso2.org) All Rights Reserved. +// +// WSO2 Inc. licenses this file to you under the Apache License, +// Version 2.0 (the "License"); you may not use this file except +// in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +import ballerina/http; +import ballerina/url; +import ballerina/lang.'string; + +public type ClientConfig record { + http:BearerTokenConfig authConfig; + http:ClientSecureSocket secureSocketConfig?; +}; + +# Mail content +public type SendMailRequest record { + # An object allowing you to specify how to handle unsubscribes. + record { # The unsubscribe group to associate with this email. + int group_id; # An array containing the unsubscribe groups that you would like to be displayed on the unsubscribe preferences page. + int[] groups_to_display?;} asm?; + # An array of objects in which you can specify any attachments you want to include. + record { # The Base64 encoded content of the attachment. + string content; # The content id for the attachment. This is used when the disposition is set to “inline” and the attachment is an image, allowing the file to be displayed within the body of your email. + string content_id?; # The content-disposition of the attachment specifying how you would like the attachment to be displayed. For example, “inline” results in the attached file being displayed automatically within the message while “attachment” results in the attached file requiring some action to be taken before it is displayed (e.g. opening or downloading the file). + string disposition?; # The filename of the attachment. + string filename; # The mime type of the content you are attaching. For example, “text/plain” or “text/html”. + string 'type?;} [] attachments?; + # This ID represents a batch of emails to be sent at the same time. Including a batch_id in your request allows you include this email in that batch, and also enables you to cancel or pause the delivery of that batch. For more information, see https://sendgrid.com/docs/API_Reference/Web_API_v3/cancel_schedule_send.html + string batch_id?; + # An array of category names for this message. Each category name may not exceed 255 characters. + string[] categories?; + # An array in which you may specify the content of your email. You can include multiple mime types of content, but you must specify at least one mime type. To include more than one mime type, simply add another object to the array containing the `type` and `value` parameters. + record { # The mime type of the content you are including in your email. For example, “text/plain” or “text/html”. + string 'type; # The actual content of the specified mime type that you are including in your email. + string value;} [] content; + # Values that are specific to the entire send that will be carried along with the email and its activity data. Substitutions will not be made on custom arguments, so any string that is entered into this parameter will be assumed to be the custom argument that you would like to be used. This parameter is overridden by personalizations[x].custom_args if that parameter has been defined. Total custom args size may not exceed 10,000 bytes. + record {} custom_args?; + # Email details + EmailObject 'from; + # An object containing key/value pairs of header names and the value to substitute for them. You must ensure these are properly encoded if they contain unicode characters. Must not be one of the reserved headers. + record {} headers?; + # The IP Pool that you would like to send this email from. + string ip_pool_name?; + # A collection of different mail settings that you can use to specify how you would like this email to be handled. + record { # This allows you to have a blind carbon copy automatically sent to the specified email address for every email that is sent. + record { # The email address that you would like to receive the BCC. + string email?; # Indicates if this setting is enabled. + boolean enable?;} bcc?; # Allows you to bypass all unsubscribe groups and suppressions to ensure that the email is delivered to every single recipient. This should only be used in emergencies when it is absolutely necessary that every recipient receives your email. + record { # Indicates if this setting is enabled. + boolean enable?;} bypass_list_management?; # The default footer that you would like included on every email. + record { # Indicates if this setting is enabled. + boolean enable?; # The HTML content of your footer. + string html?; # The plain text content of your footer. + string text?;} footer?; # This allows you to send a test email to ensure that your request body is valid and formatted correctly. + record { # Indicates if this setting is enabled. + boolean enable?;} sandbox_mode?; # This allows you to test the content of your email for spam. + record { # Indicates if this setting is enabled. + boolean enable?; # An Inbound Parse URL that you would like a copy of your email along with the spam report to be sent to. + string post_to_url?; # The threshold used to determine if your content qualifies as spam on a scale from 1 to 10, with 10 being most strict, or most likely to be considered as spam. + int threshold?;} spam_check?;} mail_settings?; + # An array of messages and their metadata. Each object within personalizations can be thought of as an envelope - it defines who should receive an individual message and how that message should be handled. + record { # An array of recipients who will receive a blind carbon copy of your email. Each object within this array may contain the name, but must always contain the email, of a recipient. + EmailObject[] bcc?; # An array of recipients who will receive a copy of your email. Each object within this array may contain the name, but must always contain the email, of a recipient. + EmailObject[] cc?; # Values that are specific to this personalization that will be carried along with the email and its activity data. Substitutions will not be made on custom arguments, so any string that is entered into this parameter will be assumed to be the custom argument that you would like to be used. May not exceed 10,000 bytes. + record {} custom_args?; # A collection of JSON key/value pairs allowing you to specify specific handling instructions for your email. You may not overwrite the following headers: x-sg-id, x-sg-eid, received, dkim-signature, Content-Type, Content-Transfer-Encoding, To, From, Subject, Reply-To, CC, BCC + record {} headers?; # A unix timestamp allowing you to specify when you want your email to be delivered. Scheduling more than 72 hours in advance is forbidden. + int send_at?; # The subject of your email. Char length requirements, according to the RFC - http://stackoverflow.com/questions/1592291/what-is-the-email-subject-length-limit#answer-1592310 + string subject?; # A collection of key/value pairs following the pattern "substitution_tag":"value to substitute". All are assumed to be strings. These substitutions will apply to the text and html content of the body of your email, in addition to the `subject` and `reply-to` parameters. + record {} substitutions?; # An array of recipients. Each object within this array may contain the name, but must always contain the email, of a recipient. + EmailObject[] to;} [] personalizations; + # Email details + EmailObject reply_to?; + # An object of key/value pairs that define block sections of code to be used as substitutions. + record {} sections?; + # A unix timestamp allowing you to specify when you want your email to be delivered. This may be overridden by the personalizations[x].send_at parameter. Scheduling more ta 72 hours in advance is forbidden. + int send_at?; + # The global, or “message level”, subject of your email. This may be overridden by personalizations[x].subject. + string subject; + # The id of a template that you would like to use. If you use a template that contains a subject and content (either text or html), you do not need to specify those at the personalizations nor message level. + string template_id?; + # Settings to determine how you would like to track the metrics of how your recipients interact with your email. + record { # Allows you to track whether a recipient clicked a link in your email. + record { # Indicates if this setting is enabled. + boolean enable?; # Indicates if this setting should be included in the text/plain portion of your email. + boolean enable_text?;} click_tracking?; # Allows you to enable tracking provided by Google Analytics. + record { # Indicates if this setting is enabled. + boolean enable?; # The name of the campaign. + string utm_campaign?; # Used to differentiate your campaign from advertisements. + string utm_content?; # Name of the marketing medium. (e.g. Email) + string utm_medium?; # Name of the referrer source. (e.g. Google, SomeDomain.com, or Marketing Email) + string utm_source?; # Used to identify any paid keywords. + string utm_term?;} ganalytics?; # Allows you to track whether the email was opened or not, but including a single pixel image in the body of the content. When the pixel is loaded, we can log that the email was opened. + record { # Indicates if this setting is enabled. + boolean enable?; # Allows you to specify a substitution tag that you can insert in the body of your email at a location that you desire. This tag will be replaced by the open tracking pixel. + string substitution_tag?;} open_tracking?; # Allows you to insert a subscription management link at the bottom of the text and html bodies of your email. If you would like to specify the location of the link within your email, you may use the substitution_tag. + record { # Indicates if this setting is enabled. + boolean enable?; # HTML to be appended to the email, with the subscription tracking link. You may control where the link is by using the tag <% %> + string html?; # A tag that will be replaced with the unsubscribe URL. for example: [unsubscribe_url]. If this parameter is used, it will override both the `text` and `html` parameters. The URL of the link will be placed at the substitution tag’s location, with no additional formatting. + string substitution_tag?; # Text to be appended to the email, with the subscription tracking link. You may control where the link is by using the tag <% %> + string text?;} subscription_tracking?;} tracking_settings?; +}; + +public type AlertResponseArr AlertResponse[]; + +# Alert Content +public type PostAlertsRequest record { + # The email address the alert will be sent to. + string? email_to; + # Required for stats_notification. How frequently the alert will be sent. Example: daily + string frequency?; + # Required for usage_alert. When this usage threshold is reached, the alert will be sent. Example: 90 + int percentage?; + # The type of alert you want to create. Can be either usage_limit or stats_notification. Example: usage_limit + string 'type; +}; + +# Created alert details +public type PostAlertsResponse record { + # A Unix timestamp indicating when the alert was created. + int created_at; + # The email address that the alert will be sent to. + string email_to; + # If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example, "daily", "weekly", or "monthly". + string frequency?; + # The ID of the alert. + int id; + # If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent. + int percentage?; + # The type of alert. + string 'type; + # A Unix timestamp indicating when the alert was last modified. + int updated_at; +}; + +public type SubuserArr Subuser[]; + +# New subuser details +public type PostSubusersRequest record { + # The email address of the subuser. + string email; + # The IP addresses that should be assigned to this subuser. + string[] ips; + # The password this subuser will use when logging into SendGrid. + string password; + # The username for this subuser. + string username; +}; + +public type SuppressionBlocksArr SuppressionBlocks[]; + +# Client endpoint for Sendgrid API +# +# + clientEp - Connector http endpoint +@display {label: "Sendgrid Client"} +public client class Client { + http:Client clientEp; + public isolated function init(ClientConfig clientConfig, string serviceUrl = "https://api.sendgrid.com/v3") returns error? { + http:ClientSecureSocket? secureSocketConfig = clientConfig?.secureSocketConfig; + http:Client httpEp = check new (serviceUrl, { auth: clientConfig.authConfig, secureSocket: secureSocketConfig }); + self.clientEp = httpEp; + } + # Send Mail + # + # + payload - Mail content + # + return - No Content + @display {label: "Send Email"} + remote isolated function sendMail(@display {label: "Email Content"} SendMailRequest payload) returns error? { + string path = string `/mail/send`; + http:Request request = new; + json jsonBody = check payload.cloneWithType(json); + request.setPayload(jsonBody); + _ = check self.clientEp-> post(path, request, targetType=http:Response); + } + # Retrieve all alerts + # + # + 'on\-behalf\-of - The subuser's username. This header generates the API call as if the subuser account was making the call. + # + return - Details related to alerts + @display {label: "Get All Alerts"} + remote isolated function getAlerts(@display {label: "Subuser's Username"} string? 'on\-behalf\-of = ()) returns AlertResponseArr|error { + string path = string `/alerts`; + map headerValues = {'on\-behalf\-of: 'on\-behalf\-of}; + map accHeaders = getMapForHeaders(headerValues); + AlertResponseArr response = check self.clientEp-> get(path, accHeaders, targetType = AlertResponseArr); + return response; + } + # Create a new Alert + # + # + payload - Alert Content + # + 'on\-behalf\-of - The subuser's username. This header generates the API call as if the subuser account was making the call. + # + return - Created alert details + @display {label: "Create Alert"} + remote isolated function postAlerts(@display {label: "Alert Content"} PostAlertsRequest payload, @display {label: "Subuser's Username"} string? 'on\-behalf\-of = ()) returns PostAlertsResponse|error { + string path = string `/alerts`; + map headerValues = {'on\-behalf\-of: 'on\-behalf\-of}; + map accHeaders = getMapForHeaders(headerValues); + http:Request request = new; + json jsonBody = check payload.cloneWithType(json); + request.setPayload(jsonBody); + PostAlertsResponse response = check self.clientEp->post(path, request, headers = accHeaders, targetType=PostAlertsResponse); + return response; + } + # List all Subusers + # + # + username - The username of this subuser. + # + 'limit - The number of results you would like to get in each request. + # + offset - The number of subusers to skip. + # + return - List of Subusers + @display {label: "List All Subusers"} + remote isolated function getSubusers(@display {label: "Username"} string? username = (), @display {label: "Limit"} int? 'limit = (), @display {label: "Offset"} int? offset = ()) returns SubuserArr|error { + string path = string `/subusers`; + map queryParam = {username: username, 'limit: 'limit, offset: offset}; + path = path + check getPathForQueryParam(queryParam); + SubuserArr response = check self.clientEp-> get(path, targetType = SubuserArr); + return response; + } + # Create Subuser + # + # + payload - New subuser details + # + return - Created subuser's details + remote isolated function postSubusers(@display {label: "New Subuser Details"} PostSubusersRequest payload) returns SubuserPost|error { + string path = string `/subusers`; + http:Request request = new; + json jsonBody = check payload.cloneWithType(json); + request.setPayload(jsonBody); + SubuserPost response = check self.clientEp->post(path, request, targetType=SubuserPost); + return response; + } + # Retrieve all blocks + # + # + start_time - Refers start of the time range in unix timestamp when a blocked email was created (inclusive). + # + end_time - Refers end of the time range in unix timestamp when a blocked email was created (inclusive). + # + 'limit - Limit the number of results to be displayed per page. + # + offset - The point in the list to begin displaying results. + # + 'on\-behalf\-of - The subuser's username. This header generates the API call as if the subuser account was making the call. + # + return - List of all blocks + @display {label: "Get Suppression Blocks"} + remote isolated function getSuppressionBlocks(@display {label: "Start Time"} int? start_time = (), @display {label: "End Time"} int? end_time = (), @display {label: "Limit"} int? 'limit = (), @display {label: "Offset"} int? offset = (), @display {label: "Subuser's Username"} string? 'on\-behalf\-of = ()) returns SuppressionBlocksArr|error { + string path = string `/suppression/blocks`; + map queryParam = {start_time: start_time, end_time: end_time, 'limit: 'limit, offset: offset}; + path = path + check getPathForQueryParam(queryParam); + map headerValues = {'on\-behalf\-of: 'on\-behalf\-of}; + map accHeaders = getMapForHeaders(headerValues); + SuppressionBlocksArr response = check self.clientEp-> get(path, accHeaders, targetType = SuppressionBlocksArr); + return response; + } +} + +# Generate query path with query parameter. +# +# + queryParam - Query parameter map +# + return - Returns generated Path or error at failure of client initialization +isolated function getPathForQueryParam(map queryParam) returns string|error { + string[] param = []; + param[param.length()] = "?"; + foreach var [key, value] in queryParam.entries() { + if value is () { + _ = queryParam.remove(key); + } else { + if string:startsWith( key, "'") { + param[param.length()] = string:substring(key, 1, key.length()); + } else { + param[param.length()] = key; + } + param[param.length()] = "="; + if value is string { + string updateV = check url:encode(value, "UTF-8"); + param[param.length()] = updateV; + } else { + param[param.length()] = value.toString(); + } + param[param.length()] = "&"; + } + } + _ = param.remove(param.length()-1); + if param.length() == 1 { + _ = param.remove(0); + } + string restOfPath = string:'join("", ...param); + return restOfPath; +} + +# Generate header map for given header values. +# +# + headerParam - Headers map +# + return - Returns generated map or error at failure of client initialization +isolated function getMapForHeaders(map headerParam) returns map { + map headerMap = {}; + foreach var [key, value] in headerParam.entries() { + if value is string || value is string[] { + headerMap[key] = value; + } + } + return headerMap; +} diff --git a/openapi/sendgrid/openapi.yaml b/openapi/sendgrid/openapi.yaml new file mode 100644 index 000000000..ac1629f49 --- /dev/null +++ b/openapi/sendgrid/openapi.yaml @@ -0,0 +1,1247 @@ +openapi: 3.0.0 +servers: + - url: https://api.sendgrid.com/v3 +info: + description: Client endpoint for Sendgrid API + title: SendGrid v3 API Documentation + version: "3.0" + x-display: + label: Sendgrid Client +externalDocs: + url: https://sendgrid.com/docs/API_Reference/Web_API_v3/index.html +paths: + /mail/send: + post: + description: >- + This endpoint allows you to send email over SendGrid’s v3 Web API, + the most recent version of our API. If you are looking for documentation + about the v2 Mail Send endpoint, please see our [v2 API + Reference](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). + + + * Top level parameters are referred to as "global". + + * Individual fields within the personalizations array will override any other global, or “message level”, parameters that are defined outside of personalizations. + + **SendGrid provides libraries to help you quickly and easily integrate with the v3 Web API in 7 different languages: [C#](https://github.com/sendgrid/sendgrid-csharp), [Go](https://github.com/sendgrid/sendgrid-go), [Java](https://github.com/sendgrid/sendgrid-java), [Node JS](https://github.com/sendgrid/sendgrid-nodejs), [PHP](https://github.com/sendgrid/sendgrid-php), [Python](https://github.com/sendgrid/sendgrid-python), and [Ruby](https://github.com/sendgrid/sendgrid-ruby).** + + + + For more detailed information about how to use the v3 Mail Send endpoint, please visit our [Classroom](https://sendgrid.com/docs/Classroom/Send/v3_Mail_Send/index.html). + operationId: sendMail + x-display: + label: Send Email + requestBody: + content: + application/json: + schema: + example: + content: + - type: text/html + value:

Hello, world!

+ from: + email: sam.smith@example.com + name: Sam Smith + personalizations: + - subject: Hello, World! + to: + - email: john.doe@example.com + name: John Doe + reply_to: + email: sam.smith@example.com + name: Sam Smith + subject: Hello, World! + properties: + asm: + description: An object allowing you to specify how to handle unsubscribes. + properties: + group_id: + description: The unsubscribe group to associate with this email. + type: integer + x-display: + label: Group Id + groups_to_display: + description: An array containing the unsubscribe groups that you would like to + be displayed on the unsubscribe preferences page. + items: + type: integer + maxItems: 25 + type: array + x-display: + label: Groups to Display + required: + - group_id + type: object + attachments: + description: An array of objects in which you can specify any attachments you + want to include. + x-display: + label: Attachments + items: + properties: + content: + description: The Base64 encoded content of the attachment. + minLength: 1 + type: string + x-display: + label: Content + content_id: + description: The content id for the attachment. This is used when the + disposition is set to “inline” and the attachment is + an image, allowing the file to be displayed within the + body of your email. + type: string + x-display: + label: Content Id + disposition: + default: attachment + description: The content-disposition of the attachment specifying how you would + like the attachment to be displayed. For example, + “inline” results in the attached file being displayed + automatically within the message while “attachment” + results in the attached file requiring some action to + be taken before it is displayed (e.g. opening or + downloading the file). + x-display: + label: Disposition + enum: + - inline + - attachment + type: string + filename: + description: The filename of the attachment. + type: string + x-display: + label: File Name + type: + description: The mime type of the content you are attaching. For example, + “text/plain” or “text/html”. + minLength: 1 + type: string + x-display: + label: Mime Type + required: + - content + - filename + type: object + type: array + batch_id: + description: "This ID represents a batch of emails to be sent at the same time. + Including a batch_id in your request allows you include this + email in that batch, and also enables you to cancel or pause + the delivery of that batch. For more information, see + https://sendgrid.com/docs/API_Reference/Web_API_v3/cancel_s\ + chedule_send.html " + type: string + x-display: + label: Batch Id + categories: + description: "An array of category names for this message. Each category name + may not exceed 255 characters. " + x-display: + label: Categories + items: + maxLength: 255 + type: string + maxItems: 10 + type: array + uniqueItems: true + content: + description: An array in which you may specify the content of your email. You + can include multiple mime types of content, but you must + specify at least one mime type. To include more than one + mime type, simply add another object to the array containing + the `type` and `value` parameters. + x-display: + label: Content + items: + properties: + type: + description: The mime type of the content you are including in your email. For + example, “text/plain” or “text/html”. + minLength: 1 + type: string + x-display: + label: Type + value: + description: The actual content of the specified mime type that you are + including in your email. + minLength: 1 + type: string + x-display: + label: Value + required: + - type + - value + type: object + type: array + custom_args: + description: Values that are specific to the entire send that will be carried + along with the email and its activity data. Substitutions + will not be made on custom arguments, so any string that is + entered into this parameter will be assumed to be the custom + argument that you would like to be used. This parameter is + overridden by personalizations[x].custom_args if that + parameter has been defined. Total custom args size may not + exceed 10,000 bytes. + type: object + x-display: + label: Custome Arguments + from: + $ref: "#/components/schemas/EmailObject" + description: "Email details" + x-display: + label: From Email + headers: + description: An object containing key/value pairs of header names and the value + to substitute for them. You must ensure these are properly + encoded if they contain unicode characters. Must not be one + of the reserved headers. + type: object + x-display: + label: Headers + ip_pool_name: + description: The IP Pool that you would like to send this email from. + maxLength: 64 + minLength: 2 + type: string + x-display: + label: Ip Pool Name + mail_settings: + description: A collection of different mail settings that you can use to specify + how you would like this email to be handled. + x-display: + label: Mail Settings + properties: + bcc: + description: This allows you to have a blind carbon copy automatically sent to + the specified email address for every email that is + sent. + x-display: + label: BCC + properties: + email: + description: The email address that you would like to receive the BCC. + format: email + type: string + x-display: + label: Email Address + enable: + description: Indicates if this setting is enabled. + type: boolean + x-display: + label: Enable BCC + type: object + bypass_list_management: + description: Allows you to bypass all unsubscribe groups and suppressions to + ensure that the email is delivered to every single + recipient. This should only be used in emergencies when + it is absolutely necessary that every recipient receives + your email. + x-display: + label: Bypass List Management + properties: + enable: + description: Indicates if this setting is enabled. + type: boolean + x-display: + label: Enable + type: object + footer: + description: The default footer that you would like included on every email. + x-display: + label: Footer + properties: + enable: + description: Indicates if this setting is enabled. + type: boolean + x-display: + label: Enable + html: + description: The HTML content of your footer. + type: string + x-display: + label: HTML Content + text: + description: The plain text content of your footer. + type: string + x-display: + label: Text Content + type: object + sandbox_mode: + description: This allows you to send a test email to ensure that your request + body is valid and formatted correctly. + x-display: + label: Sandbox Mode + properties: + enable: + description: Indicates if this setting is enabled. + type: boolean + x-display: + label: Enable + type: object + spam_check: + description: This allows you to test the content of your email for spam. + x-display: + label: Spam Check + properties: + enable: + description: Indicates if this setting is enabled. + type: boolean + x-display: + label: Enable + post_to_url: + description: An Inbound Parse URL that you would like a copy of your email along + with the spam report to be sent to. + x-display: + label: Post to URL + type: string + threshold: + description: The threshold used to determine if your content qualifies as spam + on a scale from 1 to 10, with 10 being most strict, + or most likely to be considered as spam. + maximum: 10 + minimum: 1 + type: integer + x-display: + label: Threshold + type: object + type: object + personalizations: + description: An array of messages and their metadata. Each object within + personalizations can be thought of as an envelope - it + defines who should receive an individual message and how + that message should be handled. + x-display: + label: Personalization + items: + properties: + bcc: + description: An array of recipients who will receive a blind carbon copy of your + email. Each object within this array may contain the + name, but must always contain the email, of a + recipient. + items: + $ref: "#/components/schemas/EmailObject" + description: "Email details" + maxItems: 1000 + type: array + x-display: + label: BCC + cc: + description: An array of recipients who will receive a copy of your email. Each + object within this array may contain the name, but + must always contain the email, of a recipient. + items: + $ref: "#/components/schemas/EmailObject" + description: "Email details" + maxItems: 1000 + type: array + x-display: + label: CC + custom_args: + description: Values that are specific to this personalization that will be + carried along with the email and its activity data. + Substitutions will not be made on custom arguments, so + any string that is entered into this parameter will be + assumed to be the custom argument that you would like + to be used. May not exceed 10,000 bytes. + type: object + x-display: + label: Custome Arguments + headers: + description: "A collection of JSON key/value pairs allowing you to specify + specific handling instructions for your email. You may + not overwrite the following headers: x-sg-id, + x-sg-eid, received, dkim-signature, Content-Type, + Content-Transfer-Encoding, To, From, Subject, + Reply-To, CC, BCC" + type: object + x-display: + label: Headers + send_at: + description: A unix timestamp allowing you to specify when you want your email + to be delivered. Scheduling more than 72 hours in + advance is forbidden. + type: integer + x-display: + label: Send At + subject: + description: The subject of your email. Char length requirements, according to + the RFC - + http://stackoverflow.com/questions/1592291/what-is-the-email-subject-length-limit#answer-1592310 + minLength: 1 + type: string + x-display: + label: Subject + substitutions: + description: A collection of key/value pairs following the pattern + "substitution_tag":"value to substitute". All are + assumed to be strings. These substitutions will apply + to the text and html content of the body of your + email, in addition to the `subject` and `reply-to` + parameters. + maxProperties: 10000 + type: object + x-display: + label: Substitutions + to: + description: An array of recipients. Each object within this array may contain + the name, but must always contain the email, of a + recipient. + x-display: + label: To + items: + $ref: "#/components/schemas/EmailObject" + description: "Email details" + maxItems: 1000 + minItems: 1 + type: array + required: + - to + type: object + maxItems: 1000 + type: array + uniqueItems: false + reply_to: + $ref: "#/components/schemas/EmailObject" + description: "Reply to Email details" + x-display: + label: Reply To + sections: + description: An object of key/value pairs that define block sections of code to + be used as substitutions. + type: object + x-display: + label: Sections + send_at: + description: A unix timestamp allowing you to specify when you want your email + to be delivered. This may be overridden by the + personalizations[x].send_at parameter. Scheduling more ta 72 + hours in advance is forbidden. + type: integer + x-display: + label: Send At + subject: + description: The global, or “message level”, subject of your email. This may be + overridden by personalizations[x].subject. + minLength: 1 + type: string + x-display: + label: Subject + template_id: + description: "The id of a template that you would like to use. If you use a + template that contains a subject and content (either text or + html), you do not need to specify those at the + personalizations nor message level. " + type: string + x-display: + label: Template Id + tracking_settings: + description: Settings to determine how you would like to track the metrics of + how your recipients interact with your email. + x-display: + label: Tracking Settings + properties: + click_tracking: + description: Allows you to track whether a recipient clicked a link in your + email. + x-display: + label: Click Tracking + properties: + enable: + description: Indicates if this setting is enabled. + type: boolean + x-display: + label: Enable + enable_text: + description: Indicates if this setting should be included in the text/plain + portion of your email. + type: boolean + x-display: + label: Enable Text + type: object + ganalytics: + description: Allows you to enable tracking provided by Google Analytics. + x-display: + label: Google Analytics + properties: + enable: + description: Indicates if this setting is enabled. + type: boolean + x-display: + label: Enable + utm_campaign: + description: "The name of the campaign.\t" + type: string + x-display: + label: Campaign Name + utm_content: + description: "Used to differentiate your campaign from advertisements.\t" + type: string + x-display: + label: Campaign Advertisement Content + utm_medium: + description: Name of the marketing medium. (e.g. Email) + type: string + x-display: + label: Marketing Medium + utm_source: + description: Name of the referrer source. (e.g. Google, SomeDomain.com, or + Marketing Email) + type: string + x-display: + label: Referrer Source + utm_term: + description: "Used to identify any paid keywords.\t" + type: string + x-display: + label: UTM Term + type: object + open_tracking: + description: Allows you to track whether the email was opened or not, but + including a single pixel image in the body of the + content. When the pixel is loaded, we can log that the + email was opened. + x-display: + label: Open Tracking + properties: + enable: + description: Indicates if this setting is enabled. + type: boolean + x-display: + label: Enable + substitution_tag: + description: Allows you to specify a substitution tag that you can insert in the + body of your email at a location that you desire. + This tag will be replaced by the open tracking + pixel. + type: string + x-display: + label: Substitution Tag + type: object + subscription_tracking: + description: Allows you to insert a subscription management link at the bottom + of the text and html bodies of your email. If you would + like to specify the location of the link within your + email, you may use the substitution_tag. + x-display: + label: Subscription Tracking + properties: + enable: + description: Indicates if this setting is enabled. + type: boolean + x-display: + label: Enale + html: + description: HTML to be appended to the email, with the subscription tracking + link. You may control where the link is by using the + tag <% %> + type: string + x-display: + label: HTML Content + substitution_tag: + description: "A tag that will be replaced with the unsubscribe URL. for example: + [unsubscribe_url]. If this parameter is used, it + will override both the `text` and `html` parameters. + The URL of the link will be placed at the + substitution tag’s location, with no additional + formatting." + type: string + x-display: + label: Substitution Tag + text: + description: Text to be appended to the email, with the subscription tracking + link. You may control where the link is by using the + tag <% %> + type: string + x-display: + label: Text + type: object + type: object + required: + - personalizations + - from + - subject + - content + type: object + description: Mail content + x-display: + label: Email Content + responses: + "202": + description: "No Content" + "400": + content: + application/json: + schema: + $ref: "#/components/schemas/errors" + description: "" + "401": + content: + application/json: + schema: + $ref: "#/components/schemas/errors" + description: "" + "413": + content: + application/json: + schema: + $ref: "#/components/schemas/errors" + description: "" + security: + - Authorization: [] + summary: Send Mail + tags: + - Mail Send + /alerts: + get: + description: >- + **This endpoint allows you to retieve all of your alerts.** + + + Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics. + + * Usage alerts allow you to set the threshold at which an alert will be sent. + + * Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly". + + + For more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html). + operationId: GET_alerts + x-display: + label: Get All Alerts + parameters: + - $ref: "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" + responses: + "200": + content: + application/json: + examples: + response: + value: + - created_at: 1451498784 + email_to: example1@example.com + id: 46 + percentage: 90 + type: usage_limit + updated_at: 1451498784 + - created_at: 1451498812 + email_to: example2@example.com + frequency: monthly + id: 47 + type: stats_notification + updated_at: 1451498812 + - created_at: 1451520930 + email_to: example3@example.com + frequency: daily + id: 48 + type: stats_notification + updated_at: 1451520930 + schema: + description: The list of alerts. + items: + $ref: '#/components/schemas/AlertResponse' + description: "Details related to alerts" + security: + - Authorization: [] + summary: Retrieve all alerts + tags: + - Alerts + post: + description: >- + **This endpoint allows you to create a new alert.** + + + Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics. There are two types of alerts that can be created with this endpoint: + + + * `usage_limit` allows you to set the threshold at which an alert will be sent. + + * `stats_notification` allows you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly". + + + For more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html). + operationId: POST_alerts + x-display: + label: Create Alert + parameters: + - in: header + description: "The subuser's username. This header generates the API call as if the subuser account was making the call." + name: on-behalf-of + x-display: + label: Subuser's Username + schema: + type: string + requestBody: + content: + application/json: + schema: + example: + email_to: example@example.com + frequency: daily + type: stats_notification + description: "Alert Object" + properties: + email_to: + description: |- + The email address the alert will be sent to. + Example: test@example.com + nullable: true + type: string + x-display: + label: Email To + frequency: + description: >- + Required for stats_notification. How frequently the alert will be + sent. Example: daily + type: string + x-display: + label: Frequency + percentage: + description: >- + Required for usage_alert. When this usage threshold is reached, the + alert will be sent. Example: 90 + type: integer + x-display: + label: Percentage + type: + description: >- + The type of alert you want to create. Can be either usage_limit or + stats_notification. Example: usage_limit + enum: + - stats_notification + - usage_limit + type: string + x-display: + label: Type + required: + - type + - email_to + type: object + description: Alert Content + x-display: + label: Alert Content + responses: + "201": + content: + application/json: + examples: + response: + value: + created_at: 1451520930 + email_to: test@example.com + frequency: daily + id: 48 + type: stats_notification + updated_at: 1451520930 + schema: + properties: + created_at: + description: A Unix timestamp indicating when the alert was created. + type: integer + email_to: + description: The email address that the alert will be sent to. + type: string + frequency: + description: If the alert is of type stats_notification, this indicates how + frequently the stats notifications will be sent. For + example, "daily", "weekly", or "monthly". + type: string + id: + description: The ID of the alert. + type: integer + percentage: + description: "If the alert is of type usage_limit, this indicates the + percentage of email usage that must be reached before the + alert will be sent." + type: integer + type: + description: The type of alert. + type: string + updated_at: + description: A Unix timestamp indicating when the alert was last modified. + type: integer + required: + - created_at + - email_to + - id + - type + - updated_at + type: object + description: "Created alert details" + "400": + content: + application/json: + schema: + properties: + field: + type: string + message: + type: string + type: object + description: "" + security: + - Authorization: [] + summary: Create a new Alert + tags: + - Alerts + /subusers: + get: + description: >- + This endpoint allows you to retrieve a list of all of your + subusers. You can choose to retrieve specific subusers as well as limit + the results that come back from the API. + + + For more information about Subusers: + + + * [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html) + + * [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html) + operationId: GET_subusers + x-display: + label: List All Subusers + parameters: + - description: The username of this subuser. + in: query + name: username + schema: + type: string + x-display: + label: Username + - description: The number of results you would like to get in each request. + in: query + name: limit + schema: + type: integer + x-display: + label: Limit + - description: The number of subusers to skip. + in: query + name: offset + schema: + type: integer + x-display: + label: Offset + responses: + "200": + content: + application/json: + examples: + response: + value: + - disabled: false + email: example@example.com + id: 1234 + username: example_subuser + - disabled: false + email: example2@example.com + id: 1234 + username: example_subuser2 + schema: + items: + $ref: "#/components/schemas/Subuser" + type: array + description: "List of Subusers" + "401": + content: + application/json: + schema: + $ref: "#/components/schemas/global_ErrorResponse" + description: Unexpected error in API call. See HTTP response body for details. + security: + - Authorization: [] + summary: List all Subusers + tags: + - Subusers API + post: + description: >- + This endpoint allows you to retrieve a list of all of your + subusers. You can choose to retrieve specific subusers as well as limit + the results that come back from the API. + + + For more information about Subusers: + + + * [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html) + + * [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html) + operationId: POST_subusers + requestBody: + content: + application/json: + schema: + example: + email: John@example.com + ips: + - 1.1.1.1 + - 2.2.2.2 + password: johns_password + username: John@example.com + properties: + email: + description: The email address of the subuser. + format: email + type: string + x-display: + label: Subuser's Email + ips: + description: The IP addresses that should be assigned to this subuser. + items: + format: ipv4 + type: string + type: array + x-display: + label: Subuser's IP Addresses + password: + description: The password this subuser will use when logging into SendGrid. + type: string + x-display: + label: Password + username: + description: The username for this subuser. + type: string + x-display: + label: Username + required: + - username + - email + - password + - ips + type: object + description: New subuser details + x-display: + label: New Subuser Details + responses: + "200": + content: + application/json: + examples: + response: + value: + authorization_token: "" + credit_allocation: + type: unlimited + email: example@example.com + signup_session_token: "" + user_id: 1234 + username: example_subuser + schema: + $ref: "#/components/schemas/subuser_post" + description: Created subuser's details + "400": + content: + application/json: + examples: + response: + value: + errors: + - message: username exists + - message: unable to validate IPs at this time + schema: + $ref: "#/components/schemas/global_ErrorResponse" + description: "" + "401": + content: + application/json: + schema: + $ref: "#/components/schemas/global_ErrorResponse" + description: "" + "403": + content: + application/json: + examples: + response: + value: + errors: + - message: you dont have permission to access this resource + schema: + $ref: "#/components/schemas/global_ErrorResponse" + description: "" + "500": + content: + application/json: + examples: + response: + value: + errors: + - message: unable to validate IPs at this time + schema: + type: object + description: "" + security: + - Authorization: [] + summary: Create Subuser + tags: + - Subusers API + "/suppression/blocks": + get: + description: >- + **This endpoint allows you to retrieve a list of all email + addresses that are currently on your blocks list.** + + + There are several causes for [blocked](https://sendgrid.com/docs/Glossary/blocks.html) emails: for example, your mail server IP address is on an ISP blacklist, or blocked by an ISP, or if the receiving server flags the message content. + + + For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html). + operationId: GET_suppression-blocks + x-display: + label: Get Suppression Blocks + parameters: + - description: Refers start of the time range in unix timestamp when a blocked + email was created (inclusive). + in: query + name: start_time + schema: + type: integer + x-display: + label: Start Time + - description: Refers end of the time range in unix timestamp when a blocked email + was created (inclusive). + in: query + name: end_time + schema: + type: integer + x-display: + label: End Time + - description: Limit the number of results to be displayed per page. + in: query + name: limit + schema: + type: integer + x-display: + label: Limit + - description: The point in the list to begin displaying results. + in: query + name: offset + schema: + type: integer + x-display: + label: Offset + - $ref: "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" + responses: + "200": + content: + application/json: + examples: + response: + value: + - created: 1443651154 + email: example@example.com + reason: "error dialing remote address: dial tcp 10.57.152.165:25: no route to + host" + status: 4.0.0 + schema: + items: + $ref: '#/components/schemas/SuppressionBlocks' + type: array + description: "List of all blocks" + security: + - Authorization: [] + summary: Retrieve all blocks + tags: + - Blocks API +components: + parameters: + trait_onBehalfOfSubuser_on-behalf-of: + description: "The subuser's username. This header generates the API call as if the subuser account was making the call." + in: header + name: on-behalf-of + schema: + default: subuser_ + type: string + x-display: + label: Subuser's Username + schemas: + subuser_post: + description: Created subuser's details + example: + authorization_token: "" + credit_allocation: + type: unlimited + email: example@example.com + signup_session_token: "" + user_id: 1234 + username: example_subuser + properties: + authorization_token: + description: Authorization tokens + type: string + credit_allocation: + description: Credit allocations + properties: + type: + type: string + type: object + email: + description: The email address for this subuser. + format: email + type: string + signup_session_token: + description: Signup session token + type: string + user_id: + description: The user ID for this subuser. + type: number + username: + description: The username of the subuser. + type: string + required: + - username + - user_id + - email + title: Subuser::POST + type: object + global_ErrorResponse: + example: + errors: + - field: field_name + message: Some message here + description: Global error response + properties: + errors: + description: Error details + items: + $ref: '#/components/schemas/ErrorDetails' + type: array + title: "Global: Error Response" + type: object + ErrorDetails: + description: Error details + properties: + field: + description: The field that generated the error. + nullable: true + type: string + message: + description: The error message. + type: string + required: + - message + type: object + SuppressionBlocks: + description: Details of the blocks + properties: + created: + description: A Unix timestamp indicating when the email address was added to the + blocks list. + type: integer + email: + description: The email address that was added to the block list. + type: string + reason: + description: An explanation for the reason of the block. + type: string + status: + description: The status of the block. + type: string + required: + - created + - email + - reason + - status + type: object + Subuser: + description: Details of the subuser + example: + disabled: false + email: example@example.com + id: 1234 + username: example_subuser + properties: + disabled: + description: Whether or not the user is enabled or disabled. + type: boolean + email: + description: The email address to contact this subuser. + format: email + type: string + id: + description: The ID of this subuser. + type: number + username: + description: The name by which this subuser will be referred. + type: string + required: + - disabled + - id + - username + - email + title: List all Subusers for a parent response + type: object + AlertResponse: + description: Alert details + properties: + created_at: + description: A Unix timestamp indicating when the alert was created. + type: integer + email_to: + description: The email address that the alert will be sent to. + type: string + frequency: + description: If the alert is of type stats_notification, this indicates how + frequently the stats notifications will be sent. For + example, "daily", "weekly", or "monthly". + type: string + id: + description: The ID of the alert. + type: integer + percentage: + description: If the alert is of type usage_limit, this indicates the percentage + of email usage that must be reached before the alert + will be sent. + type: integer + type: + description: The type of alert. + enum: + - usage_limit + - stats_notification + type: string + updated_at: + description: A Unix timestamp indicating when the alert was last modified. + type: integer + required: + - created_at + - email_to + - id + - type + type: object + EmailObject: + description: Email details + properties: + email: + description: Email Address + format: email + type: string + name: + description: The name of the person to whom you are sending an email. + type: string + required: + - email + title: Email Object + type: object + errors: + description: List of errors + properties: + errors: + items: + properties: + field: + description: The field that has the error. + nullable: true + type: string + message: + description: The message the API caller will receive. + type: string + type: object + type: array + title: Error Schema + type: object + securitySchemes: + Authorization: + type: http + scheme: bearer diff --git a/openapi/sendgrid/types.bal b/openapi/sendgrid/types.bal new file mode 100644 index 000000000..f38631e96 --- /dev/null +++ b/openapi/sendgrid/types.bal @@ -0,0 +1,102 @@ +// Copyright (c) 2021 WSO2 Inc. (http://www.wso2.org) All Rights Reserved. +// +// WSO2 Inc. licenses this file to you under the Apache License, +// Version 2.0 (the "License"); you may not use this file except +// in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +# List of errors +public type Errors record { + record { # The field that has the error. + string? 'field?; # The message the API caller will receive. + string message?;} [] errors?; +}; + +# Email details +public type EmailObject record { + # Email Address + string email; + # The name of the person to whom you are sending an email. + string name?; +}; + +# Details of the subuser +public type Subuser record { + # Whether or not the user is enabled or disabled. + boolean disabled; + # The email address to contact this subuser. + string email; + # The ID of this subuser. + decimal id; + # The name by which this subuser will be referred. + string username; +}; + +# Alert details +public type AlertResponse record { + # A Unix timestamp indicating when the alert was created. + int created_at; + # The email address that the alert will be sent to. + string email_to; + # If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example, "daily", "weekly", or "monthly". + string frequency?; + # The ID of the alert. + int id; + # If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent. + int percentage?; + # The type of alert. + string 'type; + # A Unix timestamp indicating when the alert was last modified. + int updated_at?; +}; + +# Error details +public type ErrorDetails record { + # The field that generated the error. + string? 'field?; + # The error message. + string message; +}; + +# Global error response +public type GlobalErrorresponse record { + # Error details + ErrorDetails[] errors?; +}; + +# Details of the blocks +public type SuppressionBlocks record { + # A Unix timestamp indicating when the email address was added to the blocks list. + int created; + # The email address that was added to the block list. + string email; + # An explanation for the reason of the block. + string reason; + # The status of the block. + string status; +}; + +# Created subuser's details +public type SubuserPost record { + # Authorization tokens + string authorization_token?; + # Credit allocations + record { string 'type?;} credit_allocation?; + # The email address for this subuser. + string email; + # Signup session token + string signup_session_token?; + # The user ID for this subuser. + decimal user_id; + # The username of the subuser. + string username; +}; From 2a966866e78a1f27c5b55c1ac920d55aaded244d Mon Sep 17 00:00:00 2001 From: aneeshafedo Date: Fri, 18 Jun 2021 18:32:38 +0530 Subject: [PATCH 07/14] remove checkpanic --- openapi/spotify/client.bal | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/openapi/spotify/client.bal b/openapi/spotify/client.bal index c8c637dd7..6853e64fd 100644 --- a/openapi/spotify/client.bal +++ b/openapi/spotify/client.bal @@ -37,7 +37,7 @@ public client class Client { remote isolated function getMyPlaylists(@display {label: "Limit"} int? 'limit = (), @display {label: "Offset"} int? offset = ()) returns CurrentPlaylistDetails|error { string path = string `/me/playlists`; map queryParam = {'limit: 'limit, offset: offset}; - path = path + getPathForQueryParam(queryParam); + path = path + check getPathForQueryParam(queryParam); CurrentPlaylistDetails response = check self.clientEp-> get(path, targetType = CurrentPlaylistDetails); return response; } @@ -45,7 +45,7 @@ public client class Client { remote isolated function getPlaylistById(@display {label: "Playlist Id"} string playlist_id, @display {label: "Market"} string? market = (), @display {label: "Fields to Return"} string? fields = (), @display {label: "Additional Types"} string? additional_types = ()) returns PlaylistObject|error { string path = string `/playlists/${playlist_id}`; map queryParam = {market: market, fields: fields, additional_types: additional_types}; - path = path + getPathForQueryParam(queryParam); + path = path + check getPathForQueryParam(queryParam); PlaylistObject response = check self.clientEp-> get(path, targetType = PlaylistObject); return response; } @@ -76,7 +76,7 @@ public client class Client { remote isolated function getPlaylistTracks(@display {label: "Playlist Id"} string playlist_id, @display {label: "Market"} string market, @display {label: "Fields to Return"} string? fields = (), @display {label: "Limit"} int? 'limit = (), @display {label: "Offset"} int? offset = (), string? additional_types = ()) returns PlaylistTrackDetails|error { string path = string `/playlists/${playlist_id}/tracks`; map queryParam = {market: market, fields: fields, 'limit: 'limit, offset: offset, additional_types: additional_types}; - path = path + getPathForQueryParam(queryParam); + path = path + check getPathForQueryParam(queryParam); PlaylistTrackDetails response = check self.clientEp-> get(path, targetType = PlaylistTrackDetails); return response; } @@ -84,7 +84,7 @@ public client class Client { remote isolated function reorderOrReplacePlaylistTracks(@display {label: "Playlist Id"} string playlist_id, PlayListReorderDetails payload, @display {label: "Track URIs"} string? uris = ()) returns SnapshotIdObject|error { string path = string `/playlists/${playlist_id}/tracks`; map queryParam = {uris: uris}; - path = path + getPathForQueryParam(queryParam); + path = path + check getPathForQueryParam(queryParam); http:Request request = new; json jsonBody = check payload.cloneWithType(json); request.setPayload(jsonBody); @@ -95,7 +95,7 @@ public client class Client { remote isolated function getPlayslistsByUserID(@display {label: "User Id"} string user_id, @display {label: "Limit"} int? 'limit = (), @display {label: "Offset"} int? offset = ()) returns UserPlayListDetails|error { string path = string `/users/${user_id}/playlists`; map queryParam = {'limit: 'limit, offset: offset}; - path = path + getPathForQueryParam(queryParam); + path = path + check getPathForQueryParam(queryParam); UserPlayListDetails response = check self.clientEp-> get(path, targetType = UserPlayListDetails); return response; } @@ -110,7 +110,7 @@ public client class Client { } } -isolated function getPathForQueryParam(map queryParam) returns string { +isolated function getPathForQueryParam(map queryParam) returns string|error { string[] param = []; param[param.length()] = "?"; foreach var [key, value] in queryParam.entries() { @@ -124,7 +124,7 @@ isolated function getPathForQueryParam(map queryParam) returns str } param[param.length()] = "="; if value is string { - string updateV = checkpanic url:encode(value, "UTF-8"); + string updateV = check url:encode(value, "UTF-8"); param[param.length()] = updateV; } else { param[param.length()] = value.toString(); From 230557ccea3a183a5365599629dca84c665746e9 Mon Sep 17 00:00:00 2001 From: aneeshafedo Date: Fri, 18 Jun 2021 19:12:36 +0530 Subject: [PATCH 08/14] add get spam reports function --- openapi/sendgrid/Package.md | 1 + openapi/sendgrid/client.bal | 20 +++++++++ openapi/sendgrid/openapi.yaml | 85 +++++++++++++++++++++++++++++++++++ openapi/sendgrid/types.bal | 10 +++++ 4 files changed, 116 insertions(+) diff --git a/openapi/sendgrid/Package.md b/openapi/sendgrid/Package.md index 5518e5093..83f7124c3 100644 --- a/openapi/sendgrid/Package.md +++ b/openapi/sendgrid/Package.md @@ -10,6 +10,7 @@ The WorldBank connector consume the data exposed in https://api.sendgrid.com/v3. - List all Subusers - Create Subuser - Retrieve all Blocks +- Get Suppression Spam Reports ## Compatibility diff --git a/openapi/sendgrid/client.bal b/openapi/sendgrid/client.bal index 490ccfcbc..53220f2d0 100644 --- a/openapi/sendgrid/client.bal +++ b/openapi/sendgrid/client.bal @@ -159,6 +159,8 @@ public type PostSubusersRequest record { public type SuppressionBlocksArr SuppressionBlocks[]; +public type SpamReportDetailsArr SpamReportDetails[]; + # Client endpoint for Sendgrid API # # + clientEp - Connector http endpoint @@ -254,6 +256,24 @@ public client class Client { SuppressionBlocksArr response = check self.clientEp-> get(path, accHeaders, targetType = SuppressionBlocksArr); return response; } + # Retrieve all spam reports + # + # + start_time - Refers start of the time range in unix timestamp when a spam report was created (inclusive). + # + end_time - Refers end of the time range in unix timestamp when a spam report was created (inclusive). + # + 'limit - Limit the number of results to be displayed per page. + # + offset - Paging offset. The point in the list to begin displaying results. + # + 'on\-behalf\-of - The subuser's username. This header generates the API call as if the subuser account was making the call. + # + return - Received spam reports + @display {label: "Get Suppression Spam Reports"} + remote isolated function getSuppressionSpamReports(@display {label: "Start Time"} int? start_time = (), @display {label: "End Time"} int? end_time = (), @display {label: "Limit"} int? 'limit = (), @display {label: "Offset"} int? offset = (), @display {label: "Subuser's Username"} string? 'on\-behalf\-of = ()) returns SpamReportDetailsArr|error { + string path = string `/suppression/spam_reports`; + map queryParam = {start_time: start_time, end_time: end_time, 'limit: 'limit, offset: offset}; + path = path + check getPathForQueryParam(queryParam); + map headerValues = {'on\-behalf\-of: 'on\-behalf\-of}; + map accHeaders = getMapForHeaders(headerValues); + SpamReportDetailsArr response = check self.clientEp-> get(path, accHeaders, targetType = SpamReportDetailsArr); + return response; + } } # Generate query path with query parameter. diff --git a/openapi/sendgrid/openapi.yaml b/openapi/sendgrid/openapi.yaml index ac1629f49..8b26f5ff4 100644 --- a/openapi/sendgrid/openapi.yaml +++ b/openapi/sendgrid/openapi.yaml @@ -1045,6 +1045,74 @@ paths: summary: Retrieve all blocks tags: - Blocks API + "/suppression/spam_reports": + get: + description: >- + **This endpoint allows you to retrieve all spam reports.** + + + [Spam reports](https://sendgrid.com/docs/Glossary/spam_reports.html) happen when a recipient indicates that they think your email is [spam](https://sendgrid.com/docs/Glossary/spam.html) and then their email provider reports this to SendGrid. + + + For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html). + operationId: GET_suppression-spam_reports + x-display: + label: Get Suppression Spam Reports + parameters: + - description: Refers start of the time range in unix timestamp when a spam report + was created (inclusive). + in: query + name: start_time + schema: + type: integer + x-display: + label: Start Time + - description: Refers end of the time range in unix timestamp when a spam report + was created (inclusive). + in: query + name: end_time + schema: + type: integer + x-display: + label: End Time + - description: Limit the number of results to be displayed per page. + in: query + name: limit + schema: + type: integer + x-display: + label: Limit + - description: Paging offset. The point in the list to begin displaying results. + in: query + name: offset + schema: + type: integer + x-display: + label: Offset + - $ref: "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" + responses: + "200": + content: + application/json: + examples: + response: + value: + - created: 1443651141 + email: user1@example.com + ip: 10.63.202.100 + - created: 1443651154 + email: user2@example.com + ip: 10.63.202.100 + schema: + items: + $ref: '#/components/schemas/SpamReportDetails' + type: array + description: "Received spam reports" + security: + - Authorization: [] + summary: Retrieve all spam reports + tags: + - Spam Reports API components: parameters: trait_onBehalfOfSubuser_on-behalf-of: @@ -1057,6 +1125,23 @@ components: x-display: label: Subuser's Username schemas: + SpamReportDetails: + description: Spam report details + properties: + created: + description: A Unix timestamp indicating when the spam report was made. + type: integer + email: + description: The email address of the recipient who marked your message as spam. + type: string + ip: + description: The IP address that the message was sent on. + type: string + required: + - created + - email + - ip + type: object subuser_post: description: Created subuser's details example: diff --git a/openapi/sendgrid/types.bal b/openapi/sendgrid/types.bal index f38631e96..bef5d4220 100644 --- a/openapi/sendgrid/types.bal +++ b/openapi/sendgrid/types.bal @@ -59,6 +59,16 @@ public type AlertResponse record { int updated_at?; }; +# Spam report details +public type SpamReportDetails record { + # A Unix timestamp indicating when the spam report was made. + int created; + # The email address of the recipient who marked your message as spam. + string email; + # The IP address that the message was sent on. + string ip; +}; + # Error details public type ErrorDetails record { # The field that generated the error. From 595f8e4cda5c2a0958f0e950a22c9a0cf757c59b Mon Sep 17 00:00:00 2001 From: aneeshafedo Date: Fri, 18 Jun 2021 19:59:27 +0530 Subject: [PATCH 09/14] add delete and update functions --- openapi/sendgrid/Package.md | 3 + openapi/sendgrid/client.bal | 70 +++++++++++++++ openapi/sendgrid/openapi.yaml | 165 ++++++++++++++++++++++++++++++++++ openapi/sendgrid/types.bal | 1 + 4 files changed, 239 insertions(+) diff --git a/openapi/sendgrid/Package.md b/openapi/sendgrid/Package.md index 83f7124c3..06b9ad965 100644 --- a/openapi/sendgrid/Package.md +++ b/openapi/sendgrid/Package.md @@ -7,8 +7,11 @@ The WorldBank connector consume the data exposed in https://api.sendgrid.com/v3. - Send Mail - Retrieve all Alerts - Create a new Alert +- Update Alert by Id +- Delete Alert by Id - List all Subusers - Create Subuser +- Delete Subuser by Name - Retrieve all Blocks - Get Suppression Spam Reports diff --git a/openapi/sendgrid/client.bal b/openapi/sendgrid/client.bal index 53220f2d0..c0aba8281 100644 --- a/openapi/sendgrid/client.bal +++ b/openapi/sendgrid/client.bal @@ -143,6 +143,34 @@ public type PostAlertsResponse record { int updated_at; }; +# Alert content to update +public type UpdateAlertbyIdRequest record { + # The new email address you want your alert to be sent to. + string email_to?; + # The new frequency at which to send the stats_notification alert. Example: monthly + string frequency?; + # The new percentage threshold at which the usage_limit alert will be sent. Example: 90 + int percentage?; +}; + +# Updated alert details +public type UpdateAlertbyIdResponse record { + # A Unix timestamp indicating when the alert was created. + int created_at; + # The email address that the alert will be sent to. + string email_to; + # If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example: "daily", "weekly", or "monthly". + string frequency?; + # The ID of the alert. + int id; + # If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent. + int percentage?; + # The type of alert. + string 'type; + # A Unix timestamp indicating when the alert was last modified. + int updated_at; +}; + public type SubuserArr Subuser[]; # New subuser details @@ -212,6 +240,37 @@ public client class Client { PostAlertsResponse response = check self.clientEp->post(path, request, headers = accHeaders, targetType=PostAlertsResponse); return response; } + # Delete an alert + # + # + alert_id - The ID of the alert you would like to retrieve. + # + 'on\-behalf\-of - The subuser's username. This header generates the API call as if the subuser account was making the call. + # + return - Succesful - No Content + @display {label: "Delete Alert by Id"} + remote isolated function deleteAlertById(@display {label: "Alert Id"} int alert_id, @display {label: "Subuser's Username"} string? 'on\-behalf\-of = ()) returns error? { + string path = string `/alerts/${alert_id}`; + map headerValues = {'on\-behalf\-of: 'on\-behalf\-of}; + map accHeaders = getMapForHeaders(headerValues); + http:Request request = new; + //TODO: Update the request as needed; + _ = check self.clientEp-> delete(path, request, headers = accHeaders, targetType=http:Response); + } + # Update an alert + # + # + alert_id - The ID of the alert you would like to retrieve. + # + payload - Alert content to update + # + 'on\-behalf\-of - The subuser's username. This header generates the API call as if the subuser account was making the call. + # + return - Updated alert details + @display {label: "Update Alert by Id"} + remote isolated function updateAlertbyId(@display {label: "Alert Id"} int alert_id, UpdateAlertbyIdRequest payload, @display {label: "Subuser's Username"} string? 'on\-behalf\-of = ()) returns UpdateAlertbyIdResponse|error { + string path = string `/alerts/${alert_id}`; + map headerValues = {'on\-behalf\-of: 'on\-behalf\-of}; + map accHeaders = getMapForHeaders(headerValues); + http:Request request = new; + json jsonBody = check payload.cloneWithType(json); + request.setPayload(jsonBody); + UpdateAlertbyIdResponse response = check self.clientEp->patch(path, request, headers = accHeaders, targetType=UpdateAlertbyIdResponse); + return response; + } # List all Subusers # # + username - The username of this subuser. @@ -238,6 +297,17 @@ public client class Client { SubuserPost response = check self.clientEp->post(path, request, targetType=SubuserPost); return response; } + # Delete a subuser + # + # + subuser_name - Subuser name + # + return - Successful - No Content + @display {label: "Update Subuser by Subuser Name"} + remote isolated function deleteSubuserByName(@display {label: "Subuser Name"} string subuser_name) returns error? { + string path = string `/subusers/${subuser_name}`; + http:Request request = new; + //TODO: Update the request as needed; + _ = check self.clientEp-> delete(path, request, targetType =http:Response); + } # Retrieve all blocks # # + start_time - Refers start of the time range in unix timestamp when a blocked email was created (inclusive). diff --git a/openapi/sendgrid/openapi.yaml b/openapi/sendgrid/openapi.yaml index 8b26f5ff4..eb975d999 100644 --- a/openapi/sendgrid/openapi.yaml +++ b/openapi/sendgrid/openapi.yaml @@ -786,6 +786,136 @@ paths: summary: Create a new Alert tags: - Alerts + "/alerts/{alert_id}": + delete: + description: >- + **This endpoint allows you to delete an alert.** + Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics. + * Usage alerts allow you to set the threshold at which an alert will be sent. + * Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly". + For more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html). + operationId: deleteAlertById + x-display: + label: Delete Alert by Id + parameters: + - description: The ID of the alert you would like to retrieve. + in: path + name: alert_id + required: true + schema: + type: integer + x-display: + label: Alert Id + - $ref: "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" + responses: + "204": + description: "Succesful - No Content" + security: + - Authorization: [] + summary: Delete an alert + tags: + - Alerts + patch: + description: >- + **This endpoint allows you to update an alert.** + Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics. + * Usage alerts allow you to set the threshold at which an alert will be sent. + * Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly". + For more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html). + operationId: updateAlertbyId + x-display: + label: Update Alert by Id + parameters: + - description: The ID of the alert you would like to retrieve. + in: path + name: alert_id + required: true + schema: + type: integer + x-display: + label: Alert Id + - $ref: "#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of" + requestBody: + content: + application/json: + schema: + example: + email_to: example@example.com + properties: + email_to: + description: |- + The new email address you want your alert to be sent to. + Example: test@example.com + type: string + frequency: + description: >- + The new frequency at which to send the stats_notification alert. + Example: monthly + type: string + percentage: + description: >- + The new percentage threshold at which the usage_limit alert will be + sent. + Example: 90 + type: integer + type: object + description: Alert content to update + responses: + "200": + content: + application/json: + examples: + response: + value: + created_at: 1451520930 + email_to: example@example.com + frequency: daily + id: 48 + type: stats_notification + updated_at: 1451522691 + schema: + properties: + created_at: + description: A Unix timestamp indicating when the alert was created. + type: integer + email_to: + description: The email address that the alert will be sent to. + type: string + frequency: + description: 'If the alert is of type stats_notification, this indicates how + frequently the stats notifications will be sent. For + example: "daily", "weekly", or "monthly".' + type: string + id: + description: The ID of the alert. + type: integer + percentage: + description: If the alert is of type usage_limit, this indicates the percentage + of email usage that must be reached before the alert will + be sent. + type: integer + type: + description: The type of alert. + enum: + - usage_alert + - stats_notification + type: string + updated_at: + description: A Unix timestamp indicating when the alert was last modified. + type: integer + required: + - created_at + - email_to + - id + - type + - updated_at + type: object + description: "Updated alert details" + security: + - Authorization: [] + summary: Update an alert + tags: + - Alerts /subusers: get: description: >- @@ -977,6 +1107,40 @@ paths: summary: Create Subuser tags: - Subusers API + "/subusers/{subuser_name}": + delete: + description: >- + This endpoint allows you to delete a subuser. This is a permanent + action, once deleted a subuser cannot be retrieved. + For more information about Subusers: + * [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html) + * [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html) + operationId: deleteSubuserByName + x-display: + label: Update Subuser by Subuser Name + responses: + "204": + description: "Successful - No Content" + "401": + content: + application/json: + schema: + $ref: "#/components/schemas/global_ErrorResponse" + description: "" + security: + - Authorization: [] + summary: Delete a subuser + tags: + - Subusers API + parameters: + - in: path + name: subuser_name + required: true + schema: + type: string + x-display: + label: Subuser Name + description: Subuser name "/suppression/blocks": get: description: >- @@ -1313,6 +1477,7 @@ components: description: List of errors properties: errors: + description: Error message items: properties: field: diff --git a/openapi/sendgrid/types.bal b/openapi/sendgrid/types.bal index bef5d4220..cf546b841 100644 --- a/openapi/sendgrid/types.bal +++ b/openapi/sendgrid/types.bal @@ -16,6 +16,7 @@ # List of errors public type Errors record { + # Error message record { # The field that has the error. string? 'field?; # The message the API caller will receive. string message?;} [] errors?; From 0eebc7aca28d9f29ea79f6f5fcb93720e2cb1135 Mon Sep 17 00:00:00 2001 From: Kanishka <123kanishka@gmail.com> Date: Fri, 18 Jun 2021 20:22:27 +0530 Subject: [PATCH 10/14] code build task added --- build.gradle | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/build.gradle b/build.gradle index e4dd5c5ce..e07f2fbab 100644 --- a/build.gradle +++ b/build.gradle @@ -25,6 +25,10 @@ if (project.hasProperty("remote")){ remote = new Boolean(project.property("remote").toString()) } +Utils.loadOpenAPIProperties(project.projectDir.absolutePath) +String openApiPackageDirPath = project.projectDir.absolutePath + "/openapi"; +updatedBallerinaPackages = Utils.findUpdatedBallerinaPackages(openApiPackageDirPath) + // TODO: Remove this cleanup task once the file override enabled // task cleanup { // println "Cleaning up generated code..." @@ -101,6 +105,33 @@ if (project.hasProperty("remote")){ // } // } +// Temporarily added. +task codeBuild { + // Pulling slalpha5 distribution if not available + if (project.hasProperty("remote") ) { + if (remote) { + exec { + commandLine 'sh', '-c', "${ballerinaDistributionPath}/bin/bal dist pull slalpha5" + } + + exec { + commandLine 'sh', '-c', "rm -rf ${ballerinaDistributionPath}/bin/../dependencies/jdk-11.0.8+10-jre" + } + } + } + + // Changing the build distribution to SL Alpha5 + exec { + commandLine 'sh', '-c', "${ballerinaDistributionPath}/bin/bal dist use slalpha5" + } + for (String path : updatedBallerinaPackages) { + println "Code building..." + exec { + commandLine 'sh', '-c', "${ballerinaDistributionPath}/bin/bal build -c ${path}" + } + } +} + task releaseConnector { //TODO: check and remove the snapshot part in the ballerina toml if (project.hasProperty("release") ) { From 42c879619805b4b729005547422786f9f2edfe68 Mon Sep 17 00:00:00 2001 From: Indika Sampath Date: Fri, 18 Jun 2021 23:11:52 +0530 Subject: [PATCH 11/14] Remove checkpanic in the generated code The OpenAPI tool now updated not to generate the code with checkpanic. --- openapi/covid19/client.bal | 22 +++++++++++----------- openapi/openweathermap/client.bal | 8 ++++---- openapi/worldbank/client.bal | 24 ++++++++++++------------ 3 files changed, 27 insertions(+), 27 deletions(-) diff --git a/openapi/covid19/client.bal b/openapi/covid19/client.bal index c495f7287..b5637b4a0 100644 --- a/openapi/covid19/client.bal +++ b/openapi/covid19/client.bal @@ -38,7 +38,7 @@ public client class Client { remote isolated function getGlobalStatus(@display {label: "Yesterday"} string? yesterday = (), @display {label: "Two Days Ago"} string? twoDaysAgo = (), @display {label: "Allow Null"} string? allowNull = ()) returns CovidAll|error { string path = string `/v3/covid-19/all`; map queryParam = {yesterday: yesterday, twoDaysAgo: twoDaysAgo, allowNull: allowNull}; - path = path + getPathForQueryParam(queryParam); + path = path + check getPathForQueryParam(queryParam); CovidAll response = check self.clientEp-> get(path, targetType = CovidAll); return response; } @@ -52,7 +52,7 @@ public client class Client { remote isolated function getUSAStatusByState(@display {label: "State Name"} string states, @display {label: "Yesterday"} string? yesterday = (), @display {label: "Allow Null"} string? allowNull = ()) returns CovidState|error { string path = string `/v3/covid-19/states/${states}`; map queryParam = {yesterday: yesterday, allowNull: allowNull}; - path = path + getPathForQueryParam(queryParam); + path = path + check getPathForQueryParam(queryParam); CovidState response = check self.clientEp-> get(path, targetType = CovidState); return response; } @@ -68,7 +68,7 @@ public client class Client { remote isolated function getStatusByContinent(@display {label: "Continent"} string continent, @display {label: "Yesterday"} string? yesterday = (), @display {label: "Two Days Ago"} string? twoDaysAgo = (), @display {label: "Strict"} string? strict = (), @display {label: "Allow Null"} string? allowNull = ()) returns CovidContinent|error { string path = string `/v3/covid-19/continents/${continent}`; map queryParam = {yesterday: yesterday, twoDaysAgo: twoDaysAgo, strict: strict, allowNull: allowNull}; - path = path + getPathForQueryParam(queryParam); + path = path + check getPathForQueryParam(queryParam); CovidContinent response = check self.clientEp-> get(path, targetType = CovidContinent); return response; } @@ -84,7 +84,7 @@ public client class Client { remote isolated function getStatusByCountry(@display {label: "Country"} string country, @display {label: "Yesterday"} string? yesterday = (), @display {label: "Two Days Ago"} string? twoDaysAgo = (), @display {label: "Strict"} string? strict = (), @display {label: "Allow Null"} string? allowNull = ()) returns CovidCountry|error { string path = string `/v3/covid-19/countries/${country}`; map queryParam = {yesterday: yesterday, twoDaysAgo: twoDaysAgo, strict: strict, allowNull: allowNull}; - path = path + getPathForQueryParam(queryParam); + path = path + check getPathForQueryParam(queryParam); CovidCountry response = check self.clientEp-> get(path, targetType = CovidCountry); return response; } @@ -96,7 +96,7 @@ public client class Client { remote isolated function getGlobalStatusInTimeSeries(@display {label: "Number Of Days"} string? lastdays = ()) returns CovidHistoricalAll|error { string path = string `/v3/covid-19/historical/all`; map queryParam = {lastdays: lastdays}; - path = path + getPathForQueryParam(queryParam); + path = path + check getPathForQueryParam(queryParam); CovidHistoricalAll response = check self.clientEp-> get(path, targetType = CovidHistoricalAll); return response; } @@ -109,7 +109,7 @@ public client class Client { remote isolated function getTimeSeriesbycountry(@display {label: "Country"} string country, @display {label: "Number Of Days"} string? lastdays = ()) returns CovidHistoricalCountry|error { string path = string `/v3/covid-19/historical/${country}`; map queryParam = {lastdays: lastdays}; - path = path + getPathForQueryParam(queryParam); + path = path + check getPathForQueryParam(queryParam); CovidHistoricalCountry response = check self.clientEp-> get(path, targetType = CovidHistoricalCountry); return response; } @@ -123,7 +123,7 @@ public client class Client { remote isolated function getTimeSeriesByProvince(@display {label: "Country"} string country, @display {label: "Province"} string province, @display {label: "Number of Days"} string? lastdays = ()) returns CovidHistoricalProvince|error { string path = string `/v3/covid-19/historical/${country}/${province}`; map queryParam = {lastdays: lastdays}; - path = path + getPathForQueryParam(queryParam); + path = path + check getPathForQueryParam(queryParam); CovidHistoricalProvince response = check self.clientEp-> get(path, targetType = CovidHistoricalProvince); return response; } @@ -144,7 +144,7 @@ public client class Client { remote isolated function getTotalGlobalVaccineDosesAdministered(@display {label: "Number of Days"} string? lastdays = ()) returns SimpleVaccineTimeline|error { string path = string `/v3/covid-19/vaccine/coverage`; map queryParam = {lastdays: lastdays}; - path = path + getPathForQueryParam(queryParam); + path = path + check getPathForQueryParam(queryParam); SimpleVaccineTimeline response = check self.clientEp-> get(path, targetType = SimpleVaccineTimeline); return response; } @@ -157,7 +157,7 @@ public client class Client { remote isolated function getVaccineCoverageByCountry(@display {label: "Country"} string country, @display {label: "Last Days"} string? lastdays = ()) returns VaccineCountryCoverage|error { string path = string `/v3/covid-19/vaccine/coverage/countries/${country}`; map queryParam = {lastdays: lastdays}; - path = path + getPathForQueryParam(queryParam); + path = path + check getPathForQueryParam(queryParam); VaccineCountryCoverage response = check self.clientEp-> get(path, targetType = VaccineCountryCoverage); return response; } @@ -167,7 +167,7 @@ public client class Client { # # + queryParam - Query parameter map # + return - Returns generated Path or error at failure of client initialization -isolated function getPathForQueryParam(map queryParam) returns string { +isolated function getPathForQueryParam(map queryParam) returns string|error { string[] param = []; param[param.length()] = "?"; foreach var [key, value] in queryParam.entries() { @@ -181,7 +181,7 @@ isolated function getPathForQueryParam(map queryParam) returns str } param[param.length()] = "="; if value is string { - string updateV = checkpanic url:encode(value, "UTF-8"); + string updateV = check url:encode(value, "UTF-8"); param[param.length()] = updateV; } else { param[param.length()] = value.toString(); diff --git a/openapi/openweathermap/client.bal b/openapi/openweathermap/client.bal index c024ab6d5..a030d8903 100644 --- a/openapi/openweathermap/client.bal +++ b/openapi/openweathermap/client.bal @@ -49,7 +49,7 @@ public client class Client { remote isolated function getCurretWeatherData(@display {label: "CityName or StateCode or CountryCode"} string? q = (), @display {label: "City Id"} string? id = (), @display {label: "Latitude"} string? lat = (), @display {label: "Longitude"} string? lon = (), @display {label: "Zip Code"} string? zip = (), @display {label: "Units"} string? units = (), @display {label: "Language"} string? lang = (), @display {label: "Mode"} string? mode = ()) returns CurrentWeatherData|error { string path = string `/weather`; map queryParam = {q: q, id: id, lat: lat, lon: lon, zip: zip, units: units, lang: lang, mode: mode, appid: self.apiKeys["appid"]}; - path = path + getPathForQueryParam(queryParam); + path = path + check getPathForQueryParam(queryParam); CurrentWeatherData response = check self.clientEp-> get(path, targetType = CurrentWeatherData); return response; } @@ -65,7 +65,7 @@ public client class Client { remote isolated function getWeatherForecast(@display {label: "Latitude"} string lat, @display {label: "Longtitude"} string lon, @display {label: "Exclude"} string? exclude = (), @display {label: "Units"} string? units = (), @display {label: "Language"} string? lang = ()) returns WeatherForecast|error { string path = string `/onecall`; map queryParam = {lat: lat, lon: lon, exclude: exclude, units: units, lang: lang, appid: self.apiKeys["appid"]}; - path = path + getPathForQueryParam(queryParam); + path = path + check getPathForQueryParam(queryParam); WeatherForecast response = check self.clientEp-> get(path, targetType = WeatherForecast); return response; } @@ -75,7 +75,7 @@ public client class Client { # # + queryParam - Query parameter map # + return - Returns generated Path or error at failure of client initialization -isolated function getPathForQueryParam(map queryParam) returns string { +isolated function getPathForQueryParam(map queryParam) returns string|error { string[] param = []; param[param.length()] = "?"; foreach var [key, value] in queryParam.entries() { @@ -89,7 +89,7 @@ isolated function getPathForQueryParam(map queryParam) returns str } param[param.length()] = "="; if value is string { - string updateV = checkpanic url:encode(value, "UTF-8"); + string updateV = check url:encode(value, "UTF-8"); param[param.length()] = updateV; } else { param[param.length()] = value.toString(); diff --git a/openapi/worldbank/client.bal b/openapi/worldbank/client.bal index 5a8219431..9bf7ab260 100644 --- a/openapi/worldbank/client.bal +++ b/openapi/worldbank/client.bal @@ -50,7 +50,7 @@ public client class Client { remote isolated function getPopulation(@display {label: "Date"} string? date = (), @display {label: "Page Number"} int? page = (), @display {label: "Per Page Record Count"} int? per_page = ()) returns CountryPopulation[]|error { string path = string `/country/all/indicator/SP.POP.TOTL`; map queryParam = {date: date, format: "json", page: page, per_page: per_page}; - path = path + getPathForQueryParam(queryParam); + path = path + check getPathForQueryParam(queryParam); json[] payloadArr = check self.clientEp-> get(path, targetType = JsonArr); if (payloadArr.length() > 1) { if (payloadArr[1] != ()) { @@ -79,7 +79,7 @@ public client class Client { remote isolated function getPopulationByCountry(@display {label: "Country Code"} string country_code, @display {label: "Date"} string date, @display {label: "Page Number"} int? page = (), @display {label: "Per Page Record Count"} int? per_page = ()) returns CountryPopulation[]|error { string path = string `/country/${country_code}/indicator/SP.POP.TOTL`; map queryParam = {date: date, format: "json", page: page, per_page: per_page}; - path = path + getPathForQueryParam(queryParam); + path = path + check getPathForQueryParam(queryParam); json[] payloadArr = check self.clientEp-> get(path, targetType = JsonArr); if (payloadArr.length() > 1) { if (payloadArr[1] != ()) { @@ -107,7 +107,7 @@ public client class Client { remote isolated function getGDP(string? date = (), @display {label: "Page Number"} int? page = (), @display {label: "Per Page Record Count"} int? per_page = ()) returns GrossDomesticProduct[]|error { string path = string `/country/all/indicator/NY.GDP.MKTP.CD`; map queryParam = {date: date, format: "json", page: page, per_page: per_page}; - path = path + getPathForQueryParam(queryParam); + path = path + check getPathForQueryParam(queryParam); json[] payloadArr = check self.clientEp-> get(path, targetType = JsonArr); if (payloadArr.length() > 1) { if (payloadArr[1] != ()) { @@ -136,7 +136,7 @@ public client class Client { remote isolated function getGDPByCountry(@display {label: "Country Code"} string country_code, string? date = (), @display {label: "Page Number"} int? page = (), @display {label: "Per Page Record Count"} int? per_page = ()) returns GrossDomesticProduct[]|error { string path = string `/country/${country_code}/indicator/NY.GDP.MKTP.CD`; map queryParam = {date: date, format: "json", page: page, per_page: per_page}; - path = path + getPathForQueryParam(queryParam); + path = path + check getPathForQueryParam(queryParam); json[] payloadArr = check self.clientEp-> get(path, targetType = JsonArr); if (payloadArr.length() > 1) { if (payloadArr[1] != ()) { @@ -164,7 +164,7 @@ public client class Client { remote isolated function getAccessToElectricityPercentage(string? date = (), @display {label: "Page Number"} int? page = (), @display {label: "Per Page Record Count"} int? per_page = ()) returns AccessToElectricity[]|error { string path = string `/country/all/indicator/1.1_ACCESS.ELECTRICITY.TOT`; map queryParam = {date: date, format: "json", page: page, per_page: per_page}; - path = path + getPathForQueryParam(queryParam); + path = path + check getPathForQueryParam(queryParam); json[] payloadArr = check self.clientEp-> get(path, targetType = JsonArr); if (payloadArr.length() > 1) { if (payloadArr[1] != ()) { @@ -193,7 +193,7 @@ public client class Client { remote isolated function getAccessToElectricityPercentageByCountry(@display {label: "Country Code"} string country_code, string? date = (), @display {label: "Page Number"} int? page = (), @display {label: "Per Page Record Count"} int? per_page = ()) returns AccessToElectricity[]|error { string path = string `/country/${country_code}/indicator/1.1_ACCESS.ELECTRICITY.TOT`; map queryParam = {date: date, format: "json", page: page, per_page: per_page}; - path = path + getPathForQueryParam(queryParam); + path = path + check getPathForQueryParam(queryParam); json[] payloadArr = check self.clientEp-> get(path, targetType = JsonArr); if (payloadArr.length() > 1) { if (payloadArr[1] != ()) { @@ -221,7 +221,7 @@ public client class Client { remote isolated function getYouthLiteracyRate(@display {label: "Date"} string? date = (), @display {label: "Page Number"} int? page = (), @display {label: "Per Page Record Count"} int? per_page = ()) returns YouthLiteracyRate[]|error { string path = string `/country/all/indicator/1.1_YOUTH.LITERACY.RATE`; map queryParam = {date: date, format: "json", page: page, per_page: per_page}; - path = path + getPathForQueryParam(queryParam); + path = path + check getPathForQueryParam(queryParam); json[] payloadArr = check self.clientEp-> get(path, targetType = JsonArr); if (payloadArr.length() > 1) { if (payloadArr[1] != ()) { @@ -250,7 +250,7 @@ public client class Client { remote isolated function getYouthLiteracyRateByCountry(@display {label: "Country Code"} string country_code, @display {label: "Date"} string? date = (), @display {label: "Page Number"} int? page = (), @display {label: "Per Page Record Count"} int? per_page = ()) returns YouthLiteracyRate[]|error { string path = string `/country/${country_code}/indicator/1.1_YOUTH.LITERACY.RATE`; map queryParam = {date: date, format: "json", page: page, per_page: per_page}; - path = path + getPathForQueryParam(queryParam); + path = path + check getPathForQueryParam(queryParam); json[] payloadArr = check self.clientEp-> get(path, targetType = JsonArr); if (payloadArr.length() > 1) { if (payloadArr[1] != ()) { @@ -278,7 +278,7 @@ public client class Client { remote isolated function getGovernmentExpenditureOnPrimaryEducation(@display {label: "Date"} string? date = (), @display {label: "Page Number"} int? page = (), @display {label: "Per Page Record Count"} int? per_page = ()) returns PrimaryEducationExpenditure[]|error { string path = string `/country/all/indicator/UIS.X.PPP.1.FSGOV`; map queryParam = {date: date, format: "json", page: page, per_page: per_page}; - path = path + getPathForQueryParam(queryParam); + path = path + check getPathForQueryParam(queryParam); json[] payloadArr = check self.clientEp-> get(path, targetType = JsonArr); if (payloadArr.length() > 1) { if (payloadArr[1] != ()) { @@ -307,7 +307,7 @@ public client class Client { remote isolated function getGovernmentExpenditureOnPrimaryEducationByCountry(@display {label: "Country Code"} string country_code, @display {label: "Date"} string? date = (), @display {label: "Page Number"} int? page = (), @display {label: "Per Page Record Count"} int? per_page = ()) returns PrimaryEducationExpenditure[]|error { string path = string `/country/${country_code}/indicator/UIS.X.PPP.1.FSGOV`; map queryParam = {date: date, format: "json", page: page, per_page: per_page}; - path = path + getPathForQueryParam(queryParam); + path = path + check getPathForQueryParam(queryParam); json[] payloadArr = check self.clientEp-> get(path, targetType = JsonArr); if (payloadArr.length() > 1) { if (payloadArr[1] != ()) { @@ -331,7 +331,7 @@ public client class Client { # # + queryParam - Query parameter map # + return - Returns generated Path or error at failure of client initialization -isolated function getPathForQueryParam(map queryParam) returns string { +isolated function getPathForQueryParam(map queryParam) returns string|error { string[] param = []; param[param.length()] = "?"; foreach var [key, value] in queryParam.entries() { @@ -345,7 +345,7 @@ isolated function getPathForQueryParam(map queryParam) returns str } param[param.length()] = "="; if value is string { - string updateV = checkpanic url:encode(value, "UTF-8"); + string updateV = check url:encode(value, "UTF-8"); param[param.length()] = updateV; } else { param[param.length()] = value.toString(); From 094cde51fa4eb742ff96fc04e5382e6f8c78f8ab Mon Sep 17 00:00:00 2001 From: Indika Sampath Date: Sat, 19 Jun 2021 00:15:22 +0530 Subject: [PATCH 12/14] Bump covid19, openweathermap, worldbank connector versions --- openapi/covid19/Ballerina.toml | 2 +- openapi/openweathermap/Ballerina.toml | 2 +- openapi/worldbank/Ballerina.toml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/openapi/covid19/Ballerina.toml b/openapi/covid19/Ballerina.toml index f8e265be4..6bfb1612e 100644 --- a/openapi/covid19/Ballerina.toml +++ b/openapi/covid19/Ballerina.toml @@ -1,7 +1,7 @@ [package] org = "ballerinax" name = "covid19" -version = "0.3.0" +version = "0.4.0" license= ["Apache-2.0"] authors = ["Ballerina"] keywords = ["covid19", "covid19 vaccine"] diff --git a/openapi/openweathermap/Ballerina.toml b/openapi/openweathermap/Ballerina.toml index 5af054b59..8594ef838 100644 --- a/openapi/openweathermap/Ballerina.toml +++ b/openapi/openweathermap/Ballerina.toml @@ -1,7 +1,7 @@ [package] org = "ballerinax" name = "openweathermap" -version = "0.3.0" +version = "0.4.0" authors = ["Ballerina"] license= ["Apache-2.0"] keywords = ["open weather map", "weather data", "weather forecast"] diff --git a/openapi/worldbank/Ballerina.toml b/openapi/worldbank/Ballerina.toml index 7f1f7402c..f37d8baa6 100644 --- a/openapi/worldbank/Ballerina.toml +++ b/openapi/worldbank/Ballerina.toml @@ -1,7 +1,7 @@ [package] org = "ballerinax" name = "worldbank" -version = "0.4.0" +version = "0.5.0" authors = ["Ballerina"] license= ["Apache-2.0"] keywords = ["world bank", "world bank indicators"] From ac1eef362e0acff6fe3841f4f9d2f8dbd50bbd5f Mon Sep 17 00:00:00 2001 From: aneeshafedo Date: Mon, 21 Jun 2021 11:23:58 +0530 Subject: [PATCH 13/14] format header param names --- openapi/sendgrid/Package.md | 2 +- openapi/sendgrid/client.bal | 36 ++++++++++++++++++------------------ 2 files changed, 19 insertions(+), 19 deletions(-) diff --git a/openapi/sendgrid/Package.md b/openapi/sendgrid/Package.md index 06b9ad965..d40832c90 100644 --- a/openapi/sendgrid/Package.md +++ b/openapi/sendgrid/Package.md @@ -2,7 +2,7 @@ Connects to Sendgrid API from Ballerina. ## Module Overview -The WorldBank connector consume the data exposed in https://api.sendgrid.com/v3. It is currently supporting the following operations. +The Sendgrid connector consume the data exposed in https://api.sendgrid.com/v3. It is currently supporting the following operations. - Send Mail - Retrieve all Alerts diff --git a/openapi/sendgrid/client.bal b/openapi/sendgrid/client.bal index c0aba8281..6ee9b206c 100644 --- a/openapi/sendgrid/client.bal +++ b/openapi/sendgrid/client.bal @@ -214,12 +214,12 @@ public client class Client { } # Retrieve all alerts # - # + 'on\-behalf\-of - The subuser's username. This header generates the API call as if the subuser account was making the call. + # + onBehalfOf - The subuser's username. This header generates the API call as if the subuser account was making the call. # + return - Details related to alerts @display {label: "Get All Alerts"} - remote isolated function getAlerts(@display {label: "Subuser's Username"} string? 'on\-behalf\-of = ()) returns AlertResponseArr|error { + remote isolated function getAlerts(@display {label: "Subuser's Username"} string? onBehalfOf = ()) returns AlertResponseArr|error { string path = string `/alerts`; - map headerValues = {'on\-behalf\-of: 'on\-behalf\-of}; + map headerValues = {"on-behalf-of": onBehalfOf}; map accHeaders = getMapForHeaders(headerValues); AlertResponseArr response = check self.clientEp-> get(path, accHeaders, targetType = AlertResponseArr); return response; @@ -227,12 +227,12 @@ public client class Client { # Create a new Alert # # + payload - Alert Content - # + 'on\-behalf\-of - The subuser's username. This header generates the API call as if the subuser account was making the call. + # + onBehalfOf - The subuser's username. This header generates the API call as if the subuser account was making the call. # + return - Created alert details @display {label: "Create Alert"} - remote isolated function postAlerts(@display {label: "Alert Content"} PostAlertsRequest payload, @display {label: "Subuser's Username"} string? 'on\-behalf\-of = ()) returns PostAlertsResponse|error { + remote isolated function postAlerts(@display {label: "Alert Content"} PostAlertsRequest payload, @display {label: "Subuser's Username"} string? onBehalfOf = ()) returns PostAlertsResponse|error { string path = string `/alerts`; - map headerValues = {'on\-behalf\-of: 'on\-behalf\-of}; + map headerValues = {"on-behalf-of": onBehalfOf}; map accHeaders = getMapForHeaders(headerValues); http:Request request = new; json jsonBody = check payload.cloneWithType(json); @@ -243,12 +243,12 @@ public client class Client { # Delete an alert # # + alert_id - The ID of the alert you would like to retrieve. - # + 'on\-behalf\-of - The subuser's username. This header generates the API call as if the subuser account was making the call. + # + onBehalfOf - The subuser's username. This header generates the API call as if the subuser account was making the call. # + return - Succesful - No Content @display {label: "Delete Alert by Id"} - remote isolated function deleteAlertById(@display {label: "Alert Id"} int alert_id, @display {label: "Subuser's Username"} string? 'on\-behalf\-of = ()) returns error? { + remote isolated function deleteAlertById(@display {label: "Alert Id"} int alert_id, @display {label: "Subuser's Username"} string? onBehalfOf = ()) returns error? { string path = string `/alerts/${alert_id}`; - map headerValues = {'on\-behalf\-of: 'on\-behalf\-of}; + map headerValues = {"on-behalf-of": onBehalfOf}; map accHeaders = getMapForHeaders(headerValues); http:Request request = new; //TODO: Update the request as needed; @@ -258,12 +258,12 @@ public client class Client { # # + alert_id - The ID of the alert you would like to retrieve. # + payload - Alert content to update - # + 'on\-behalf\-of - The subuser's username. This header generates the API call as if the subuser account was making the call. + # + onBehalfOf - The subuser's username. This header generates the API call as if the subuser account was making the call. # + return - Updated alert details @display {label: "Update Alert by Id"} - remote isolated function updateAlertbyId(@display {label: "Alert Id"} int alert_id, UpdateAlertbyIdRequest payload, @display {label: "Subuser's Username"} string? 'on\-behalf\-of = ()) returns UpdateAlertbyIdResponse|error { + remote isolated function updateAlertbyId(@display {label: "Alert Id"} int alert_id, UpdateAlertbyIdRequest payload, @display {label: "Subuser's Username"} string? onBehalfOf = ()) returns UpdateAlertbyIdResponse|error { string path = string `/alerts/${alert_id}`; - map headerValues = {'on\-behalf\-of: 'on\-behalf\-of}; + map headerValues = {"on-behalf-of": onBehalfOf}; map accHeaders = getMapForHeaders(headerValues); http:Request request = new; json jsonBody = check payload.cloneWithType(json); @@ -314,14 +314,14 @@ public client class Client { # + end_time - Refers end of the time range in unix timestamp when a blocked email was created (inclusive). # + 'limit - Limit the number of results to be displayed per page. # + offset - The point in the list to begin displaying results. - # + 'on\-behalf\-of - The subuser's username. This header generates the API call as if the subuser account was making the call. + # + onBehalfOf - The subuser's username. This header generates the API call as if the subuser account was making the call. # + return - List of all blocks @display {label: "Get Suppression Blocks"} - remote isolated function getSuppressionBlocks(@display {label: "Start Time"} int? start_time = (), @display {label: "End Time"} int? end_time = (), @display {label: "Limit"} int? 'limit = (), @display {label: "Offset"} int? offset = (), @display {label: "Subuser's Username"} string? 'on\-behalf\-of = ()) returns SuppressionBlocksArr|error { + remote isolated function getSuppressionBlocks(@display {label: "Start Time"} int? start_time = (), @display {label: "End Time"} int? end_time = (), @display {label: "Limit"} int? 'limit = (), @display {label: "Offset"} int? offset = (), @display {label: "Subuser's Username"} string? onBehalfOf = ()) returns SuppressionBlocksArr|error { string path = string `/suppression/blocks`; map queryParam = {start_time: start_time, end_time: end_time, 'limit: 'limit, offset: offset}; path = path + check getPathForQueryParam(queryParam); - map headerValues = {'on\-behalf\-of: 'on\-behalf\-of}; + map headerValues = {"on-behalf-of": onBehalfOf}; map accHeaders = getMapForHeaders(headerValues); SuppressionBlocksArr response = check self.clientEp-> get(path, accHeaders, targetType = SuppressionBlocksArr); return response; @@ -332,14 +332,14 @@ public client class Client { # + end_time - Refers end of the time range in unix timestamp when a spam report was created (inclusive). # + 'limit - Limit the number of results to be displayed per page. # + offset - Paging offset. The point in the list to begin displaying results. - # + 'on\-behalf\-of - The subuser's username. This header generates the API call as if the subuser account was making the call. + # + onBehalfOf - The subuser's username. This header generates the API call as if the subuser account was making the call. # + return - Received spam reports @display {label: "Get Suppression Spam Reports"} - remote isolated function getSuppressionSpamReports(@display {label: "Start Time"} int? start_time = (), @display {label: "End Time"} int? end_time = (), @display {label: "Limit"} int? 'limit = (), @display {label: "Offset"} int? offset = (), @display {label: "Subuser's Username"} string? 'on\-behalf\-of = ()) returns SpamReportDetailsArr|error { + remote isolated function getSuppressionSpamReports(@display {label: "Start Time"} int? start_time = (), @display {label: "End Time"} int? end_time = (), @display {label: "Limit"} int? 'limit = (), @display {label: "Offset"} int? offset = (), @display {label: "Subuser's Username"} string? onBehalfOf = ()) returns SpamReportDetailsArr|error { string path = string `/suppression/spam_reports`; map queryParam = {start_time: start_time, end_time: end_time, 'limit: 'limit, offset: offset}; path = path + check getPathForQueryParam(queryParam); - map headerValues = {'on\-behalf\-of: 'on\-behalf\-of}; + map headerValues = {"on-behalf-of": onBehalfOf}; map accHeaders = getMapForHeaders(headerValues); SpamReportDetailsArr response = check self.clientEp-> get(path, accHeaders, targetType = SpamReportDetailsArr); return response; From aa6b5789994499b9bc7d719bd09450a51299bae5 Mon Sep 17 00:00:00 2001 From: aneeshafedo Date: Mon, 21 Jun 2021 21:56:43 +0530 Subject: [PATCH 14/14] add latest changes --- openapi/spotify/client.bal | 86 ++++++- openapi/spotify/openapi.yaml | 6 + openapi/spotify/types.bal | 484 ++++++++++++++++++++++++----------- 3 files changed, 416 insertions(+), 160 deletions(-) diff --git a/openapi/spotify/client.bal b/openapi/spotify/client.bal index 6853e64fd..96123add1 100644 --- a/openapi/spotify/client.bal +++ b/openapi/spotify/client.bal @@ -1,4 +1,4 @@ -// Copyright (c) 2021, WSO2 Inc. (http://www.wso2.org) All Rights Reserved. +// Copyright (c) 2021 WSO2 Inc. (http://www.wso2.org) All Rights Reserved. // // WSO2 Inc. licenses this file to you under the Apache License, // Version 2.0 (the "License"); you may not use this file except @@ -23,8 +23,9 @@ public type ClientConfig record { http:ClientSecureSocket secureSocketConfig?; }; -type ImageObjectArr ImageObject[]; +public type ImageObjectArr ImageObject[]; +# + clientEp - Connector http endpoint @display {label: "Spotify Client"} public client class Client { http:Client clientEp; @@ -33,6 +34,11 @@ public client class Client { http:Client httpEp = check new (serviceUrl, { auth: clientConfig.authConfig, secureSocket: secureSocketConfig }); self.clientEp = httpEp; } + # Get a List of Current User's Playlists + # + # + 'limit - 'The maximum number of playlists to return. Default: 20. Minimum: 1. Maximum: 50.' + # + offset - 'The index of the first playlist to return. Default: 0 (the first object). Maximum offset: 100.000. Use with `limit` to get the next set of playlists.' + # + return - On success, the HTTP status code in the response header is `200` OK and the response body contains an array of simplified [playlist objects](https://developer.spotify.com/documentation/web-api/reference/#object-simplifiedplaylistobject) (wrapped in a [paging object](https://developer.spotify.com/documentation/web-api/reference/#object-pagingobject)) in JSON format. On error, the header status code is an [error code](https://developer.spotify.com/documentation/web-api/#response-status-codes) and the response body contains an [error object](https://developer.spotify.com/documentation/web-api/#response-schema). Please note that the access token has to be tied to a user. @display {label: "My Playlists"} remote isolated function getMyPlaylists(@display {label: "Limit"} int? 'limit = (), @display {label: "Offset"} int? offset = ()) returns CurrentPlaylistDetails|error { string path = string `/me/playlists`; @@ -41,6 +47,13 @@ public client class Client { CurrentPlaylistDetails response = check self.clientEp-> get(path, targetType = CurrentPlaylistDetails); return response; } + # Get a Playlist + # + # + playlist_id - The [Spotify ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the playlist. + # + market - An [ISO 3166-1 alpha-2 country code](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) or the string `from_token`. Provide this parameter if you want to apply [Track + # + fields - Filters for the query: a comma-separated list of the fields to return. If omitted, all fields are returned. For example, to get just the playlist''s description and URI: `fields=description,uri`. A dot separator can be used to specify non-reoccurring fields, while parentheses can be used to specify reoccurring fields within objects. For example, to get just the added date and user ID of the adder: `fields=tracks.items(added_at,added_by.id)`. Use multiple parentheses to drill down into nested objects, for example: `fields=tracks.items(track(name,href,album(name,href)))`. Fields can be excluded by prefixing them with an exclamation mark, for example: `fields=tracks.items(track(name,href,album(!name,href)))` + # + additional_types - A comma-separated list of item types that your client supports besides the default `track` type. Valid types are: `track` and `episode`. **Note** : This parameter was introduced to allow existing clients to maintain their current behaviour and might be deprecated in the future. In addition to providing this parameter, make sure that your client properly handles cases of new types in the future by checking against the `type` field of each object. + # + return - On success, the response body contains a [playlist object](https://developer.spotify.com/documentation/web-api/reference/#object-playlistobject) in JSON format and the HTTP status code in the response header is `200` OK. If an episode is unavailable in the given `market`, its information will not be included in the response. On error, the header status code is an [error code](https://developer.spotify.com/documentation/web-api/#response-status-codes) and the response body contains an [error object](https://developer.spotify.com/documentation/web-api/#response-schema). Requesting playlists that you do not have the user's authorization to access returns error `403` Forbidden. @display {label: "Playlist By Id"} remote isolated function getPlaylistById(@display {label: "Playlist Id"} string playlist_id, @display {label: "Market"} string? market = (), @display {label: "Fields to Return"} string? fields = (), @display {label: "Additional Types"} string? additional_types = ()) returns PlaylistObject|error { string path = string `/playlists/${playlist_id}`; @@ -49,29 +62,55 @@ public client class Client { PlaylistObject response = check self.clientEp-> get(path, targetType = PlaylistObject); return response; } + # Change a Playlist's Details + # + # + contentType - The content type of the request body: `application/json` + # + playlist_id - The [Spotify ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the playlist. + # + payload - Content to update the playlist + # + return - On success the HTTP status code in the response header is `200` OK. @display {label: "Update Playlist"} - remote isolated function updatePlaylist(@display {label: "Content Type"} string 'Content\-Type, @display {label: "Playlist Id"} string playlist_id, ChangePlayListDetails payload) returns error? { + remote isolated function updatePlaylist(@display {label: "Content Type"} string contentType, @display {label: "Playlist Id"} string playlist_id, ChangePlayListDetails payload) returns error? { string path = string `/playlists/${playlist_id}`; - map accHeaders = {'Content\-Type: 'Content\-Type}; + map headerValues = {"Content-Type": contentType}; + map accHeaders = getMapForHeaders(headerValues); http:Request request = new; json jsonBody = check payload.cloneWithType(json); request.setPayload(jsonBody); _ = check self.clientEp->put(path, request, headers = accHeaders, targetType=http:Response); } + # Get a Playlist Cover Image + # + # + playlist_id - The [Spotify ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the playlist. + # + return - On success, the response body contains a list of [image objects](https://developer.spotify.com/documentation/web-api/reference/#object-imageobject) in JSON format and the HTTP status code in the response header is `200` OK @display {label: "Playlist Cover"} remote isolated function getPlaylistCover(@display {label: "Playlist Id"} string playlist_id) returns ImageObjectArr|error { string path = string `/playlists/${playlist_id}/images`; ImageObjectArr response = check self.clientEp-> get(path, targetType = ImageObjectArr); return response; } + # Upload a Custom Playlist Cover Image + # + # + contentType - The content type of the request body: `image/jpeg` + # + playlist_id - The [Spotify ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the playlist. + # + return - If you get status code `429`, it means that you have sent too many requests. @display {label: "Update Playlist Cover"} - remote isolated function updatePlaylistCover(@display {label: "Content Type"} string 'Content\-Type, @display {label: "Playlist Id"} string playlist_id) returns error? { + remote isolated function updatePlaylistCover(@display {label: "Content Type"} string contentType, @display {label: "Playlist Id"} string playlist_id) returns error? { string path = string `/playlists/${playlist_id}/images`; - map accHeaders = {'Content\-Type: 'Content\-Type}; + map headerValues = {"Content-Type": contentType}; + map accHeaders = getMapForHeaders(headerValues); http:Request request = new; //TODO: Update the request as needed; _ = check self.clientEp-> put(path, request, headers = accHeaders, targetType=http:Response); } + # Get a Playlist's Items + # + # + playlist_id - The [Spotify ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the playlist. + # + market - An [ISO 3166-1 alpha-2 country code](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) or the string `from_token`. Provide this parameter if you want to apply [Track + # + fields - Filters for the query: a comma-separated list of the fields to return. If omitted, all fields are returned. For example, to get just the total number of items and the request limit: + # + 'limit - The maximum number of items to return. Default: 100. Minimum: 1. Maximum: 100. + # + offset - The index of the first item to return. Default: 0 (the first object). + # + additional_types - A comma-separated list of item types that your client supports besides the default `track` type. Valid types are: `track` and `episode`. **Note** : This parameter was introduced to allow existing clients to maintain their current behaviour and might be deprecated in the future. In addition to providing this parameter, make sure that your client properly handles cases of new types in the future by checking against the `type` field of each object. + # + return - On success, the response body contains an array of [track objects](https://developer.spotify.com/documentation/web-api/reference/#object-simplifiedtrackobject) and [episode objects](https://developer.spotify.com/documentation/web-api/reference/#object-simplifiedepisodeobject) (depends on the `additional_types` parameter), wrapped in a [paging object](https://developer.spotify.com/documentation/web-api/reference/#object-pagingobject) in JSON format and the HTTP status code in the response header is `200` OK. If an episode is unavailable in the given `market`, its information will not be included in the response. On error, the header status code is an [error code](https://developer.spotify.com/documentation/web-api/#response-status-codes) and the response body contains an [error object](https://developer.spotify.com/documentation/web-api/#response-schema). Requesting playlists that you do not have the user's authorization to access returns error `403` Forbidden. @display {label: "Playlist Tracks"} remote isolated function getPlaylistTracks(@display {label: "Playlist Id"} string playlist_id, @display {label: "Market"} string market, @display {label: "Fields to Return"} string? fields = (), @display {label: "Limit"} int? 'limit = (), @display {label: "Offset"} int? offset = (), string? additional_types = ()) returns PlaylistTrackDetails|error { string path = string `/playlists/${playlist_id}/tracks`; @@ -80,6 +119,12 @@ public client class Client { PlaylistTrackDetails response = check self.clientEp-> get(path, targetType = PlaylistTrackDetails); return response; } + # Reorder or Replace a Playlist's Items + # + # + playlist_id - The [Spotify ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the playlist. + # + payload - Information needed to reorder the playlist + # + uris - A comma-separated list of [Spotify URIs](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) to set, can be track or episode URIs. For example: `uris=spotify:track:4iV5W9uYEdYUVa79Axb7Rh,spotify:track:1301WleyT98MSxVHPZCA6M,spotify:episode:512ojhOuo1ktJprKbVcKyQ` + # + return - On a successful **reorder** operation, the response body contains a `snapshot_id` in JSON format @display {label: "Reorder or Replace Tracks"} remote isolated function reorderOrReplacePlaylistTracks(@display {label: "Playlist Id"} string playlist_id, PlayListReorderDetails payload, @display {label: "Track URIs"} string? uris = ()) returns SnapshotIdObject|error { string path = string `/playlists/${playlist_id}/tracks`; @@ -91,6 +136,12 @@ public client class Client { SnapshotIdObject response = check self.clientEp->put(path, request, targetType=SnapshotIdObject); return response; } + # Get a List of a User's Playlists + # + # + user_id - The user's [Spotify user ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids). + # + 'limit - The maximum number of playlists to return. Default: 20. Minimum: 1. Maximum: 50. + # + offset - The index of the first playlist to return. Default: 0 (the first object). Maximum offset: 100.000. Use with `limit` to get the next set of playlists. + # + return - On success, the HTTP status code in the response header is `200` OK and the response body contains an array of simplified [playlist objects](https://developer.spotify.com/documentation/web-api/reference/#object-simplifiedplaylistobject) (wrapped in a [paging object](https://developer.spotify.com/documentation/web-api/reference/#object-pagingobject)) in JSON format. On error, the header status code is an [error code](https://developer.spotify.com/documentation/web-api/#response-status-codes) and the response body contains an [error object](https://developer.spotify.com/documentation/web-api/#response-schema). @display {label: "Playlist By User Id"} remote isolated function getPlayslistsByUserID(@display {label: "User Id"} string user_id, @display {label: "Limit"} int? 'limit = (), @display {label: "Offset"} int? offset = ()) returns UserPlayListDetails|error { string path = string `/users/${user_id}/playlists`; @@ -99,6 +150,11 @@ public client class Client { UserPlayListDetails response = check self.clientEp-> get(path, targetType = UserPlayListDetails); return response; } + # Create a Playlist + # + # + user_id - The user's [Spotify user ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids). + # + payload - Content to create playlist + # + return - On success, the response body contains the created [playlist object](https://developer.spotify.com/documentation/web-api/reference/#object-playlistobject) @display {label: "Create Playlist"} remote isolated function createPlaylist(@display {label: "User Id"} string user_id, PlayListDetails payload) returns PlaylistObject|error { string path = string `/users/${user_id}/playlists`; @@ -110,6 +166,10 @@ public client class Client { } } +# Generate query path with query parameter. +# +# + queryParam - Query parameter map +# + return - Returns generated Path or error at failure of client initialization isolated function getPathForQueryParam(map queryParam) returns string|error { string[] param = []; param[param.length()] = "?"; @@ -139,3 +199,17 @@ isolated function getPathForQueryParam(map queryParam) returns str string restOfPath = string:'join("", ...param); return restOfPath; } + +# Generate header map for given header values. +# +# + headerParam - Headers map +# + return - Returns generated map or error at failure of client initialization +isolated function getMapForHeaders(map headerParam) returns map { + map headerMap = {}; + foreach var [key, value] in headerParam.entries() { + if value is string || value is string[] { + headerMap[key] = value; + } + } + return headerMap; +} \ No newline at end of file diff --git a/openapi/spotify/openapi.yaml b/openapi/spotify/openapi.yaml index dcdb0d605..d35f13158 100644 --- a/openapi/spotify/openapi.yaml +++ b/openapi/spotify/openapi.yaml @@ -152,6 +152,7 @@ paths: content: application/json: schema: + description: Content to update the playlist $ref: "#/components/schemas/ChangePlayListDetails" type: object required: false @@ -369,6 +370,7 @@ paths: content: application/json: schema: + description: Information needed to reorder the playlist $ref: "#/components/schemas/PlayListReorderDetails" required: false responses: @@ -486,6 +488,7 @@ paths: content: application/json: schema: + description: Content of the playlist $ref: "#/components/schemas/PlayListDetails" type: object required: true @@ -533,6 +536,7 @@ components: description: Unexpected error schemas: PlayListDetails: + description: Playlist details properties: collaborative: description: Defaults to `false` . If `true` the playlist will be collaborative. Note that to create a collaborative playlist you must also set `public` to `false` . To create collaborative playlists you must have granted `playlist-modify-private` and `playlist-modify-public` [scopes](https://developer.spotify.com/documentation/general/guides/authorization-guide/#list-of-scopes) . @@ -598,6 +602,7 @@ components: type: array type: object PlayListReorderDetails: + description: Information needed to reorder the playlist properties: insert_before: description: |- @@ -666,6 +671,7 @@ components: type: integer type: object ChangePlayListDetails: + description: Content to update the playlist properties: collaborative: description: "If `true` , the playlist will become collaborative and other users will be able to modify the playlist in their Spotify client. *Note: You can only set `collaborative` to `true` on non-public playlists.*" diff --git a/openapi/spotify/types.bal b/openapi/spotify/types.bal index 73f91ce32..0b7ffde11 100644 --- a/openapi/spotify/types.bal +++ b/openapi/spotify/types.bal @@ -1,4 +1,4 @@ -// Copyright (c) 2021, WSO2 Inc. (http://www.wso2.org) All Rights Reserved. +// Copyright (c) 2021 WSO2 Inc. (http://www.wso2.org) All Rights Reserved. // // WSO2 Inc. licenses this file to you under the Apache License, // Version 2.0 (the "License"); you may not use this file except @@ -14,290 +14,466 @@ // specific language governing permissions and limitations // under the License. -public type PlayListDetails record { - boolean collaborative?; - string description?; - string name; - boolean 'public?; -}; - -public type UserPlayListDetails record { - string href?; - SimplifiedPlaylistObject[] items?; - int 'limit?; - string? next?; - int offset?; - string? previous?; - int total?; -}; - -public type PlaylistTrackInsertionDetails record { - int position?; - string[] uris?; -}; - +# Information needed to reorder the playlist public type PlayListReorderDetails record { + # The position where the items should be inserted. int insert_before?; + # The amount of items to be reordered. Defaults to 1 if not set. int range_length?; + # The position of the first item to be reordered. int range_start?; + # The playlist's snapshot ID against which you want to make the changes. string snapshot_id?; + # A comma-separated list of [Spotify URIs](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) to set, can be track or episode URIs. For example: `uris=spotify:track:4iV5W9uYEdYUVa79Axb7Rh,spotify:track:1301WleyT98MSxVHPZCA6M,spotify:episode:512ojhOuo1ktJprKbVcKyQ` string[] uris?; }; -public type PlaylistTrackDetails record { - string href?; - PlaylistTrackObject[] items?; - int 'limit?; - string? next?; - int offset?; - string? previous?; - int total?; -}; - +# Content to update the playlist public type ChangePlayListDetails record { + # If `true` , the playlist will become collaborative and other users will be able to modify the playlist in their Spotify client. *Note: You can only set `collaborative` to `true` on non-public playlists.* boolean collaborative?; + # Value for playlist description as displayed in Spotify Clients and in the Web API. string description?; + # The new name for the playlist, for example `"My New Playlist Title"` string name?; + # If `true` the playlist will be public, if `false` it will be private. boolean 'public?; }; -public type CurrentPlaylistDetails record { - string href?; - SimplifiedPlaylistObject[] items?; - int 'limit?; - string? next?; - int offset?; - string? previous?; - int total?; -}; - -public type PlaylistObject record { - boolean collaborative?; - string description?; +public type LinkedTrackObject record { ExternalUrlObject external_urls?; - FollowersObject followers?; + # A link to the Web API endpoint providing full details of the track. string href?; + # The [Spotify ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the track. string id?; - ImageObject[] images?; - string name?; - PublicUserObject owner?; - boolean 'public?; - string snapshot_id?; - record { string href?; PlaylistTrackObject[] items?; int 'limit?; string? next?; int offset?; string? previous?; int total?;} tracks?; - string 'type?; - string uri?; -}; - -public type ImageObject record { - int height?; - string url?; - int width?; -}; - -public type SnapshotIdObject record { - string snapshot_id?; -}; - -public type ErrorResponseObject record { - ErrorObject _error?; -}; - -public type SimplifiedPlaylistObject record { - boolean collaborative?; - string description?; - ExternalUrlObject external_urls?; - string href?; - string id?; - ImageObject[] images?; - string name?; - PublicUserObject owner?; - boolean 'public?; - string snapshot_id?; - PlaylistTracksRefObject tracks?; + # The object type: "track". string 'type?; + # The [Spotify URI](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the track. string uri?; }; public type PlaylistTrackObject record { + # The date and time the track or episode was added. *Note that some very old playlists may return `null` in this field.* string added_at?; PublicUserObject added_by?; + # Whether this track or episode is a [local file](https://developer.spotify.com/web-api/local-files-spotify-playlists/) or not. boolean is_local?; - anydata track?; -}; - -public type ExternalUrlObject record { - string spotify?; + # Information about the track or episode. + TrackObject|EpisodeObject track?; }; -public type FollowersObject record { - string? href?; - int total?; -}; - -public type PublicUserObject record { - string display_name?; +public type SimplifiedArtistObject record { ExternalUrlObject external_urls?; - FollowersObject followers?; + # A link to the Web API endpoint providing full details of the artist. string href?; + # The [Spotify ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the artist. string id?; - ImageObject[] images?; + # The name of the artist. + string name?; + # The object type: `"artist"` string 'type?; + # The [Spotify URI](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the artist. string uri?; }; -public type ErrorObject record { - string message?; - int status?; -}; - -public type PlaylistTracksRefObject record { - string href?; - int total?; +public type TrackRemovingDetails record { + # The playlist's snapshot ID against which you want to make the changes. The API will validate that the specified items exist and in the specified positions and make the changes, even if more recent changes have been made to the playlist. + string snapshot_id?; + # An array of objects containing [Spotify URIs](https://developer.spotify.com/spotify-documentation/web-api/#spotify-uris-and-ids) of the tracks or episodes to remove. For example: `{ "tracks": [{ "uri": "spotify:track:4iV5W9uYEdYUVa79Axb7Rh" },{ "uri": "spotify:track:1301WleyT98MSxVHPZCA6M" }] }`. A maximum of 100 objects can be sent at once. + string[] tracks; }; public type EpisodeObject record { + # A URL to a 30 second preview (MP3 format) of the episode. `null` if not available. string audio_preview_url?; + # A description of the episode. HTML tags are stripped away from this field, use `html_description` field in case HTML tags are needed. string description?; + # The episode length in milliseconds. int duration_ms?; + # Whether or not the episode has explicit content (true = yes it does; false = no it does not OR unknown). boolean explicit?; ExternalUrlObject external_urls?; + # A link to the Web API endpoint providing full details of the episode. string href?; + # A description of the episode. This field may contain HTML tags. string html_description?; + # The [Spotify ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the episode. string id?; + # The cover art for the episode in various sizes, widest first. ImageObject[] images?; + # True if the episode is hosted outside of Spotify's CDN. boolean is_externally_hosted?; + # True if the episode is playable in the given market. Otherwise false. boolean is_playable?; + # **Note: This field is deprecated and might be removed in the future. Please use the `languages` field instead.** The language used in the episode, identified by a [ISO 639](https://en.wikipedia.org/wiki/ISO_639) code. string language?; + # A list of the languages used in the episode, identified by their [ISO 639](https://en.wikipedia.org/wiki/ISO_639) code. string[] languages?; + # The name of the episode. string name?; + # The date the episode was first released, for example `"1981-12-15"`. Depending on the precision, it might be shown as `"1981"` or `"1981-12"`. string release_date?; + # The precision with which `release_date` value is known: `"year"`, `"month"`, or `"day"`. string release_date_precision?; EpisodeRestrictionObject restrictions?; ResumePointObject resume_point?; SimplifiedShowObject show?; + # The object type: "episode". string 'type?; + # The [Spotify URI](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the episode. string uri?; }; -public type EpisodeRestrictionObject record { - string reason?; +# Playlist details +public type PlayListDetails record { + # Defaults to `false` . If `true` the playlist will be collaborative. Note that to create a collaborative playlist you must also set `public` to `false` . To create collaborative playlists you must have granted `playlist-modify-private` and `playlist-modify-public` [scopes](https://developer.spotify.com/documentation/general/guides/authorization-guide/#list-of-scopes) . + boolean collaborative?; + # value for playlist description as displayed in Spotify Clients and in the Web API. + string description?; + # The name for the new playlist, for example `"Your Coolest Playlist"` . This name does not need to be unique; a user may have several playlists with the same name. + string name; + # Defaults to `true` . If `true` the playlist will be public, if `false` it will be private. To be able to create private playlists, the user must have granted the `playlist-modify-private` [scope](https://developer.spotify.com/documentation/general/guides/authorization-guide/#list-of-scopes) + boolean 'public?; }; -public type ResumePointObject record { - boolean fully_played?; - int resume_position_ms?; +public type ExternalUrlObject record { + # The [Spotify URL](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the object. + string spotify?; }; -public type SimplifiedShowObject record { +public type SimplifiedAlbumObject record { + # The field is present when getting an artist's albums. Possible values are "album", "single", "compilation", "appears_on". Compare to album_type this field represents relationship between the artist and the album. + string album_group?; + # The type of the album: one of "album", "single", or "compilation". + string album_type?; + # The artists of the album. Each artist object includes a link in `href` to more detailed information about the artist. + SimplifiedArtistObject[] artists?; + # The markets in which the album is available: [ISO 3166-1 alpha-2 country codes](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). Note that an album is considered available in a market when at least 1 of its tracks is available in that market. string[] available_markets?; - CopyrightObject[] copyrights?; - string description?; - boolean explicit?; ExternalUrlObject external_urls?; + # A link to the Web API endpoint providing full details of the album. string href?; - string html_description?; + # The [Spotify ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the album. string id?; + # The cover art for the album in various sizes, widest first. ImageObject[] images?; - boolean is_externally_hosted?; - string[] languages?; - string media_type?; + # The name of the album. In case of an album takedown, the value may be an empty string. string name?; - string publisher?; + # The date the album was first released, for example `1981`. Depending on the precision, it might be shown as `1981-12` or `1981-12-15`. + string release_date?; + # The precision with which `release_date` value is known: `year` , `month` , or `day`. + string release_date_precision?; + AlbumRestrictionObject restrictions?; + # The total number of tracks in the album. + int total_tracks?; + # The object type: "album" string 'type?; + # The [Spotify URI](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the album. string uri?; }; +public type FollowersObject record { + # A link to the Web API endpoint providing full details of the followers; `null` if not available. Please note that this will always be set to null, as the Web API does not support it at the moment. + string? href?; + # The total number of followers. + int total?; +}; + public type CopyrightObject record { + # The copyright text for this content. string text?; + # The type of copyright: `C` = the copyright, `P` = the sound recording (performance) copyright. string 'type?; }; -public type SimplifiedArtistObject record { - ExternalUrlObject external_urls?; +public type CurrentPlaylistDetails record { + # A link to the Web API endpoint returning the full result of the request string href?; - string id?; - string name?; - string 'type?; - string uri?; + # The requested data. + SimplifiedPlaylistObject[] items?; + # The maximum number of items in the response (as set in the query or by default). + int 'limit?; + # URL to the next page of items. ( `null` if none) + string? next?; + # The offset of the items returned (as set in the query or by default) + int offset?; + # URL to the previous page of items. ( `null` if none) + string? previous?; + # The total number of items available to return. + int total?; }; -public type SimplifiedAlbumObject record { - string album_group?; - string album_type?; - SimplifiedArtistObject[] artists?; - string[] available_markets?; +public type ErrorResponseObject record { + ErrorObject _error?; +}; + +public type SimplifiedPlaylistObject record { + # `true` if the owner allows other users to modify the playlist. + boolean collaborative?; + # The playlist description. *Only returned for modified, verified playlists, otherwise* `null`. + string description?; ExternalUrlObject external_urls?; + # A link to the Web API endpoint providing full details of the playlist. string href?; + # The [Spotify ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the playlist. string id?; + # Images for the playlist. The array may be empty or contain up to three images. The images are returned by size in descending order. See [Working with Playlists](https://developer.spotify.com/documentation/general/guides/working-with-playlists/). *Note: If returned, the source URL for the image (`url`) is temporary and will expire in less than a day.* ImageObject[] images?; + # The name of the playlist. string name?; - string release_date?; - string release_date_precision?; - AlbumRestrictionObject restrictions?; - int total_tracks?; + PublicUserObject owner?; + # The playlist's public/private status: `true` the playlist is public, `false` the playlist is private, `null` the playlist status is not relevant. For more about public/private status, see [Working with Playlists](https://developer.spotify.com/documentation/general/guides/working-with-playlists/) + boolean 'public?; + # The version identifier for the current playlist. Can be supplied in other requests to target a specific playlist version + string snapshot_id?; + PlaylistTracksRefObject tracks?; + # The object type: "playlist" string 'type?; + # The [Spotify URI](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the playlist. string uri?; }; -public type AlbumRestrictionObject record { +public type PlaylistTrackDetails record { + # A link to the Web API endpoint returning the full result of the request + string href?; + # The requested data. + PlaylistTrackObject[] items?; + # The maximum number of items in the response (as set in the query or by default). + int 'limit?; + # URL to the next page of items. ( `null` if none) + string? next?; + # The offset of the items returned (as set in the query or by default) + int offset?; + # URL to the previous page of items. ( `null` if none) + string? previous?; + # The total number of items available to return. + int total?; +}; + +public type EpisodeRestrictionObject record { + # The reason for the restriction. Supported values: string reason?; }; -public type ArtistObject record { +public type ImageObject record { + # The image height in pixels. If unknown: `null` or not returned. + int height?; + # The source URL of the image. + string url?; + # The image width in pixels. If unknown: `null` or not returned. + int width?; +}; + +public type ErrorObject record { + # A short description of the cause of the error. + string message?; + # The HTTP status code (also returned in the response header; see [Response Status Codes](https://developer.spotify.com/documentation/web-api/#response-status-codes) for more information). + int status?; +}; + +public type PublicUserObject record { + # The name displayed on the user's profile. `null` if not available. + string display_name?; ExternalUrlObject external_urls?; FollowersObject followers?; - string[] genres?; + # A link to the Web API endpoint for this user. string href?; + # The [Spotify user ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for this user. string id?; + # The user's profile image. ImageObject[] images?; - string name?; - int popularity?; + # The object type: "user" string 'type?; + # The [Spotify URI](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for this user. string uri?; }; -public type ExternalIdObject record { - string ean?; - string isrc?; - string upc?; +public type TrackRestrictionObject record { + # The reason for the restriction. Supported values: + string reason?; }; -public type LinkedTrackObject record { - ExternalUrlObject external_urls?; +public type UserPlayListDetails record { + # A link to the Web API endpoint returning the full result of the request string href?; - string id?; - string 'type?; - string uri?; -}; - -public type TrackRemovingDetails record { - string snapshot_id?; - string[] tracks; + # The requested data. + SimplifiedPlaylistObject[] items?; + # The maximum number of items in the response (as set in the query or by default). + int 'limit?; + # URL to the next page of items. ( `null` if none) + string? next?; + # The offset of the items returned (as set in the query or by default) + int offset?; + # URL to the previous page of items. ( `null` if none) + string? previous?; + # The total number of items available to return. + int total?; }; public type TrackObject record { SimplifiedAlbumObject album?; + # The artists who performed the track. Each artist object includes a link in `href` to more detailed information about the artist. ArtistObject[] artists?; + # A list of the countries in which the track can be played, identified by their [ISO 3166-1 alpha-2](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code. string[] available_markets?; + # The disc number (usually `1` unless the album consists of more than one disc). int disc_number?; + # The track length in milliseconds. int duration_ms?; + # Whether or not the track has explicit lyrics ( `true` = yes it does; `false` = no it does not OR unknown). boolean explicit?; ExternalIdObject external_ids?; ExternalUrlObject external_urls?; + # A link to the Web API endpoint providing full details of the track. string href?; + # The [Spotify ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the track. string id?; + # Whether or not the track is from a local file. boolean is_local?; + # Part of the response when [Track Relinking](https://developer.spotify.com/documentation/general/guides/track-relinking-guide/) is applied. If `true` , the track is playable in the given market. Otherwise `false`. boolean is_playable?; LinkedTrackObject linked_from?; + # The name of the track. string name?; + # The popularity of the track. The value will be between 0 and 100, with 100 being the most popular. int popularity?; + # A link to a 30 second preview (MP3 format) of the track. Can be `null` string preview_url?; TrackRestrictionObject restrictions?; + # The number of the track. If an album has several discs, the track number is the number on the specified disc. int track_number?; + # The object type: "track". string 'type?; + # The [Spotify URI](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the track. string uri?; }; -public type TrackRestrictionObject record { +public type ArtistObject record { + ExternalUrlObject external_urls?; + FollowersObject followers?; + # A list of the genres the artist is associated with. For example: `"Prog Rock"` , `"Post-Grunge"`. (If not yet classified, the array is empty.) + string[] genres?; + # A link to the Web API endpoint providing full details of the artist. + string href?; + # The [Spotify ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the artist. + string id?; + # Images of the artist in various sizes, widest first. + ImageObject[] images?; + # The name of the artist. + string name?; + # The popularity of the artist. The value will be between 0 and 100, with 100 being the most popular. The artist's popularity is calculated from the popularity of all the artist's tracks. + int popularity?; + # The object type: `"artist"` + string 'type?; + # The [Spotify URI](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the artist. + string uri?; +}; + +public type PlaylistTrackInsertionDetails record { + # The position to insert the items, a zero-based index. For example, to insert the items in the first position: `position=0` ; to insert the items in the third position: `position=2`. If omitted, the items will be appended to the playlist. Items are added in the order they appear in the uris array. For example: `{"uris": ["spotify:track:4iV5W9uYEdYUVa79Axb7Rh","spotify:track:1301WleyT98MSxVHPZCA6M"], "position": 3}` + int position?; + # A JSON array of the [Spotify URIs](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) to add. For example: `{"uris": ["spotify:track:4iV5W9uYEdYUVa79Axb7Rh","spotify:track:1301WleyT98MSxVHPZCA6M", "spotify:episode:512ojhOuo1ktJprKbVcKyQ"]}` + string[] uris?; +}; + +public type SnapshotIdObject record { + # The snapshot_id can be used to identify your playlist version in future requests. + string snapshot_id?; +}; + +public type PlaylistTracksRefObject record { + # A link to the Web API endpoint where full details of the playlist's tracks can be retrieved. + string href?; + # Number of tracks in the playlist. + int total?; +}; + +public type SimplifiedShowObject record { + # A list of the countries in which the show can be played, identified by their [ISO 3166-1 alpha-2](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code. + string[] available_markets?; + # The copyright statements of the show. + CopyrightObject[] copyrights?; + # A description of the show. HTML tags are stripped away from this field, use `html_description` field in case HTML tags are needed. + string description?; + # Whether or not the show has explicit content (true = yes it does; false = no it does not OR unknown). + boolean explicit?; + ExternalUrlObject external_urls?; + # A link to the Web API endpoint providing full details of the show. + string href?; + # A description of the show. This field may contain HTML tags. + string html_description?; + # The [Spotify ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the show. + string id?; + # The cover art for the show in various sizes, widest first. + ImageObject[] images?; + # True if all of the show's episodes are hosted outside of Spotify's CDN. This field might be `null` in some cases. + boolean is_externally_hosted?; + # A list of the languages used in the show, identified by their [ISO 639](https://en.wikipedia.org/wiki/ISO_639) code. + string[] languages?; + # The media type of the show. + string media_type?; + # The name of the episode. + string name?; + # The publisher of the show. + string publisher?; + # The object type: "show". + string 'type?; + # The [Spotify URI](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the show. + string uri?; +}; + +public type AlbumRestrictionObject record { + # The reason for the restriction. Supported values: string reason?; }; + +public type PlaylistObject record { + # `true` if the owner allows other users to modify the playlist. + boolean collaborative?; + # The playlist description. *Only returned for modified, verified playlists, otherwise* `null`. + string description?; + ExternalUrlObject external_urls?; + FollowersObject followers?; + # A link to the Web API endpoint providing full details of the playlist. + string href?; + # The [Spotify ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the playlist. + string id?; + # Images for the playlist. The array may be empty or contain up to three images. The images are returned by size in descending order. See [Working with Playlists](https://developer.spotify.com/documentation/general/guides/working-with-playlists/). *Note: If returned, the source URL for the image (`url`) is temporary and will expire in less than a day.* + ImageObject[] images?; + # The name of the playlist. + string name?; + PublicUserObject owner?; + # The playlist's public/private status: `true` the playlist is public, `false` the playlist is private, `null` the playlist status is not relevant. For more about public/private status, see [Working with Playlists](https://developer.spotify.com/documentation/general/guides/working-with-playlists/) + boolean 'public?; + # The version identifier for the current playlist. Can be supplied in other requests to target a specific playlist version + string snapshot_id?; + # Information about the tracks of the playlist. Note, a track object may be `null`. This can happen if a track is no longer available. + record { # A link to the Web API endpoint returning the full result of the request + string href?; # The requested data. + PlaylistTrackObject[] items?; # The maximum number of items in the response (as set in the query or by default). + int 'limit?; # URL to the next page of items. ( `null` if none) + string? next?; # The offset of the items returned (as set in the query or by default) + int offset?; # URL to the previous page of items. ( `null` if none) + string? previous?; # The total number of items available to return. + int total?;} tracks?; + # The object type: "playlist" + string 'type?; + # The [Spotify URI](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids) for the playlist. + string uri?; +}; + +public type ResumePointObject record { + # Whether or not the episode has been fully played by the user. + boolean fully_played?; + # The user's most recent position in the episode in milliseconds. + int resume_position_ms?; +}; + +public type ExternalIdObject record { + # [International Article Number](http://en.wikipedia.org/wiki/International_Article_Number_%28EAN%29) + string ean?; + # [International Standard Recording Code](http://en.wikipedia.org/wiki/International_Standard_Recording_Code) + string isrc?; + # [Universal Product Code](http://en.wikipedia.org/wiki/Universal_Product_Code) + string upc?; +};